* @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
* qp = $qp;
* }
*
* public function stubToe() {
* $this->qp->find(':root')->append('')->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.
*
* Enabling an Extension
*
* To enable an extension, call the QueryPath::enable() method.
*
* @code
*
* @endcode
*
* More complex management of extensions can be accomplished with the
* QueryPath::ExtensionRegistry class.
*
* How is a QueryPath extension called?
*
* QueryPath extensions are called like regular QueryPath functions. For
* example, the extension above can be called like this:
*
* qp('some.xml')->stubToe();
* // or
* QueryPath::with('some.xml')->stubToe();
*
* Since it returns the Query ($qp) object, chaining is supported:
*
* print qp('some.xml')->stubToe()->xml();
*
* 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);
}