update v 1.0.7.5

vendor/phpdocumentor/reflection-docblock/examples/01-interpreting-a-simple-docblock.php

@@ -0,0 +1,27 @@
+<?php
+require_once(__DIR__ . '/../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * This is a Description. A Summary and Description are separated by either
+ * two subsequent newlines (thus a whiteline in between as can be seen in this
+ * example), or when the Summary ends with a dot (`.`) and some form of
+ * whitespace.
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Should contain the first line of the DocBlock
+$summary = $docblock->getSummary();
+
+// Contains an object of type Description; you can either cast it to string or use
+// the render method to get a string representation of the Description.
+//
+// In subsequent examples we will be fiddling a bit more with the Description.
+$description = $docblock->getDescription();

vendor/phpdocumentor/reflection-docblock/examples/02-interpreting-tags.php

@@ -0,0 +1,24 @@
+<?php
+require_once(__DIR__ . '/../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * @see \phpDocumentor\Reflection\DocBlock\StandardTagFactory
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// You can check if a DocBlock has one or more see tags
+$hasSeeTag = $docblock->hasTag('see');
+
+// Or we can get a complete list of all tags
+$tags = $docblock->getTags();
+
+// But we can also grab all tags of a specific type, such as `see`
+$seeTags = $docblock->getTagsByName('see');

vendor/phpdocumentor/reflection-docblock/examples/03-reconstituting-a-docblock.php

@@ -0,0 +1,27 @@
+<?php
+
+require_once(__DIR__ . '/../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlock\Serializer;
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * And here is an example of the description
+ * of a DocBlock that can span multiple lines.
+ *
+ * @see \phpDocumentor\Reflection\DocBlock\StandardTagFactory
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// 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);
+

vendor/phpdocumentor/reflection-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);

vendor/phpdocumentor/reflection-docblock/examples/playing-with-descriptions/02-escaping.php

@@ -0,0 +1,47 @@
+<?php
+
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Escaping is automatic so this happens in the DescriptionFactory.
+$description = $docblock->getDescription();
+
+// This is the rendition that we will receive of the Description.
+$receivedDocComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+// Render it using the default PassthroughFormatter
+$foundDescription = $description->render();