Add example on writing your own Tag and prepare for TagFactory objects

Author: mvriel

examples/03-reconstituting-a-docblock.php

@@ -1,4 +1,5 @@
 <?php
+
 require_once(__DIR__ . '/../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlock\Serializer;
@@ -18,6 +19,9 @@
 $factory  = DocBlockFactory::createInstance();
 $docblock = $factory->create($docComment);
 
-$serializer              = new Serializer();
+// Create the serializer that will reconstitute the DocBlock back to its original form.
+$serializer = new Serializer();
+
+// Reconstitution is performed by the `getDocComment()` method.
 $reconstitutedDocComment = $serializer->getDocComment($docblock);
 

examples/04-adding-your-own-tag.php

@@ -0,0 +1,135 @@
+<?php
+/**
+ * In this example we demonstrate how you can add your own Tag using a Static Factory method in your Tag class.
+ */
+
+require_once(__DIR__ . '/../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlock\Serializer;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
+use phpDocumentor\Reflection\DocBlockFactory;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\BaseTag;
+use phpDocumentor\Reflection\Types\Context;
+use Webmozart\Assert\Assert;
+
+/**
+ * An example of a custom tag called `my-tag` with an optional description.
+ *
+ * A Custom Tag is a class that can consist of two parts:
+ *
+ * 1. a method `create` that is a static factory for this class.
+ * 2. methods and properties that have this object act as an immutable Value Object representing a Tag instance.
+ *
+ * The static factory `create` is used to convert a tag line (without the tag name) into an instance of the
+ * same tag object with the right constructor parameters set. This method has a dynamic list of parameters so that you
+ * can inject various dependencies, see the method's DocBlock for more information.
+ *
+ * An object of this class, and its methods and properties, represent a single instance of that tag in your
+ * documentation in the form of a Value Object whose properties should not be changed after instantiation (it should be
+ * immutable).
+ *
+ * > Important: Tag classes that act as Factories using the `create` method should implement the TagFactory interface.
+ */
+final class MyTag extends BaseTag implements StaticMethod
+{
+    /**
+     * A required property that is used by Formatters to reconstitute the complete tag line.
+     *
+     * @see Formatter
+     *
+     * @var string
+     */
+    protected $name = 'my-tag';
+
+    /**
+     * The constructor for this Tag; this should contain all properties for this object.
+     *
+     * @param Description $description An example of how to add a Description to the tag; the Description is often
+     *                                 an optional variable so passing null is allowed in this instance (though you can
+     *                                 also construct an empty description object).
+     *
+     * @see BaseTag for the declaration of the description property and getDescription method.
+     */
+    public function __construct(Description $description = null)
+    {
+        $this->description = $description;
+    }
+
+    /**
+     * A static Factory that creates a new instance of the current Tag.
+     *
+     * In this example the MyTag tag can be created by passing a description text as $body. Because we have added
+     * a $descriptionFactory that is type-hinted as DescriptionFactory we can now construct a new Description object
+     * and pass that to the constructor.
+     *
+     * > You could directly instantiate a Description object here but that won't be parsed for inline tags and Types
+     * > won't be resolved. The DescriptionFactory will take care of those actions.
+     *
+     * The `create` method's interface states that this method only features a single parameter (`$body`) but the
+     * {@see TagFactory} will read the signature of this method and if it has more parameters then it will try
+     * to find declarations for it in the ServiceLocator of the TagFactory (see {@see TagFactory::$serviceLocator}).
+     *
+     * > Important: all properties following the `$body` should default to `null`, otherwise PHP will error because
+     * > it no longer matches the interface. This is why you often see the default tags check that an optional argument
+     * > is not null nonetheless.
+     *
+     * @param string             $body
+     * @param DescriptionFactory $descriptionFactory
+     * @param Context|null       $context The Context is used to resolve Types and FQSENs, although optional
+     *                                    it is highly recommended to pass it. If you omit it then it is assumed that
+     *                                    the DocBlock is in the global namespace and has no `use` statements.
+     *
+     * @see Tag for the interface declaration of the `create` method.
+     * @see Tag::create() for more information on this method's workings.
+     *
+     * @return MyTag
+     */
+    public static function create($body, DescriptionFactory $descriptionFactory = null, Context $context = null)
+    {
+        Assert::string($body);
+        Assert::notNull($descriptionFactory);
+
+        return new static($descriptionFactory->create($body, $context));
+    }
+
+    /**
+     * Returns a rendition of the original tag line.
+     *
+     * This method is used to reconstitute a DocBlock into its original form by the {@see Serializer}. It should
+     * feature all parts of the tag so that the serializer can put it back together.
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return (string)$this->description;
+    }
+}
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * @my-tag I have a description
+ */
+DOCCOMMENT;
+
+// Make a mapping between the tag name `my-tag` and the Tag class containing the Factory Method `create`.
+$customTags = ['my-tag' => MyTag::class];
+
+// Do pass the list of custom tags to the Factory for the DocBlockFactory.
+$factory = DocBlockFactory::createInstance($customTags);
+// You can also add Tags later using `$factory->registerTagHandler()` with a tag name and Tag class name.
+
+// Create the DocBlock
+$docblock = $factory->create($docComment);
+
+// Take a look: the $customTagObjects now contain an array with your newly added tag
+$customTagObjects = $docblock->getTagsByName('my-tag');
+
+// As an experiment: let's reconstitute the DocBlock and observe that because we added a __toString() method
+// to the tag class that we can now also see it.
+$serializer              = new Serializer();
+$reconstitutedDocComment = $serializer->getDocComment($docblock);

src/DocBlock/Serializer.php

@@ -109,7 +109,8 @@ private function addAsterisksForEachLine($indent, $text)
      */
     private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength)
     {
-        $text = $docblock->getSummary() . "\n\n" . $docblock->getDescription();
+        $text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription()
+                : '');
         if ($wrapLength !== null) {
             $text = wordwrap($text, $wrapLength);
             return $text;

src/DocBlock/StandardTagFactory.php

@@ -12,6 +12,7 @@
 
 namespace phpDocumentor\Reflection\DocBlock;
 
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\FqsenResolver;
 use phpDocumentor\Reflection\Types\Context;
@@ -139,7 +140,7 @@ public function registerTagHandler($tagName, $handler)
         Assert::stringNotEmpty($tagName);
         Assert::stringNotEmpty($handler);
         Assert::classExists($handler);
-        Assert::implementsInterface($handler, Tag::class);
+        Assert::implementsInterface($handler, StaticMethod::class);
 
         if (strpos($tagName, '\\') && $tagName[0] !== '\\') {
             throw new \InvalidArgumentException(

src/DocBlock/Tags/Author.php

@@ -17,7 +17,7 @@
 /**
  * Reflection class for an {@}author tag in a Docblock.
  */
-final class Author extends BaseTag
+final class Author extends BaseTag implements Factory\StaticMethod
 {
     /** @var string register that this is the author tag. */
     protected $name = 'author';

src/DocBlock/Tags/Covers.php

@@ -22,7 +22,7 @@
 /**
  * Reflection class for a @covers tag in a Docblock.
  */
-final class Covers extends BaseTag
+final class Covers extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'covers';
 

src/DocBlock/Tags/Deprecated.php

@@ -20,7 +20,7 @@
 /**
  * Reflection class for a {@}deprecated tag in a Docblock.
  */
-final class Deprecated extends BaseTag
+final class Deprecated extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'deprecated';
 

src/DocBlock/Tags/Factory/StaticMethod.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+interface StaticMethod
+{
+    public static function create($body);
+}

src/DocBlock/Tags/Factory/Strategy.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+interface Strategy
+{
+    public function create($body);
+}

src/DocBlock/Tags/Generic.php

@@ -21,7 +21,7 @@
 /**
  * Parses a tag definition for a DocBlock.
  */
-class Generic extends BaseTag
+class Generic extends BaseTag implements Factory\StaticMethod
 {
     /**
      * Parses a tag and populates the member variables.