1 files changed, 94 insertions, 0 deletions
diff --git a/lib/querypath/src/QueryPath/Extension.php b/lib/querypath/src/QueryPath/Extension.php
new file mode 100644
index 0000000..ec370ca
--- /dev/null
+++ b/lib/querypath/src/QueryPath/Extension.php
@@ -0,0 +1,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);
+}