1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
<?php
/** @file
* This file contains the Query Path extension tools.
*
* Query Path can be extended to support additional features. To do this,
* you need only create a new class that implements {@link Extension}
* and add your own methods. This class can then be registered as an extension.
* It will then be available through Query Path.
*
* For information on building your own extension, see {@link Extension}.
* If you are trying to load an extension you have downloaded, chances are good that
* all you need to do is {@link require_once} the file that contains the extension.
*
* @author M Butcher <matt@aleph-null.tv>
* @license MIT
* @see Extension
* @see ExtensionRegistry::extend()
*/
namespace QueryPath;
/** @addtogroup querypath_extensions Extensions
* The QueryPath extension system and bundled extensions.
*
* Much like jQuery, QueryPath provides a simple extension mechanism that allows
* extensions to auto-register themselves upon being loaded. For a simple example, see
* QPXML. For the internals, see QueryPath::Extension and QueryPath::with().
*/
/**
* A Extension is a tool that extends the capabilities of a Query object.
*
* Extensions to QueryPath should implement the Extension interface. The
* only requirement is that the extension provide a constructor that takes a
* Query object as a parameter.
*
* Here is an example QueryPath extension:
* @code
* <?php
* class StubExtensionOne implements \QueryPath\Extension {
* private $qp = NULL;
* public function __construct(\QueryPath\Query $qp) {
* $this->qp = $qp;
* }
*
* public function stubToe() {
* $this->qp->find(':root')->append('<toe/>')->end();
* return $this->qp;
* }
* }
* ?>
* @endcode
* In this example, the StubExtensionOne class implements Extension.
* The constructor stores a local copyof the Query object. This is important
* if you are planning on fully integrating with QueryPath's Fluent Interface.
*
* Finally, the stubToe() function illustrates how the extension makes use of
* QueryPath's Query object internally, and remains part of the fluent interface by returning
* the $qp object.
*
* <b>Enabling an Extension</b>
*
* To enable an extension, call the QueryPath::enable() method.
*
* @code
* <?php
* QueryPath::enable('StubExtension');
* ?>
* @endcode
*
* More complex management of extensions can be accomplished with the
* QueryPath::ExtensionRegistry class.
*
* <b>How is a QueryPath extension called?</b>
*
* QueryPath extensions are called like regular QueryPath functions. For
* example, the extension above can be called like this:
* <code>
* qp('some.xml')->stubToe();
* // or
* QueryPath::with('some.xml')->stubToe();
* </code>
* Since it returns the Query ($qp) object, chaining is supported:
* <code>
* print qp('some.xml')->stubToe()->xml();
* </code>
* When you write your own extensions, anything that does not need to return a
* specific value should return the Query object. Between that and the
* extension registry, this will provide the best developer experience.
*
* @ingroup querypath_extensions
*/
interface Extension {
public function __construct(\QueryPath\Query $qp);
}
|
