Repository: phpDocumentor/ReflectionDocBlock Branch: 6.x Commit: 7bae67520aa9 Files: 165 Total size: 450.4 KB Directory structure: gitextract_rmb768rz/ ├── .gitattributes ├── .github/ │ ├── dependabot.yml │ └── workflows/ │ ├── documentation.yml │ └── integrate.yaml ├── .gitignore ├── .yamllint.yaml ├── LICENSE ├── Makefile ├── README.md ├── composer-require-checker.json ├── composer.json ├── docs/ │ ├── contributing.rst │ ├── examples/ │ │ ├── 01-interpreting-a-simple-docblock.php │ │ ├── 02-interpreting-tags.php │ │ ├── 03-reconstituting-a-docblock.php │ │ ├── 04-adding-your-own-tag.php │ │ └── playing-with-descriptions/ │ │ └── 02-escaping.php │ ├── how-to/ │ │ ├── adding-your-own-tag.rst │ │ ├── index.rst │ │ ├── interpreting-a-simple-docblock.rst │ │ ├── interpreting-tags.rst │ │ └── reconstituting-a-docblock.rst │ ├── index.rst │ ├── installation.rst │ └── upgrade-to-v6.rst ├── phive.xml ├── phpcs.xml.dist ├── phpdoc.dist.xml ├── phpmd.xml.dist ├── phpstan-baseline.neon ├── phpstan.neon ├── phpunit.xml.dist ├── psalm.xml ├── src/ │ ├── DocBlock/ │ │ ├── Description.php │ │ ├── DescriptionFactory.php │ │ ├── ExampleFinder.php │ │ ├── Serializer.php │ │ ├── StandardTagFactory.php │ │ ├── Tag.php │ │ ├── TagFactory.php │ │ └── Tags/ │ │ ├── Author.php │ │ ├── BaseTag.php │ │ ├── Covers.php │ │ ├── Deprecated.php │ │ ├── Example.php │ │ ├── Extends_.php │ │ ├── Factory/ │ │ │ ├── AbstractPHPStanFactory.php │ │ │ ├── ExtendsFactory.php │ │ │ ├── Factory.php │ │ │ ├── ImplementsFactory.php │ │ │ ├── MethodFactory.php │ │ │ ├── MethodParameterFactory.php │ │ │ ├── MixinFactory.php │ │ │ ├── PHPStanFactory.php │ │ │ ├── ParamFactory.php │ │ │ ├── PropertyFactory.php │ │ │ ├── PropertyReadFactory.php │ │ │ ├── PropertyWriteFactory.php │ │ │ ├── ReturnFactory.php │ │ │ ├── TemplateCovariantFactory.php │ │ │ ├── TemplateFactory.php │ │ │ ├── ThrowsFactory.php │ │ │ └── VarFactory.php │ │ ├── Formatter/ │ │ │ ├── AlignFormatter.php │ │ │ └── PassthroughFormatter.php │ │ ├── Formatter.php │ │ ├── Generic.php │ │ ├── Implements_.php │ │ ├── InvalidTag.php │ │ ├── Link.php │ │ ├── Method.php │ │ ├── MethodParameter.php │ │ ├── Mixin.php │ │ ├── Param.php │ │ ├── Property.php │ │ ├── PropertyRead.php │ │ ├── PropertyWrite.php │ │ ├── Reference/ │ │ │ ├── Fqsen.php │ │ │ ├── Reference.php │ │ │ └── Url.php │ │ ├── Return_.php │ │ ├── See.php │ │ ├── Since.php │ │ ├── Source.php │ │ ├── TagWithType.php │ │ ├── Template.php │ │ ├── TemplateCovariant.php │ │ ├── TemplateExtends.php │ │ ├── TemplateImplements.php │ │ ├── Throws.php │ │ ├── Uses.php │ │ ├── Var_.php │ │ └── Version.php │ ├── DocBlock.php │ ├── DocBlockFactory.php │ ├── DocBlockFactoryInterface.php │ ├── Exception/ │ │ ├── CannotCreateTag.php │ │ ├── ParserException.php │ │ ├── PcreException.php │ │ └── ReflectionDocblockException.php │ └── Utils.php └── tests/ ├── coverage-checker.php ├── integration/ │ ├── DocblockSeeTagResolvingTest.php │ ├── DocblocksWithAnnotationsTest.php │ ├── InterpretingDocBlocksTest.php │ ├── ModifyBackTraceSafeTest.php │ ├── ReconstitutingADocBlockTest.php │ ├── TypedTagsTest.php │ └── UsingTagsTest.php └── unit/ ├── Assets/ │ ├── CustomParam.php │ ├── CustomServiceClass.php │ ├── CustomServiceInterface.php │ └── CustomTagFactory.php ├── DocBlock/ │ ├── DescriptionFactoryTest.php │ ├── DescriptionTest.php │ ├── ExampleFinderTest.php │ ├── SerializerTest.php │ ├── StandardTagFactoryTest.php │ └── Tags/ │ ├── AuthorTest.php │ ├── CoversTest.php │ ├── DeprecatedTest.php │ ├── ExampleTest.php │ ├── ExtendsTest.php │ ├── Factory/ │ │ ├── AbstractPHPStanFactoryTest.php │ │ ├── ExtendsFactoryTest.php │ │ ├── ImplementsFactoryTest.php │ │ ├── MethodFactoryTest.php │ │ ├── MixinFactoryTest.php │ │ ├── ParamFactoryTest.php │ │ ├── PropertyFactoryTest.php │ │ ├── PropertyReadFactoryTest.php │ │ ├── PropertyWriteFactoryTest.php │ │ ├── ReturnFactoryTest.php │ │ ├── TagFactoryTestCase.php │ │ ├── TemplateCovariantFactoryTest.php │ │ ├── TemplateFactoryTest.php │ │ ├── ThrowsFactoryTest.php │ │ └── VarFactoryTest.php │ ├── Formatter/ │ │ ├── AlignFormatterTest.php │ │ └── PassthroughFormatterTest.php │ ├── GenericTest.php │ ├── ImplementsTest.php │ ├── InvalidTagTest.php │ ├── LinkTest.php │ ├── MethodParameterTest.php │ ├── MethodTest.php │ ├── ParamTest.php │ ├── PropertyReadTest.php │ ├── PropertyTest.php │ ├── PropertyWriteTest.php │ ├── ReturnTest.php │ ├── SeeTest.php │ ├── SinceTest.php │ ├── SourceTest.php │ ├── TemplateExtendsTest.php │ ├── TemplateImplementsTest.php │ ├── TemplateTest.php │ ├── ThrowsTest.php │ ├── UsesTest.php │ ├── VarTest.php │ └── VersionTest.php ├── DocBlockFactoryTest.php ├── DocBlockTest.php ├── Exception/ │ └── PcreExceptionTest.php └── PregSplitTest.php ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitattributes ================================================ /.gitattributes export-ignore /.gitignore export-ignore /.yamllint.yaml export-ignore /composer-require-checker.json export-ignore /composer.lock export-ignore /phpmd.xml.dist export-ignore /phpunit.xml.dist export-ignore /Makefile export-ignore /phive.xml export-ignore /phpcs.xml.dist export-ignore /phpstan.neon export-ignore /phpstan-baseline.neon export-ignore /psalm.xml export-ignore /phpdoc.dist.xml export-ignore /tests/ export-ignore /docs/ export-ignore /.github/ export-ignore ================================================ FILE: .github/dependabot.yml ================================================ version: 2 updates: - package-ecosystem: "composer" directory: "/" schedule: interval: "daily" open-pull-requests-limit: 10 - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" ================================================ FILE: .github/workflows/documentation.yml ================================================ # https://docs.github.com/en/actions name: "Documentation" on: # yamllint disable-line rule:truthy push: branches: - "6.x" workflow_dispatch: null jobs: run: name: "Documentation" uses: "phpDocumentor/.github/.github/workflows/documentation.yml@main" with: deploy: true component: "reflection-docblock" secrets: token: "${{ secrets.BOT_TOKEN }}" ================================================ FILE: .github/workflows/integrate.yaml ================================================ # https://docs.github.com/en/actions name: "Integrate" on: # yamllint disable-line rule:truthy push: branches: - "6.x" pull_request: null # Allow manually triggering the workflow. workflow_dispatch: null jobs: code-coverage: name: "Code Coverage" uses: "phpDocumentor/.github/.github/workflows/code-coverage.yml@v0.9" with: composer-root-version: "6.x-dev" coding-standards: name: "Coding Standards" uses: "phpDocumentor/.github/.github/workflows/coding-standards.yml@v0.9" with: composer-root-version: "6.x-dev" dependency-analysis: name: "Dependency analysis" uses: "phpDocumentor/.github/.github/workflows/dependency-analysis.yml@v0.9" with: composer-root-version: "6.x-dev" lint-root: name: "Lint root" uses: "phpDocumentor/.github/.github/workflows/lint.yml@v0.9" with: composer-options: "--no-check-publish --ansi" static-analysis: name: "Static analysis" uses: "phpDocumentor/.github/.github/workflows/static-analysis.yml@v0.9" with: php-extensions: "none, ctype, dom, json, mbstring, phar, simplexml, tokenizer, xml, xmlwriter, fileinfo, pcntl, posix" composer-root-version: "6.x-dev" unit-tests: name: "Unit test" uses: "phpDocumentor/.github/.github/workflows/continuous-integration.yml@v0.9" with: composer-root-version: "6.x-dev" upcoming-releases: true integration-tests: name: "Integration test" uses: "phpDocumentor/.github/.github/workflows/continuous-integration.yml@v0.9" with: composer-root-version: "6.x-dev" upcoming-releases: true test-suite: "integration" ================================================ FILE: .gitignore ================================================ # IDE Shizzle; it is recommended to use a global .gitignore for this but since this is an OSS project we want to make # it easy to contribute .idea /nbproject/private/ .buildpath .project .settings # Build folder and vendor folder are generated code; no need to version this build/ temp/ tools/ vendor/ *.phar # By default the phpunit.xml.dist is provided; you can override this using a local config file phpunit.xml .phpunit.result.cache .phpdoc ================================================ FILE: .yamllint.yaml ================================================ extends: "default" ignore: | .build/ .notes/ vendor/ rules: braces: max-spaces-inside-empty: 0 max-spaces-inside: 1 min-spaces-inside-empty: 0 min-spaces-inside: 1 brackets: max-spaces-inside-empty: 0 max-spaces-inside: 0 min-spaces-inside-empty: 0 min-spaces-inside: 0 colons: max-spaces-after: 1 max-spaces-before: 0 commas: max-spaces-after: 1 max-spaces-before: 0 min-spaces-after: 1 comments: ignore-shebangs: true min-spaces-from-content: 1 require-starting-space: true comments-indentation: "enable" document-end: present: false document-start: present: false indentation: check-multi-line-strings: false indent-sequences: true spaces: 2 empty-lines: max-end: 0 max-start: 0 max: 1 empty-values: forbid-in-block-mappings: true forbid-in-flow-mappings: true hyphens: max-spaces-after: 2 key-duplicates: "enable" key-ordering: "disable" line-length: "disable" new-line-at-end-of-file: "enable" new-lines: type: "unix" octal-values: forbid-implicit-octal: true quoted-strings: quote-type: "double" trailing-spaces: "enable" truthy: allowed-values: - "false" - "true" yaml-files: - "*.yaml" - "*.yml" ================================================ FILE: LICENSE ================================================ The MIT License (MIT) Copyright (c) 2010 Mike van Riel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: Makefile ================================================ .PHONY: help help: ## Displays this list of targets with descriptions @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' .PHONY: code-style code-style: docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpcs-ga:latest -d memory_limit=1024M -s .PHONY: fix-code-style fix-code-style: docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpcs-ga:latest phpcbf .PHONY: static-code-analysis static-code-analysis: vendor ## Runs a static code analysis with phpstan/phpstan and vimeo/psalm docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpstan --configuration=phpstan.neon --memory-limit=1024M docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/psalm.phar .PHONY: test test: test-unit ## Runs all test suites with phpunit/phpunit docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit .PHONY: test-unit test-unit: ## Runs unit tests with phpunit/phpunit docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit --testsuite=unit .PHONY: dependency-analysis dependency-analysis: vendor ## Runs a dependency analysis with maglnet/composer-require-checker docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 .phive/composer-require-checker check --config-file=/opt/project/composer-require-checker.json vendor: composer.json composer.lock composer validate --no-check-publish composer install --no-interaction --no-progress .PHONY: benchmark benchmark: docker run -it --rm -v${CURDIR}:/opt/project -w /opt/project php:7.4-cli tools/phpbench run .PHONY: rector rector: ## Refactor code using rector docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/rector process .PHONY: pre-commit-test pre-commit-test: fix-code-style test code-style static-code-analysis .PHONY: docs docs: ## Generate documentation with phpDocumentor docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpdoc:3 ================================================ FILE: README.md ================================================ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Integrate](https://github.com/phpDocumentor/ReflectionDocBlock/actions/workflows/integrate.yaml/badge.svg)](https://github.com/phpDocumentor/ReflectionDocBlock/actions/workflows/integrate.yaml) [![Scrutinizer Code Coverage](https://img.shields.io/scrutinizer/coverage/g/phpDocumentor/ReflectionDocBlock.svg)](https://scrutinizer-ci.com/g/phpDocumentor/ReflectionDocBlock/?branch=master) [![Scrutinizer Code Quality](https://img.shields.io/scrutinizer/g/phpDocumentor/ReflectionDocBlock.svg)](https://scrutinizer-ci.com/g/phpDocumentor/ReflectionDocBlock/?branch=master) [![Stable Version](https://img.shields.io/packagist/v/phpdocumentor/reflection-docblock.svg?label=stable)](https://packagist.org/packages/phpdocumentor/reflection-docblock) [![Unstable Version](https://img.shields.io/packagist/v/phpdocumentor/reflection-docblock.svg?include_prereleases&label=unstable)](https://packagist.org/packages/phpdocumentor/reflection-docblock) ReflectionDocBlock ================== Introduction ------------ The ReflectionDocBlock component of phpDocumentor provides a DocBlock parser that is 100% compatible with the [PHPDoc standard](http://phpdoc.org/docs/latest). With this component, a library can provide support for annotations via DocBlocks or otherwise retrieve information that is embedded in a DocBlock. Installation ------------ ```bash composer require phpdocumentor/reflection-docblock ``` Usage ----- In order to parse the DocBlock one needs a DocBlockFactory that can be instantiated using its `createInstance` factory method like this: ```php $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance(); ``` Then we can use the `create` method of the factory to interpret the DocBlock. Please note that it is also possible to provide a class that has the `getDocComment()` method, such as an object of type `ReflectionClass`, the create method will read that if it exists. ```php $docComment = <<create($docComment); ``` The `create` method will yield an object of type `\phpDocumentor\Reflection\DocBlock` whose methods can be queried: ```php // Contains the summary for this DocBlock $summary = $docblock->getSummary(); // Contains \phpDocumentor\Reflection\DocBlock\Description object $description = $docblock->getDescription(); // You can either cast it to string $description = (string) $docblock->getDescription(); // Or use the render method to get a string representation of the Description. $description = $docblock->getDescription()->render(); ``` > For more examples it would be best to review the scripts in the [`/docs/examples` folder](/docs/examples). ================================================ FILE: composer-require-checker.json ================================================ { "symbol-whitelist" : [ "null", "true", "false", "static", "self", "parent", "array", "string", "int", "float", "bool", "iterable", "callable", "void", "object", "XSLTProcessor", "PHPStan\\PhpDocParser\\ParserConfig" ], "php-core-extensions" : [ "Core", "pcre", "Reflection", "tokenizer", "SPL", "standard" ] } ================================================ FILE: composer.json ================================================ { "name": "phpdocumentor/reflection-docblock", "description": "With this component, a library can provide support for annotations via DocBlocks or otherwise retrieve information that is embedded in a DocBlock.", "type": "library", "license": "MIT", "authors": [ { "name": "Mike van Riel", "email": "me@mikevanriel.com" }, { "name": "Jaap van Otterdijk", "email": "opensource@ijaap.nl" } ], "require": { "php": "^7.4 || ^8.0", "phpdocumentor/type-resolver": "^2.0", "webmozart/assert": "^1.9.1 || ^2", "phpdocumentor/reflection-common": "^2.2", "ext-filter": "*", "phpstan/phpdoc-parser": "^2.0", "doctrine/deprecations": "^1.1" }, "require-dev": { "mockery/mockery": "~1.3.5 || ~1.6.0", "phpunit/phpunit": "^9.5", "phpstan/phpstan": "^1.8", "phpstan/phpstan-mockery": "^1.1", "phpstan/extension-installer": "^1.1", "phpstan/phpstan-webmozart-assert": "^1.2", "psalm/phar": "^5.26", "shipmonk/dead-code-detector": "^0.5.1" }, "autoload": { "psr-4": { "phpDocumentor\\Reflection\\": "src" } }, "autoload-dev": { "psr-4": { "phpDocumentor\\Reflection\\": ["tests/unit", "tests/integration"] } }, "config": { "platform": { "php":"7.4.0" }, "allow-plugins": { "phpstan/extension-installer": true } }, "extra": { "branch-alias": { "dev-master": "5.x-dev" } } } ================================================ FILE: docs/contributing.rst ================================================ Contributing ============ Contributions are welcome! If you would like to contribute to ReflectionDocBlock, please follow these guidelines: - Fork the repository and create your branch from ``main``. - Ensure your code follows the project's coding standards. - Write tests for your changes. - Submit a pull request with a clear description of your changes. For questions or discussions, please open an issue on GitHub. ================================================ FILE: docs/examples/01-interpreting-a-simple-docblock.php ================================================ 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(); ================================================ FILE: docs/examples/02-interpreting-tags.php ================================================ 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'); ================================================ FILE: docs/examples/03-reconstituting-a-docblock.php ================================================ create($docComment); // Create the serializer that will reconstitute the DocBlock back to its original form. $serializer = new Serializer(0, '', true, null, null, PHP_EOL); // Reconstitution is performed by the `getDocComment()` method. $reconstitutedDocComment = $serializer->getDocComment($docblock); ================================================ FILE: docs/examples/04-adding-your-own-tag.php ================================================ Important: Tag classes that act as Factories using the `create` method should implement the Tag interface. * > Instead, you could extend the abstract class BaseTag that already implements the Tag interface */ final class MyTag extends BaseTag { /** * A required property that is used by Formatters to reconstitute the complete tag line. * * @see Formatter * * @var string */ protected string $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. */ public static function create(string $body, ?DescriptionFactory $descriptionFactory = null, ?Context $context = null): self { 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. */ public function __toString(): string { return (string)$this->description; } } $docComment = << 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(0, '',true, null, null, PHP_EOL); $reconstitutedDocComment = $serializer->getDocComment($docblock); ================================================ FILE: docs/examples/playing-with-descriptions/02-escaping.php ================================================ 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 = <<render(); ================================================ FILE: docs/how-to/adding-your-own-tag.rst ================================================ Add Your Own Tag ======================= This guide demonstrates how to add your own custom tag to a DocBlock using ReflectionDocBlock. .. literalinclude:: ../examples/04-adding-your-own-tag.php :language: php :linenos: ================================================ FILE: docs/how-to/index.rst ================================================ How-to ============= Practical guides for common tasks with ReflectionDocBlock: .. toctree:: :maxdepth: 1 interpreting-a-simple-docblock interpreting-tags reconstituting-a-docblock adding-your-own-tag ================================================ FILE: docs/how-to/interpreting-a-simple-docblock.rst ================================================ Interpret a Simple DocBlock ================================== This guide demonstrates how to parse a simple DocBlock and extract its summary and description using ReflectionDocBlock. .. literalinclude:: ../examples/01-interpreting-a-simple-docblock.php :language: php :linenos: ================================================ FILE: docs/how-to/interpreting-tags.rst ================================================ Interpret Tags in a DocBlock =================================== This guide demonstrates how to interpret tags within a DocBlock using ReflectionDocBlock. .. literalinclude:: ../examples/02-interpreting-tags.php :language: php :linenos: ================================================ FILE: docs/how-to/reconstituting-a-docblock.rst ================================================ Reconstituting a DocBlock ========================= ReflectionDocBlock not only allows you to read and parse DocBlocks, but also to reconstruct them. This is useful if you need to add, remove, or modify tags in your codebase programmatically. For example, you might want to update type information, add custom tags, or strip deprecated tags as part of a refactoring or code generation process. Below is a practical example of how to reconstitute a DocBlock using this library: .. literalinclude:: ../examples/03-reconstituting-a-docblock.php :language: php :caption: examples/03-reconstituting-a-docblock.php ================================================ FILE: docs/index.rst ================================================ ReflectionDocBlock Documentation =========================================== ReflectionDocBlock is a PHP library that provides a DocBlock parser fully compatible with the PHPDoc standard. It allows you to parse, interpret, and extract information from DocBlocks in your PHP code, enabling support for annotations and metadata extraction. Key Features and Use Cases -------------------------- - **Documentation Generation**: Used as a core component in tools like phpDocumentor to generate API documentation from your code's DocBlocks. - **Type and Metadata Extraction**: Integrations and tools use this library to gather type information and other metadata, enabling advanced features such as static analysis, code introspection, and automated serialization. - **Serializer Support**: Helps serializers and similar tools to interpret type information in array and object structures, making it easier to transform nested objects correctly. - **DocBlock Reconstitution**: Not only can you read DocBlocks, but you can also reconstruct them. This is useful for adding, removing, or modifying tags in your codebase programmatically. - **Standalone or Integrated**: Designed for standalone use, but also serves as a key component of the phpDocumentor suite. Unique Advantages ----------------- - **Simple, Intuitive API**: Focus on ease of use, so you can work with DocBlocks without needing to understand the complexities of parsing. - **Widely Adopted**: Used by over 1000 packages on Packagist, making it a proven and reliable choice for PHP developers. - **Actively Maintained**: Supports PHP 7.4 and 8+, and is maintained by the phpDocumentor team and contributors. Quick Start Example ------------------- Here's a minimal example of how to use ReflectionDocBlock in your project: .. literalinclude:: examples/01-interpreting-a-simple-docblock.php :language: php :caption: examples/01-interpreting-a-simple-docblock.php For more detailed usage and how-to guides, see the ``how-to/`` section. .. toctree:: :maxdepth: 2 :hidden: installation how-to/index upgrade-to-v6 contributing ================================================ FILE: docs/installation.rst ================================================ Installation ============ To install ReflectionDocBlock, use Composer: .. code-block:: bash composer require phpdocumentor/reflection-docblock ================================================ FILE: docs/upgrade-to-v6.rst ================================================ Upgrade Guide to v6 =================== This guide helps you upgrade your project to ReflectionDocBlock v6. It covers breaking changes, removals, new features, and migration tips to ensure a smooth transition. Supported PHP Versions ---------------------- - v6 requires PHP 7.4 or higher (PHP 8+ recommended). Breaking Changes & Removals --------------------------- - **Removal of `::create` static method for type-based tags** - The `create` static method has been removed from tag classes that represent type definitions, such as `@param` and `@return` tags. Most users will not be affected, as these methods are rarely used directly. The deprecation notice for these methods was present throughout v5. - **Migration:** - If you are instantiating these tag objects directly, use the tag factory or the recommended construction pattern instead. - Before: .. code-block:: php $tag = Param::create($body); - After: .. code-block:: php $factory = \phpDocumentor\Reflection\DocBlock\Tags\Factory\StandardTagFactory::createInstance(); $tag = $factory->create('@param int $foo'); - **StandardTagFactory instantiation** - `StandardTagFactory` must now be created via `createInstance()`. - **Migration:** - Before: .. code-block:: php $factory = new StandardTagFactory(); - After: .. code-block:: php $factory = StandardTagFactory::createInstance(); - **Removed methods** - `Method::getArguments` has been removed. - `Method::create` has been removed. - **Migration:** - Refactor code to use the new API for method arguments and creation. TypeResolver Upgrade ------------------- - **Generics Support**: The TypeResolver component now supports generics, which replaces the previous `Collection` type handling. This allows for more accurate and expressive type definitions, such as `MyClass` or `Collection`, and improves compatibility with modern PHPDoc standards. - For more details and advanced migration scenarios, consult the `TypeResolver upgrade guide `_ ================================================ FILE: phive.xml ================================================ ================================================ FILE: phpcs.xml.dist ================================================ The coding standard for this library. src tests/unit */tests/unit/Types/ContextFactoryTest\.php */tests/unit/Assets/* */src/*/Abstract*\.php ================================================ FILE: phpdoc.dist.xml ================================================ Reflection Docblock build/docs latest src/ api php template template-extends template-implements extends implements phpDocumentor docs guides