95 lines
3.1 KiB
PHP
Executable File
95 lines
3.1 KiB
PHP
Executable File
<?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);
|
|
}
|