.doctrine-project.json000064400000002130144760114740010774 0ustar00{ "active": true, "name": "Annotations", "slug": "annotations", "docsSlug": "doctrine-annotations", "versions": [ { "name": "1.11", "branchName": "master", "slug": "latest", "upcoming": true }, { "name": "1.10", "branchName": "1.10.x", "slug": "1.10", "aliases": [ "current", "stable" ], "current": true, "maintained": true }, { "name": "1.9", "branchName": "1.9.x", "slug": "1.9", "maintained": false }, { "name": "1.8", "branchName": "1.8", "slug": "1.8", "maintained": false }, { "name": "1.7", "branchName": "1.7", "slug": "1.7", "maintained": false }, { "name": "1.6", "branchName": "1.6", "slug": "1.6", "maintained": false } ] } .github/workflows/coding-standards.yml000064400000001331144760114740014116 0ustar00 name: "Coding Standards" on: ["pull_request", "push"] jobs: coding-standards: name: "Coding Standards" runs-on: "ubuntu-20.04" strategy: matrix: php-version: - "7.4" steps: - name: "Checkout" uses: "actions/checkout@v2" - name: "Install PHP" uses: "shivammathur/setup-php@v2" with: coverage: "none" php-version: "${{ matrix.php-version }}" tools: "cs2pr" - name: "Install dependencies with Composer" uses: "ramsey/composer-install@v1" # https://github.com/doctrine/.github/issues/3 - name: "Run PHP_CodeSniffer" run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr" .github/workflows/continuous-integration.yml000064400000001760144760114740015427 0ustar00name: "Continuous Integration" on: pull_request: branches: - "*.x" - "master" push: branches: - "*.x" - "master" jobs: phpunit: name: "PHPUnit" runs-on: "ubuntu-20.04" strategy: matrix: php-version: - "7.1" - "7.2" - "7.3" - "7.4" - "8.0" deps: - "highest" include: - deps: "lowest" php-version: "7.2" steps: - name: "Checkout" uses: "actions/checkout@v2" with: fetch-depth: 2 - name: "Install PHP" uses: "shivammathur/setup-php@v2" with: php-version: "${{ matrix.php-version }}" coverage: "pcov" ini-values: "zend.assertions=1" - name: "Install dependencies with Composer" uses: "ramsey/composer-install@v1" with: dependency-versions: "${{ matrix.deps }}" - name: "Run PHPUnit" run: "vendor/bin/phpunit" .github/workflows/release-on-milestone-closed.yml000064400000003703144760114740016175 0ustar00name: "Automatic Releases" on: milestone: types: - "closed" jobs: release: name: "Git tag, release & create merge-up PR" runs-on: "ubuntu-20.04" steps: - name: "Checkout" uses: "actions/checkout@v2" - name: "Release" uses: "laminas/automatic-releases@v1" with: command-name: "laminas:automatic-releases:release" env: "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }} "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }} "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }} "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }} - name: "Create Merge-Up Pull Request" uses: "laminas/automatic-releases@v1" with: command-name: "laminas:automatic-releases:create-merge-up-pull-request" env: "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }} "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }} "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }} "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }} - name: "Create and/or Switch to new Release Branch" uses: "laminas/automatic-releases@v1" with: command-name: "laminas:automatic-releases:switch-default-branch-to-next-minor" env: "GITHUB_TOKEN": ${{ secrets.ORGANIZATION_ADMIN_TOKEN }} "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }} "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }} "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }} - name: "Create new milestones" uses: "laminas/automatic-releases@v1" with: command-name: "laminas:automatic-releases:create-milestones" env: "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }} "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }} "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }} "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }} .github/workflows/static-analysis.yml000064400000001514144760114740014005 0ustar00name: "Static Analysis" on: pull_request: branches: - "*.x" - "master" push: branches: - "*.x" - "master" jobs: static-analysis-phpstan: name: "Static Analysis with PHPStan" runs-on: "ubuntu-20.04" strategy: matrix: php-version: - "7.4" steps: - name: "Checkout code" uses: "actions/checkout@v2" - name: "Install PHP" uses: "shivammathur/setup-php@v2" with: coverage: "none" php-version: "${{ matrix.php-version }}" tools: "cs2pr" - name: "Install dependencies with Composer" uses: "ramsey/composer-install@v1" - name: "Run a static analysis with phpstan/phpstan" run: "vendor/bin/phpstan analyse -l 3 -c phpstan.neon --error-format=checkstyle lib/ tests/ | cs2pr" CHANGELOG.md000064400000021706144760114740006373 0ustar00## Changelog ### 1.6.1 This release fixes an issue in which annotations such as `@foo-bar` and `@foo-` were incorrectly recognised as valid, and both erroneously parsed as `@foo`. Any annotation with `@name-*` format will now silently be ignored, allowing vendor-specific annotations to be prefixed with the tool name. Total issues resolved: **3** - [165: Update the composer branch alias](https://github.com/doctrine/annotations/pull/165) thanks to @mikeSimonson - [209: Change Annotation::value typehint to mixed](https://github.com/doctrine/annotations/pull/209) thanks to @malarzm - [257: Skip parsing annotations containing dashes, such as `@Foo-bar`, or `@Foo-`](https://github.com/doctrine/annotations/pull/257) thanks to @Ocramius ### 1.6.0 This release brings a new endpoint that make sure that you can't shoot yourself in the foot by calling ```registerLoader``` multiple times and a few tests improvements. Total issues resolved: **7** - [145: Memory leak in AnnotationRegistry::registerLoader() when called multiple times](https://github.com/doctrine/annotations/issues/145) thanks to @TriAnMan - [146: Import error on @experimental Annotation](https://github.com/doctrine/annotations/issues/146) thanks to @aturki - [147: Ignoring @experimental annotation used by Symfony 3.3 CacheAdapter](https://github.com/doctrine/annotations/pull/147) thanks to @aturki - [151: Remove duplicate code in `DCOM58Test`](https://github.com/doctrine/annotations/pull/151) thanks to @tuanphpvn - [161: Prevent loading class_exists multiple times](https://github.com/doctrine/annotations/pull/161) thanks to @jrjohnson - [162: Add registerUniqueLoader to AnnotationRegistry](https://github.com/doctrine/annotations/pull/162) thanks to @jrjohnson - [163: Use assertDirectoryExists and assertDirectoryNotExists](https://github.com/doctrine/annotations/pull/163) thanks to @carusogabriel Thanks to everyone involved in this release. ### 1.5.0 This release increments the minimum supported PHP version to 7.1.0. Also, HHVM official support has been dropped. Some noticeable performance improvements to annotation autoloading have been applied, making failed annotation autoloading less heavy on the filesystem access. - [133: Add @throws annotation in AnnotationReader#__construct()](https://github.com/doctrine/annotations/issues/133) thanks to @SenseException - [134: Require PHP 7.1, drop HHVM support](https://github.com/doctrine/annotations/issues/134) thanks to @lcobucci - [135: Prevent the same loader from being registered twice](https://github.com/doctrine/annotations/issues/135) thanks to @jrjohnson - [137: #135 optimise multiple class load attempts in AnnotationRegistry](https://github.com/doctrine/annotations/issues/137) thanks to @Ocramius ### 1.4.0 This release fix an issue were some annotations could be not loaded if the namespace in the use statement started with a backslash. It also update the tests and drop the support for php 5.X - [115: Missing annotations with the latest composer version](https://github.com/doctrine/annotations/issues/115) thanks to @pascalporedda - [120: Missing annotations with the latest composer version](https://github.com/doctrine/annotations/pull/120) thanks to @gnat42 - [121: Adding a more detailed explanation of the test](https://github.com/doctrine/annotations/pull/121) thanks to @mikeSimonson - [101: Test annotation parameters containing space](https://github.com/doctrine/annotations/pull/101) thanks to @mikeSimonson - [111: Cleanup: move to correct phpunit assertions](https://github.com/doctrine/annotations/pull/111) thanks to @Ocramius - [112: Removes support for PHP 5.x](https://github.com/doctrine/annotations/pull/112) thanks to @railto - [113: bumped phpunit version to 5.7](https://github.com/doctrine/annotations/pull/113) thanks to @gabbydgab - [114: Enhancement: Use SVG Travis build badge](https://github.com/doctrine/annotations/pull/114) thanks to @localheinz - [118: Integrating PHPStan](https://github.com/doctrine/annotations/pull/118) thanks to @ondrejmirtes ### 1.3.1 - 2016-12-30 This release fixes an issue with ignored annotations that were already autoloaded, causing the `SimpleAnnotationReader` to pick them up anyway. [#110](https://github.com/doctrine/annotations/pull/110) Additionally, an issue was fixed in the `CachedReader`, which was not correctly checking the freshness of cached annotations when traits were defined on a class. [#105](https://github.com/doctrine/annotations/pull/105) Total issues resolved: **2** - [105: Return single max timestamp](https://github.com/doctrine/annotations/pull/105) - [110: setIgnoreNotImportedAnnotations(true) didn’t work for existing classes](https://github.com/doctrine/annotations/pull/110) ### 1.3.0 This release introduces a PHP version bump. `doctrine/annotations` now requires PHP 5.6 or later to be installed. A series of additional improvements have been introduced: * support for PHP 7 "grouped use statements" * support for ignoring entire namespace names via `Doctrine\Common\Annotations\AnnotationReader::addGlobalIgnoredNamespace()` and `Doctrine\Common\Annotations\DocParser::setIgnoredAnnotationNamespaces()`. This will allow you to ignore annotations from namespaces that you cannot autoload * testing all parent classes and interfaces when checking if the annotation cache in the `CachedReader` is fresh * simplifying the cache keys used by the `CachedReader`: keys are no longer artificially namespaced, since `Doctrine\Common\Cache` already supports that * corrected parsing of multibyte strings when `mbstring.func_overload` is enabled * corrected parsing of annotations when `"\t"` is put before the first annotation in a docblock * allow skipping non-imported annotations when a custom `DocParser` is passed to the `AnnotationReader` constructor Total issues resolved: **15** - [45: DocParser can now ignore whole namespaces](https://github.com/doctrine/annotations/pull/45) - [57: Switch to the docker-based infrastructure on Travis](https://github.com/doctrine/annotations/pull/57) - [59: opcache.load_comments has been removed from PHP 7](https://github.com/doctrine/annotations/pull/59) - [62: [CachedReader\ Test traits and parent class to see if cache is fresh](https://github.com/doctrine/annotations/pull/62) - [65: Remove cache salt making key unnecessarily long](https://github.com/doctrine/annotations/pull/65) - [66: Fix of incorrect parsing multibyte strings](https://github.com/doctrine/annotations/pull/66) - [68: Annotations that are indented by tab are not processed.](https://github.com/doctrine/annotations/issues/68) - [69: Support for Group Use Statements](https://github.com/doctrine/annotations/pull/69) - [70: Allow tab character before first annotation in DocBlock](https://github.com/doctrine/annotations/pull/70) - [74: Ignore not registered annotations fix](https://github.com/doctrine/annotations/pull/74) - [92: Added tests for AnnotationRegistry class.](https://github.com/doctrine/annotations/pull/92) - [96: Fix/#62 check trait and parent class ttl in annotations](https://github.com/doctrine/annotations/pull/96) - [97: Feature - #45 - allow ignoring entire namespaces](https://github.com/doctrine/annotations/pull/97) - [98: Enhancement/#65 remove cache salt from cached reader](https://github.com/doctrine/annotations/pull/98) - [99: Fix - #70 - allow tab character before first annotation in docblock](https://github.com/doctrine/annotations/pull/99) ### 1.2.4 Total issues resolved: **1** - [51: FileCacheReader::saveCacheFile::unlink fix](https://github.com/doctrine/annotations/pull/51) ### 1.2.3 Total issues resolved: [**2**](https://github.com/doctrine/annotations/milestones/v1.2.3) - [49: #46 - applying correct `chmod()` to generated cache file](https://github.com/doctrine/annotations/pull/49) - [50: Hotfix: match escaped quotes (revert #44)](https://github.com/doctrine/annotations/pull/50) ### 1.2.2 Total issues resolved: **4** - [43: Exclude files from distribution with .gitattributes](https://github.com/doctrine/annotations/pull/43) - [44: Update DocLexer.php](https://github.com/doctrine/annotations/pull/44) - [46: A plain "file_put_contents" can cause havoc](https://github.com/doctrine/annotations/pull/46) - [48: Deprecating the `FileCacheReader` in 1.2.2: will be removed in 2.0.0](https://github.com/doctrine/annotations/pull/48) ### 1.2.1 Total issues resolved: **4** - [38: fixes doctrine/common#326](https://github.com/doctrine/annotations/pull/38) - [39: Remove superfluous NS](https://github.com/doctrine/annotations/pull/39) - [41: Warn if load_comments is not enabled.](https://github.com/doctrine/annotations/pull/41) - [42: Clean up unused uses](https://github.com/doctrine/annotations/pull/42) ### 1.2.0 * HHVM support * Allowing dangling comma in annotations * Excluded annotations are no longer autoloaded * Importing namespaces also in traits * Added support for `::class` 5.5-style constant, works also in 5.3 and 5.4 ### 1.1.0 * Add Exception when ZendOptimizer+ or Opcache is configured to drop comments LICENSE000064400000002051144760114740005557 0ustar00Copyright (c) 2006-2013 Doctrine Project 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. README.md000064400000002155144760114740006036 0ustar00# Doctrine Annotations [![Dependency Status](https://www.versioneye.com/package/php--doctrine--annotations/badge.png)](https://www.versioneye.com/package/php--doctrine--annotations) [![Reference Status](https://www.versioneye.com/php/doctrine:annotations/reference_badge.svg)](https://www.versioneye.com/php/doctrine:annotations/references) [![Total Downloads](https://poser.pugx.org/doctrine/annotations/downloads.png)](https://packagist.org/packages/doctrine/annotations) [![Latest Stable Version](https://poser.pugx.org/doctrine/annotations/v/stable.png)](https://packagist.org/packages/doctrine/annotations) Docblock Annotations Parser library (extracted from [Doctrine Common](https://github.com/doctrine/common)). ## Documentation See the [doctrine-project website](https://www.doctrine-project.org/projects/doctrine-annotations/en/latest/index.html). ## Contributing When making a pull request, make sure your changes follow the [Coding Standard Guidelines](https://www.doctrine-project.org/projects/doctrine-coding-standard/en/latest/reference/index.html#introduction). ## Changelog See [CHANGELOG.md](CHANGELOG.md). composer.json000064400000002737144760114740007307 0ustar00{ "name": "doctrine/annotations", "type": "library", "description": "Docblock Annotations Parser", "keywords": ["annotations", "docblock", "parser"], "homepage": "https://www.doctrine-project.org/projects/annotations.html", "license": "MIT", "authors": [ {"name": "Guilherme Blanco", "email": "guilhermeblanco@gmail.com"}, {"name": "Roman Borschel", "email": "roman@code-factory.org"}, {"name": "Benjamin Eberlei", "email": "kontakt@beberlei.de"}, {"name": "Jonathan Wage", "email": "jonwage@gmail.com"}, {"name": "Johannes Schmitt", "email": "schmittjoh@gmail.com"} ], "require": { "php": "^7.1 || ^8.0", "ext-tokenizer": "*", "doctrine/lexer": "1.*" }, "require-dev": { "doctrine/cache": "1.*", "doctrine/coding-standard": "^6.0 || ^8.1", "phpstan/phpstan": "^0.12.20", "phpunit/phpunit": "^7.5 || ^9.1.5" }, "config": { "sort-packages": true }, "autoload": { "psr-4": { "Doctrine\\Common\\Annotations\\": "lib/Doctrine/Common/Annotations" } }, "autoload-dev": { "psr-4": { "Doctrine\\Performance\\Common\\Annotations\\": "tests/Doctrine/Performance/Common/Annotations", "Doctrine\\Tests\\Common\\Annotations\\": "tests/Doctrine/Tests/Common/Annotations" }, "files": [ "tests/Doctrine/Tests/Common/Annotations/Fixtures/SingleClassLOC1000.php" ] } } docs/en/annotations.rst000064400000024274144760114740011206 0ustar00Handling Annotations ==================== There are several different approaches to handling annotations in PHP. Doctrine Annotations maps docblock annotations to PHP classes. Because not all docblock annotations are used for metadata purposes a filter is applied to ignore or skip classes that are not Doctrine annotations. Take a look at the following code snippet: .. code-block:: php namespace MyProject\Entities; use Doctrine\ORM\Mapping AS ORM; use Symfony\Component\Validator\Constraints AS Assert; /** * @author Benjamin Eberlei * @ORM\Entity * @MyProject\Annotations\Foobarable */ class User { /** * @ORM\Id @ORM\Column @ORM\GeneratedValue * @dummy * @var int */ private $id; /** * @ORM\Column(type="string") * @Assert\NotEmpty * @Assert\Email * @var string */ private $email; } In this snippet you can see a variety of different docblock annotations: - Documentation annotations such as ``@var`` and ``@author``. These annotations are ignored and never considered for throwing an exception due to wrongly used annotations. - Annotations imported through use statements. The statement ``use Doctrine\ORM\Mapping AS ORM`` makes all classes under that namespace available as ``@ORM\ClassName``. Same goes for the import of ``@Assert``. - The ``@dummy`` annotation. It is not a documentation annotation and not ignored. For Doctrine Annotations it is not entirely clear how to handle this annotation. Depending on the configuration an exception (unknown annotation) will be thrown when parsing this annotation. - The fully qualified annotation ``@MyProject\Annotations\Foobarable``. This is transformed directly into the given class name. How are these annotations loaded? From looking at the code you could guess that the ORM Mapping, Assert Validation and the fully qualified annotation can just be loaded using the defined PHP autoloaders. This is not the case however: For error handling reasons every check for class existence inside the ``AnnotationReader`` sets the second parameter $autoload of ``class_exists($name, $autoload)`` to false. To work flawlessly the ``AnnotationReader`` requires silent autoloaders which many autoloaders are not. Silent autoloading is NOT part of the `PSR-0 specification `_ for autoloading. This is why Doctrine Annotations uses its own autoloading mechanism through a global registry. If you are wondering about the annotation registry being global, there is no other way to solve the architectural problems of autoloading annotation classes in a straightforward fashion. Additionally if you think about PHP autoloading then you recognize it is a global as well. To anticipate the configuration section, making the above PHP class work with Doctrine Annotations requires this setup: .. code-block:: php use Doctrine\Common\Annotations\AnnotationReader; use Doctrine\Common\Annotations\AnnotationRegistry; AnnotationRegistry::registerFile("/path/to/doctrine/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php"); AnnotationRegistry::registerAutoloadNamespace("Symfony\Component\Validator\Constraint", "/path/to/symfony/src"); AnnotationRegistry::registerAutoloadNamespace("MyProject\Annotations", "/path/to/myproject/src"); $reader = new AnnotationReader(); AnnotationReader::addGlobalIgnoredName('dummy'); The second block with the annotation registry calls registers all the three different annotation namespaces that are used. Doctrine Annotations saves all its annotations in a single file, that is why ``AnnotationRegistry#registerFile`` is used in contrast to ``AnnotationRegistry#registerAutoloadNamespace`` which creates a PSR-0 compatible loading mechanism for class to file names. In the third block, we create the actual ``AnnotationReader`` instance. Note that we also add ``dummy`` to the global list of ignored annotations for which we do not throw exceptions. Setting this is necessary in our example case, otherwise ``@dummy`` would trigger an exception to be thrown during the parsing of the docblock of ``MyProject\Entities\User#id``. Setup and Configuration ----------------------- To use the annotations library is simple, you just need to create a new ``AnnotationReader`` instance: .. code-block:: php $reader = new \Doctrine\Common\Annotations\AnnotationReader(); This creates a simple annotation reader with no caching other than in memory (in php arrays). Since parsing docblocks can be expensive you should cache this process by using a caching reader. You can use a file caching reader, but please note it is deprecated to do so: .. code-block:: php use Doctrine\Common\Annotations\FileCacheReader; use Doctrine\Common\Annotations\AnnotationReader; $reader = new FileCacheReader( new AnnotationReader(), "/path/to/cache", $debug = true ); If you set the ``debug`` flag to ``true`` the cache reader will check for changes in the original files, which is very important during development. If you don't set it to ``true`` you have to delete the directory to clear the cache. This gives faster performance, however should only be used in production, because of its inconvenience during development. You can also use one of the ``Doctrine\Common\Cache\Cache`` cache implementations to cache the annotations: .. code-block:: php use Doctrine\Common\Annotations\AnnotationReader; use Doctrine\Common\Annotations\CachedReader; use Doctrine\Common\Cache\ApcCache; $reader = new CachedReader( new AnnotationReader(), new ApcCache(), $debug = true ); The ``debug`` flag is used here as well to invalidate the cache files when the PHP class with annotations changed and should be used during development. .. warning :: The ``AnnotationReader`` works and caches under the assumption that all annotations of a doc-block are processed at once. That means that annotation classes that do not exist and aren't loaded and cannot be autoloaded (using the AnnotationRegistry) would never be visible and not accessible if a cache is used unless the cache is cleared and the annotations requested again, this time with all annotations defined. By default the annotation reader returns a list of annotations with numeric indexes. If you want your annotations to be indexed by their class name you can wrap the reader in an ``IndexedReader``: .. code-block:: php use Doctrine\Common\Annotations\AnnotationReader; use Doctrine\Common\Annotations\IndexedReader; $reader = new IndexedReader(new AnnotationReader()); .. warning:: You should never wrap the indexed reader inside a cached reader, only the other way around. This way you can re-use the cache with indexed or numeric keys, otherwise your code may experience failures due to caching in a numerical or indexed format. Registering Annotations ~~~~~~~~~~~~~~~~~~~~~~~ As explained in the introduction, Doctrine Annotations uses its own autoloading mechanism to determine if a given annotation has a corresponding PHP class that can be autoloaded. For annotation autoloading you have to configure the ``Doctrine\Common\Annotations\AnnotationRegistry``. There are three different mechanisms to configure annotation autoloading: - Calling ``AnnotationRegistry#registerFile($file)`` to register a file that contains one or more annotation classes. - Calling ``AnnotationRegistry#registerNamespace($namespace, $dirs = null)`` to register that the given namespace contains annotations and that their base directory is located at the given $dirs or in the include path if ``NULL`` is passed. The given directories should *NOT* be the directory where classes of the namespace are in, but the base directory of the root namespace. The AnnotationRegistry uses a namespace to directory separator approach to resolve the correct path. - Calling ``AnnotationRegistry#registerLoader($callable)`` to register an autoloader callback. The callback accepts the class as first and only parameter and has to return ``true`` if the corresponding file was found and included. .. note:: Loaders have to fail silently, if a class is not found even if it matches for example the namespace prefix of that loader. Never is a loader to throw a warning or exception if the loading failed otherwise parsing doc block annotations will become a huge pain. A sample loader callback could look like: .. code-block:: php use Doctrine\Common\Annotations\AnnotationRegistry; use Symfony\Component\ClassLoader\UniversalClassLoader; AnnotationRegistry::registerLoader(function($class) { $file = str_replace("\\", DIRECTORY_SEPARATOR, $class) . ".php"; if (file_exists("/my/base/path/" . $file)) { // file_exists() makes sure that the loader fails silently require "/my/base/path/" . $file; } }); $loader = new UniversalClassLoader(); AnnotationRegistry::registerLoader(array($loader, "loadClass")); Ignoring missing exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default an exception is thrown from the ``AnnotationReader`` if an annotation was found that: - is not part of the list of ignored "documentation annotations"; - was not imported through a use statement; - is not a fully qualified class that exists. You can disable this behavior for specific names if your docblocks do not follow strict requirements: .. code-block:: php $reader = new \Doctrine\Common\Annotations\AnnotationReader(); AnnotationReader::addGlobalIgnoredName('foo'); PHP Imports ~~~~~~~~~~~ By default the annotation reader parses the use-statement of a php file to gain access to the import rules and register them for the annotation processing. Only if you are using PHP Imports can you validate the correct usage of annotations and throw exceptions if you misspelled an annotation. This mechanism is enabled by default. To ease the upgrade path, we still allow you to disable this mechanism. Note however that we will remove this in future versions: .. code-block:: php $reader = new \Doctrine\Common\Annotations\AnnotationReader(); $reader->setEnabledPhpImports(false); docs/en/custom.rst000064400000021332144760114740010153 0ustar00Custom Annotation Classes ========================= If you want to define your own annotations, you just have to group them in a namespace and register this namespace in the ``AnnotationRegistry``. Annotation classes have to contain a class-level docblock with the text ``@Annotation``: .. code-block:: php namespace MyCompany\Annotations; /** @Annotation */ class Bar { // some code } Inject annotation values ------------------------ The annotation parser checks if the annotation constructor has arguments, if so then it will pass the value array, otherwise it will try to inject values into public properties directly: .. code-block:: php namespace MyCompany\Annotations; /** * @Annotation * * Some Annotation using a constructor */ class Bar { private $foo; public function __construct(array $values) { $this->foo = $values['foo']; } } /** * @Annotation * * Some Annotation without a constructor */ class Foo { public $bar; } Optional: Constructors with Named Parameters -------------------------------------------- Starting with Annotations v1.11 a new annotation instantiation strategy is available that aims at compatibility of Annotation classes with the PHP 8 attribute feature. You can implement the ``Doctrine\Common\Annotations\NamedArgumentConstructorAnnotation`` interface and then declare a constructor with regular parameter names that are matched from the named arguments in the annotation syntax. .. code-block:: php namespace MyCompany\Annotations; use Doctrine\Common\Annotations\NamedArgumentConstructorAnnotation; /** @Annotation */ class Bar implements NamedArgumentConstructorAnnotation { private $foo; public function __construct(string $foo) { $this->foo = $foo; } } /** Useable with @Bar(foo="baz") */ In combination with PHP 8's constructor property promotion feature you can simplify this to: .. code-block:: php namespace MyCompany\Annotations; use Doctrine\Common\Annotations\NamedArgumentConstructorAnnotation; /** @Annotation */ class Bar implements NamedArgumentConstructorAnnotation { public function __construct(private string $foo) {} } Annotation Target ----------------- ``@Target`` indicates the kinds of class elements to which an annotation type is applicable. Then you could define one or more targets: - ``CLASS`` Allowed in class docblocks - ``PROPERTY`` Allowed in property docblocks - ``METHOD`` Allowed in the method docblocks - ``ALL`` Allowed in class, property and method docblocks - ``ANNOTATION`` Allowed inside other annotations If the annotations is not allowed in the current context, an ``AnnotationException`` is thrown. .. code-block:: php namespace MyCompany\Annotations; /** * @Annotation * @Target({"METHOD","PROPERTY"}) */ class Bar { // some code } /** * @Annotation * @Target("CLASS") */ class Foo { // some code } Attribute types --------------- The annotation parser checks the given parameters using the phpdoc annotation ``@var``, The data type could be validated using the ``@var`` annotation on the annotation properties or using the ``@Attributes`` and ``@Attribute`` annotations. If the data type does not match you get an ``AnnotationException`` .. code-block:: php namespace MyCompany\Annotations; /** * @Annotation * @Target({"METHOD","PROPERTY"}) */ class Bar { /** @var mixed */ public $mixed; /** @var boolean */ public $boolean; /** @var bool */ public $bool; /** @var float */ public $float; /** @var string */ public $string; /** @var integer */ public $integer; /** @var array */ public $array; /** @var SomeAnnotationClass */ public $annotation; /** @var array */ public $arrayOfIntegers; /** @var array */ public $arrayOfAnnotations; } /** * @Annotation * @Target({"METHOD","PROPERTY"}) * @Attributes({ * @Attribute("stringProperty", type = "string"), * @Attribute("annotProperty", type = "SomeAnnotationClass"), * }) */ class Foo { public function __construct(array $values) { $this->stringProperty = $values['stringProperty']; $this->annotProperty = $values['annotProperty']; } // some code } Annotation Required ------------------- ``@Required`` indicates that the field must be specified when the annotation is used. If it is not used you get an ``AnnotationException`` stating that this value can not be null. Declaring a required field: .. code-block:: php /** * @Annotation * @Target("ALL") */ class Foo { /** @Required */ public $requiredField; } Usage: .. code-block:: php /** @Foo(requiredField="value") */ public $direction; // Valid /** @Foo */ public $direction; // Required field missing, throws an AnnotationException Enumerated values ----------------- - An annotation property marked with ``@Enum`` is a field that accepts a fixed set of scalar values. - You should use ``@Enum`` fields any time you need to represent fixed values. - The annotation parser checks the given value and throws an ``AnnotationException`` if the value does not match. Declaring an enumerated property: .. code-block:: php /** * @Annotation * @Target("ALL") */ class Direction { /** * @Enum({"NORTH", "SOUTH", "EAST", "WEST"}) */ public $value; } Annotation usage: .. code-block:: php /** @Direction("NORTH") */ public $direction; // Valid value /** @Direction("NORTHEAST") */ public $direction; // Invalid value, throws an AnnotationException Constants --------- The use of constants and class constants is available on the annotations parser. The following usages are allowed: .. code-block:: php namespace MyCompany\Entity; use MyCompany\Annotations\Foo; use MyCompany\Annotations\Bar; use MyCompany\Entity\SomeClass; /** * @Foo(PHP_EOL) * @Bar(Bar::FOO) * @Foo({SomeClass::FOO, SomeClass::BAR}) * @Bar({SomeClass::FOO_KEY = SomeClass::BAR_VALUE}) */ class User { } Be careful with constants and the cache ! .. note:: The cached reader will not re-evaluate each time an annotation is loaded from cache. When a constant is changed the cache must be cleaned. Usage ----- Using the library API is simple. Using the annotations described in the previous section, you can now annotate other classes with your annotations: .. code-block:: php namespace MyCompany\Entity; use MyCompany\Annotations\Foo; use MyCompany\Annotations\Bar; /** * @Foo(bar="foo") * @Bar(foo="bar") */ class User { } Now we can write a script to get the annotations above: .. code-block:: php $reflClass = new ReflectionClass('MyCompany\Entity\User'); $classAnnotations = $reader->getClassAnnotations($reflClass); foreach ($classAnnotations AS $annot) { if ($annot instanceof \MyCompany\Annotations\Foo) { echo $annot->bar; // prints "foo"; } else if ($annot instanceof \MyCompany\Annotations\Bar) { echo $annot->foo; // prints "bar"; } } You have a complete API for retrieving annotation class instances from a class, property or method docblock: Reader API ~~~~~~~~~~ Access all annotations of a class ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getClassAnnotations(\ReflectionClass $class); Access one annotation of a class ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getClassAnnotation(\ReflectionClass $class, $annotationName); Access all annotations of a method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getMethodAnnotations(\ReflectionMethod $method); Access one annotation of a method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getMethodAnnotation(\ReflectionMethod $method, $annotationName); Access all annotations of a property ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getPropertyAnnotations(\ReflectionProperty $property); Access one annotation of a property ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: php public function getPropertyAnnotation(\ReflectionProperty $property, $annotationName); docs/en/index.rst000064400000005542144760114740007755 0ustar00Introduction ============ Doctrine Annotations allows to implement custom annotation functionality for PHP classes. .. code-block:: php class Foo { /** * @MyAnnotation(myProperty="value") */ private $bar; } Annotations aren't implemented in PHP itself which is why this component offers a way to use the PHP doc-blocks as a place for the well known annotation syntax using the ``@`` char. Annotations in Doctrine are used for the ORM configuration to build the class mapping, but it can be used in other projects for other purposes too. Installation ============ You can install the Annotation component with composer: .. code-block::   $ composer require doctrine/annotations Create an annotation class ========================== An annotation class is a representation of the later used annotation configuration in classes. The annotation class of the previous example looks like this: .. code-block:: php /** * @Annotation */ final class MyAnnotation { public $myProperty; } The annotation class is declared as an annotation by ``@Annotation``. :ref:`Read more about custom annotations. ` Reading annotations =================== The access to the annotations happens by reflection of the class containing them. There are multiple reader-classes implementing the ``Doctrine\Common\Annotations\Reader`` interface, that can access the annotations of a class. A common one is ``Doctrine\Common\Annotations\AnnotationReader``: .. code-block:: php use Doctrine\Common\Annotations\AnnotationReader; use Doctrine\Common\Annotations\AnnotationRegistry; // Deprecated and will be removed in 2.0 but currently needed AnnotationRegistry::registerLoader('class_exists'); $reflectionClass = new ReflectionClass(Foo::class); $property = $reflectionClass->getProperty('bar'); $reader = new AnnotationReader(); $myAnnotation = $reader->getPropertyAnnotation( $property, MyAnnotation::class ); echo $myAnnotation->myProperty; // result: "value" Note that ``AnnotationRegistry::registerLoader('class_exists')`` only works if you already have an autoloader configured (i.e. composer autoloader). Otherwise, :ref:`please take a look to the other annotation autoload mechanisms `. A reader has multiple methods to access the annotations of a class. :ref:`Read more about handling annotations. ` IDE Support ----------- Some IDEs already provide support for annotations: - Eclipse via the `Symfony2 Plugin `_ - PhpStorm via the `PHP Annotations Plugin `_ or the `Symfony Plugin `_ .. _Read more about handling annotations.: annotations .. _Read more about custom annotations.: custom docs/en/sidebar.rst000064400000000101144760114740010241 0ustar00.. toctree:: :depth: 3 index annotations custom lib/Doctrine/Common/Annotations/Annotation.php000064400000002466144760114740015451 0ustar00 $data Key-value for properties to be defined in this class. */ final public function __construct(array $data) { foreach ($data as $key => $value) { $this->$key = $value; } } /** * Error handler for unknown property accessor in Annotation class. * * @param string $name Unknown property name. * * @throws BadMethodCallException */ public function __get($name) { throw new BadMethodCallException( sprintf("Unknown property '%s' on annotation '%s'.", $name, static::class) ); } /** * Error handler for unknown property mutator in Annotation class. * * @param string $name Unknown property name. * @param mixed $value Property value. * * @throws BadMethodCallException */ public function __set($name, $value) { throw new BadMethodCallException( sprintf("Unknown property '%s' on annotation '%s'.", $name, static::class) ); } } lib/Doctrine/Common/Annotations/Annotation/Attribute.php000064400000000547144760114740017412 0ustar00 */ public $value; } lib/Doctrine/Common/Annotations/Annotation/Enum.php000064400000003312144760114740016344 0ustar00 */ public $value; /** * Literal target declaration. * * @var mixed[] */ public $literal; /** * @throws InvalidArgumentException * * @phpstan-param array{literal?: mixed[], value: list} $values */ public function __construct(array $values) { if (! isset($values['literal'])) { $values['literal'] = []; } foreach ($values['value'] as $var) { if (! is_scalar($var)) { throw new InvalidArgumentException(sprintf( '@Enum supports only scalar values "%s" given.', is_object($var) ? get_class($var) : gettype($var) )); } } foreach ($values['literal'] as $key => $var) { if (! in_array($key, $values['value'])) { throw new InvalidArgumentException(sprintf( 'Undefined enumerator value "%s" for literal "%s".', $key, $var )); } } $this->value = $values['value']; $this->literal = $values['literal']; } } lib/Doctrine/Common/Annotations/Annotation/IgnoreAnnotation.php000064400000001752144760114740020724 0ustar00 */ public $names; /** * @throws RuntimeException * * @phpstan-param array{value: string|list} $values */ public function __construct(array $values) { if (is_string($values['value'])) { $values['value'] = [$values['value']]; } if (! is_array($values['value'])) { throw new RuntimeException(sprintf( '@IgnoreAnnotation expects either a string name, or an array of strings, but got %s.', json_encode($values['value']) )); } $this->names = $values['value']; } } lib/Doctrine/Common/Annotations/Annotation/Required.php000064400000000352144760114740017221 0ustar00 */ private static $map = [ 'ALL' => self::TARGET_ALL, 'CLASS' => self::TARGET_CLASS, 'METHOD' => self::TARGET_METHOD, 'PROPERTY' => self::TARGET_PROPERTY, 'ANNOTATION' => self::TARGET_ANNOTATION, ]; /** @phpstan-var list */ public $value; /** * Targets as bitmask. * * @var int */ public $targets; /** * Literal target declaration. * * @var string */ public $literal; /** * @throws InvalidArgumentException * * @phpstan-param array{value?: string|list} $values */ public function __construct(array $values) { if (! isset($values['value'])) { $values['value'] = null; } if (is_string($values['value'])) { $values['value'] = [$values['value']]; } if (! is_array($values['value'])) { throw new InvalidArgumentException( sprintf( '@Target expects either a string value, or an array of strings, "%s" given.', is_object($values['value']) ? get_class($values['value']) : gettype($values['value']) ) ); } $bitmask = 0; foreach ($values['value'] as $literal) { if (! isset(self::$map[$literal])) { throw new InvalidArgumentException( sprintf( 'Invalid Target "%s". Available targets: [%s]', $literal, implode(', ', array_keys(self::$map)) ) ); } $bitmask |= self::$map[$literal]; } $this->targets = $bitmask; $this->value = $values['value']; $this->literal = implode(', ', $this->value); } } lib/Doctrine/Common/Annotations/AnnotationException.php000064400000011030144760114740017313 0ustar00 $available */ public static function enumeratorError($attributeName, $annotationName, $context, $available, $given) { return new self(sprintf( '[Enum Error] Attribute "%s" of @%s declared on %s accepts only [%s], but got %s.', $attributeName, $annotationName, $context, implode(', ', $available), is_object($given) ? get_class($given) : $given )); } /** * @return AnnotationException */ public static function optimizerPlusSaveComments() { return new self( 'You have to enable opcache.save_comments=1 or zend_optimizerplus.save_comments=1.' ); } /** * @return AnnotationException */ public static function optimizerPlusLoadComments() { return new self( 'You have to enable opcache.load_comments=1 or zend_optimizerplus.load_comments=1.' ); } } lib/Doctrine/Common/Annotations/AnnotationReader.php000064400000022701144760114740016566 0ustar00 */ private static $globalImports = [ 'ignoreannotation' => Annotation\IgnoreAnnotation::class, ]; /** * A list with annotations that are not causing exceptions when not resolved to an annotation class. * * The names are case sensitive. * * @var array */ private static $globalIgnoredNames = ImplicitlyIgnoredAnnotationNames::LIST; /** * A list with annotations that are not causing exceptions when not resolved to an annotation class. * * The names are case sensitive. * * @var array */ private static $globalIgnoredNamespaces = []; /** * Add a new annotation to the globally ignored annotation names with regard to exception handling. * * @param string $name */ public static function addGlobalIgnoredName($name) { self::$globalIgnoredNames[$name] = true; } /** * Add a new annotation to the globally ignored annotation namespaces with regard to exception handling. * * @param string $namespace */ public static function addGlobalIgnoredNamespace($namespace) { self::$globalIgnoredNamespaces[$namespace] = true; } /** * Annotations parser. * * @var DocParser */ private $parser; /** * Annotations parser used to collect parsing metadata. * * @var DocParser */ private $preParser; /** * PHP parser used to collect imports. * * @var PhpParser */ private $phpParser; /** * In-memory cache mechanism to store imported annotations per class. * * @var array> */ private $imports = []; /** * In-memory cache mechanism to store ignored annotations per class. * * @var array> */ private $ignoredAnnotationNames = []; /** * Initializes a new AnnotationReader. * * @throws AnnotationException */ public function __construct(?DocParser $parser = null) { if ( extension_loaded('Zend Optimizer+') && (ini_get('zend_optimizerplus.save_comments') === '0' || ini_get('opcache.save_comments') === '0') ) { throw AnnotationException::optimizerPlusSaveComments(); } if (extension_loaded('Zend OPcache') && ini_get('opcache.save_comments') === 0) { throw AnnotationException::optimizerPlusSaveComments(); } // Make sure that the IgnoreAnnotation annotation is loaded class_exists(IgnoreAnnotation::class); $this->parser = $parser ?: new DocParser(); $this->preParser = new DocParser(); $this->preParser->setImports(self::$globalImports); $this->preParser->setIgnoreNotImportedAnnotations(true); $this->preParser->setIgnoredAnnotationNames(self::$globalIgnoredNames); $this->phpParser = new PhpParser(); } /** * {@inheritDoc} */ public function getClassAnnotations(ReflectionClass $class) { $this->parser->setTarget(Target::TARGET_CLASS); $this->parser->setImports($this->getClassImports($class)); $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class)); $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces); return $this->parser->parse($class->getDocComment(), 'class ' . $class->getName()); } /** * {@inheritDoc} */ public function getClassAnnotation(ReflectionClass $class, $annotationName) { $annotations = $this->getClassAnnotations($class); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * {@inheritDoc} */ public function getPropertyAnnotations(ReflectionProperty $property) { $class = $property->getDeclaringClass(); $context = 'property ' . $class->getName() . '::$' . $property->getName(); $this->parser->setTarget(Target::TARGET_PROPERTY); $this->parser->setImports($this->getPropertyImports($property)); $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class)); $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces); return $this->parser->parse($property->getDocComment(), $context); } /** * {@inheritDoc} */ public function getPropertyAnnotation(ReflectionProperty $property, $annotationName) { $annotations = $this->getPropertyAnnotations($property); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * {@inheritDoc} */ public function getMethodAnnotations(ReflectionMethod $method) { $class = $method->getDeclaringClass(); $context = 'method ' . $class->getName() . '::' . $method->getName() . '()'; $this->parser->setTarget(Target::TARGET_METHOD); $this->parser->setImports($this->getMethodImports($method)); $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class)); $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces); return $this->parser->parse($method->getDocComment(), $context); } /** * {@inheritDoc} */ public function getMethodAnnotation(ReflectionMethod $method, $annotationName) { $annotations = $this->getMethodAnnotations($method); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * Returns the ignored annotations for the given class. * * @return array */ private function getIgnoredAnnotationNames(ReflectionClass $class) { $name = $class->getName(); if (isset($this->ignoredAnnotationNames[$name])) { return $this->ignoredAnnotationNames[$name]; } $this->collectParsingMetadata($class); return $this->ignoredAnnotationNames[$name]; } /** * Retrieves imports. * * @return array */ private function getClassImports(ReflectionClass $class) { $name = $class->getName(); if (isset($this->imports[$name])) { return $this->imports[$name]; } $this->collectParsingMetadata($class); return $this->imports[$name]; } /** * Retrieves imports for methods. * * @return array */ private function getMethodImports(ReflectionMethod $method) { $class = $method->getDeclaringClass(); $classImports = $this->getClassImports($class); $traitImports = []; foreach ($class->getTraits() as $trait) { if ( ! $trait->hasMethod($method->getName()) || $trait->getFileName() !== $method->getFileName() ) { continue; } $traitImports = array_merge($traitImports, $this->phpParser->parseClass($trait)); } return array_merge($classImports, $traitImports); } /** * Retrieves imports for properties. * * @return array */ private function getPropertyImports(ReflectionProperty $property) { $class = $property->getDeclaringClass(); $classImports = $this->getClassImports($class); $traitImports = []; foreach ($class->getTraits() as $trait) { if (! $trait->hasProperty($property->getName())) { continue; } $traitImports = array_merge($traitImports, $this->phpParser->parseClass($trait)); } return array_merge($classImports, $traitImports); } /** * Collects parsing metadata for a given class. */ private function collectParsingMetadata(ReflectionClass $class) { $ignoredAnnotationNames = self::$globalIgnoredNames; $annotations = $this->preParser->parse($class->getDocComment(), 'class ' . $class->name); foreach ($annotations as $annotation) { if (! ($annotation instanceof IgnoreAnnotation)) { continue; } foreach ($annotation->names as $annot) { $ignoredAnnotationNames[$annot] = true; } } $name = $class->getName(); $this->imports[$name] = array_merge( self::$globalImports, $this->phpParser->parseClass($class), [ '__NAMESPACE__' => $class->getNamespaceName(), 'self' => $name, ] ); $this->ignoredAnnotationNames[$name] = $ignoredAnnotationNames; } } lib/Doctrine/Common/Annotations/AnnotationRegistry.php000064400000013121144760114740017170 0ustar00|null $dirs */ public static function registerAutoloadNamespace(string $namespace, $dirs = null): void { self::$autoloadNamespaces[$namespace] = $dirs; } /** * Registers multiple namespaces. * * Loading of this namespaces will be done with a PSR-0 namespace loading algorithm. * * @deprecated This method is deprecated and will be removed in * doctrine/annotations 2.0. Annotations will be autoloaded in 2.0. * * @param string[][]|string[]|null[] $namespaces indexed by namespace name */ public static function registerAutoloadNamespaces(array $namespaces): void { self::$autoloadNamespaces = array_merge(self::$autoloadNamespaces, $namespaces); } /** * Registers an autoloading callable for annotations, much like spl_autoload_register(). * * NOTE: These class loaders HAVE to be silent when a class was not found! * IMPORTANT: Loaders have to return true if they loaded a class that could contain the searched annotation class. * * @deprecated This method is deprecated and will be removed in * doctrine/annotations 2.0. Annotations will be autoloaded in 2.0. */ public static function registerLoader(callable $callable): void { // Reset our static cache now that we have a new loader to work with self::$failedToAutoload = []; self::$loaders[] = $callable; } /** * Registers an autoloading callable for annotations, if it is not already registered * * @deprecated This method is deprecated and will be removed in * doctrine/annotations 2.0. Annotations will be autoloaded in 2.0. */ public static function registerUniqueLoader(callable $callable): void { if (in_array($callable, self::$loaders, true)) { return; } self::registerLoader($callable); } /** * Autoloads an annotation class silently. */ public static function loadAnnotationClass(string $class): bool { if (class_exists($class, false)) { return true; } if (array_key_exists($class, self::$failedToAutoload)) { return false; } foreach (self::$autoloadNamespaces as $namespace => $dirs) { if (strpos($class, $namespace) !== 0) { continue; } $file = str_replace('\\', DIRECTORY_SEPARATOR, $class) . '.php'; if ($dirs === null) { $path = stream_resolve_include_path($file); if ($path) { require $path; return true; } } else { foreach ((array) $dirs as $dir) { if (is_file($dir . DIRECTORY_SEPARATOR . $file)) { require $dir . DIRECTORY_SEPARATOR . $file; return true; } } } } foreach (self::$loaders as $loader) { if ($loader($class) === true) { return true; } } if ( self::$loaders === [] && self::$autoloadNamespaces === [] && self::$registerFileUsed === false && class_exists($class) ) { return true; } self::$failedToAutoload[$class] = null; return false; } } lib/Doctrine/Common/Annotations/CachedReader.php000064400000015605144760114740015630 0ustar00> */ private $loadedAnnotations = []; /** @var int[] */ private $loadedFilemtimes = []; /** * @param bool $debug */ public function __construct(Reader $reader, Cache $cache, $debug = false) { $this->delegate = $reader; $this->cache = $cache; $this->debug = (bool) $debug; } /** * {@inheritDoc} */ public function getClassAnnotations(ReflectionClass $class) { $cacheKey = $class->getName(); if (isset($this->loadedAnnotations[$cacheKey])) { return $this->loadedAnnotations[$cacheKey]; } $annots = $this->fetchFromCache($cacheKey, $class); if ($annots === false) { $annots = $this->delegate->getClassAnnotations($class); $this->saveToCache($cacheKey, $annots); } return $this->loadedAnnotations[$cacheKey] = $annots; } /** * {@inheritDoc} */ public function getClassAnnotation(ReflectionClass $class, $annotationName) { foreach ($this->getClassAnnotations($class) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } /** * {@inheritDoc} */ public function getPropertyAnnotations(ReflectionProperty $property) { $class = $property->getDeclaringClass(); $cacheKey = $class->getName() . '$' . $property->getName(); if (isset($this->loadedAnnotations[$cacheKey])) { return $this->loadedAnnotations[$cacheKey]; } $annots = $this->fetchFromCache($cacheKey, $class); if ($annots === false) { $annots = $this->delegate->getPropertyAnnotations($property); $this->saveToCache($cacheKey, $annots); } return $this->loadedAnnotations[$cacheKey] = $annots; } /** * {@inheritDoc} */ public function getPropertyAnnotation(ReflectionProperty $property, $annotationName) { foreach ($this->getPropertyAnnotations($property) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } /** * {@inheritDoc} */ public function getMethodAnnotations(ReflectionMethod $method) { $class = $method->getDeclaringClass(); $cacheKey = $class->getName() . '#' . $method->getName(); if (isset($this->loadedAnnotations[$cacheKey])) { return $this->loadedAnnotations[$cacheKey]; } $annots = $this->fetchFromCache($cacheKey, $class); if ($annots === false) { $annots = $this->delegate->getMethodAnnotations($method); $this->saveToCache($cacheKey, $annots); } return $this->loadedAnnotations[$cacheKey] = $annots; } /** * {@inheritDoc} */ public function getMethodAnnotation(ReflectionMethod $method, $annotationName) { foreach ($this->getMethodAnnotations($method) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } /** * Clears loaded annotations. * * @return void */ public function clearLoadedAnnotations() { $this->loadedAnnotations = []; $this->loadedFilemtimes = []; } /** * Fetches a value from the cache. * * @param string $cacheKey The cache key. * * @return mixed The cached value or false when the value is not in cache. */ private function fetchFromCache($cacheKey, ReflectionClass $class) { $data = $this->cache->fetch($cacheKey); if ($data !== false) { if (! $this->debug || $this->isCacheFresh($cacheKey, $class)) { return $data; } } return false; } /** * Saves a value to the cache. * * @param string $cacheKey The cache key. * @param mixed $value The value. * * @return void */ private function saveToCache($cacheKey, $value) { $this->cache->save($cacheKey, $value); if (! $this->debug) { return; } $this->cache->save('[C]' . $cacheKey, time()); } /** * Checks if the cache is fresh. * * @param string $cacheKey * * @return bool */ private function isCacheFresh($cacheKey, ReflectionClass $class) { $lastModification = $this->getLastModification($class); if ($lastModification === 0) { return true; } return $this->cache->fetch('[C]' . $cacheKey) >= $lastModification; } /** * Returns the time the class was last modified, testing traits and parents */ private function getLastModification(ReflectionClass $class): int { $filename = $class->getFileName(); if (isset($this->loadedFilemtimes[$filename])) { return $this->loadedFilemtimes[$filename]; } $parent = $class->getParentClass(); $lastModification = max(array_merge( [$filename ? filemtime($filename) : 0], array_map(function (ReflectionClass $reflectionTrait): int { return $this->getTraitLastModificationTime($reflectionTrait); }, $class->getTraits()), array_map(function (ReflectionClass $class): int { return $this->getLastModification($class); }, $class->getInterfaces()), $parent ? [$this->getLastModification($parent)] : [] )); assert($lastModification !== false); return $this->loadedFilemtimes[$filename] = $lastModification; } private function getTraitLastModificationTime(ReflectionClass $reflectionTrait): int { $fileName = $reflectionTrait->getFileName(); if (isset($this->loadedFilemtimes[$fileName])) { return $this->loadedFilemtimes[$fileName]; } $lastModificationTime = max(array_merge( [$fileName ? filemtime($fileName) : 0], array_map(function (ReflectionClass $reflectionTrait): int { return $this->getTraitLastModificationTime($reflectionTrait); }, $reflectionTrait->getTraits()) )); assert($lastModificationTime !== false); return $this->loadedFilemtimes[$fileName] = $lastModificationTime; } } lib/Doctrine/Common/Annotations/DocLexer.php000064400000006666144760114740015052 0ustar00= 100 public const T_IDENTIFIER = 100; public const T_AT = 101; public const T_CLOSE_CURLY_BRACES = 102; public const T_CLOSE_PARENTHESIS = 103; public const T_COMMA = 104; public const T_EQUALS = 105; public const T_FALSE = 106; public const T_NAMESPACE_SEPARATOR = 107; public const T_OPEN_CURLY_BRACES = 108; public const T_OPEN_PARENTHESIS = 109; public const T_TRUE = 110; public const T_NULL = 111; public const T_COLON = 112; public const T_MINUS = 113; /** @var array */ protected $noCase = [ '@' => self::T_AT, ',' => self::T_COMMA, '(' => self::T_OPEN_PARENTHESIS, ')' => self::T_CLOSE_PARENTHESIS, '{' => self::T_OPEN_CURLY_BRACES, '}' => self::T_CLOSE_CURLY_BRACES, '=' => self::T_EQUALS, ':' => self::T_COLON, '-' => self::T_MINUS, '\\' => self::T_NAMESPACE_SEPARATOR, ]; /** @var array */ protected $withCase = [ 'true' => self::T_TRUE, 'false' => self::T_FALSE, 'null' => self::T_NULL, ]; /** * Whether the next token starts immediately, or if there were * non-captured symbols before that */ public function nextTokenIsAdjacent(): bool { return $this->token === null || ($this->lookahead !== null && ($this->lookahead['position'] - $this->token['position']) === strlen($this->token['value'])); } /** * {@inheritdoc} */ protected function getCatchablePatterns() { return [ '[a-z_\\\][a-z0-9_\:\\\]*[a-z_][a-z0-9_]*', '(?:[+-]?[0-9]+(?:[\.][0-9]+)*)(?:[eE][+-]?[0-9]+)?', '"(?:""|[^"])*+"', ]; } /** * {@inheritdoc} */ protected function getNonCatchablePatterns() { return ['\s+', '\*+', '(.)']; } /** * {@inheritdoc} */ protected function getType(&$value) { $type = self::T_NONE; if ($value[0] === '"') { $value = str_replace('""', '"', substr($value, 1, strlen($value) - 2)); return self::T_STRING; } if (isset($this->noCase[$value])) { return $this->noCase[$value]; } if ($value[0] === '_' || $value[0] === '\\' || ctype_alpha($value[0])) { return self::T_IDENTIFIER; } $lowerValue = strtolower($value); if (isset($this->withCase[$lowerValue])) { return $this->withCase[$lowerValue]; } // Checking numeric value if (is_numeric($value)) { return strpos($value, '.') !== false || stripos($value, 'e') !== false ? self::T_FLOAT : self::T_INTEGER; } return $type; } } lib/Doctrine/Common/Annotations/DocParser.php000064400000126342144760114740015221 0ustar00 */ private static $classIdentifiers = [ DocLexer::T_IDENTIFIER, DocLexer::T_TRUE, DocLexer::T_FALSE, DocLexer::T_NULL, ]; /** * The lexer. * * @var DocLexer */ private $lexer; /** * Current target context. * * @var int */ private $target; /** * Doc parser used to collect annotation target. * * @var DocParser */ private static $metadataParser; /** * Flag to control if the current annotation is nested or not. * * @var bool */ private $isNestedAnnotation = false; /** * Hashmap containing all use-statements that are to be used when parsing * the given doc block. * * @var array */ private $imports = []; /** * This hashmap is used internally to cache results of class_exists() * look-ups. * * @var array */ private $classExists = []; /** * Whether annotations that have not been imported should be ignored. * * @var bool */ private $ignoreNotImportedAnnotations = false; /** * An array of default namespaces if operating in simple mode. * * @var string[] */ private $namespaces = []; /** * A list with annotations that are not causing exceptions when not resolved to an annotation class. * * The names must be the raw names as used in the class, not the fully qualified * * @var bool[] indexed by annotation name */ private $ignoredAnnotationNames = []; /** * A list with annotations in namespaced format * that are not causing exceptions when not resolved to an annotation class. * * @var bool[] indexed by namespace name */ private $ignoredAnnotationNamespaces = []; /** @var string */ private $context = ''; /** * Hash-map for caching annotation metadata. * * @var array */ private static $annotationMetadata = [ Annotation\Target::class => [ 'is_annotation' => true, 'has_constructor' => true, 'properties' => [], 'targets_literal' => 'ANNOTATION_CLASS', 'targets' => Target::TARGET_CLASS, 'default_property' => 'value', 'attribute_types' => [ 'value' => [ 'required' => false, 'type' => 'array', 'array_type' => 'string', 'value' => 'array', ], ], ], Annotation\Attribute::class => [ 'is_annotation' => true, 'has_constructor' => false, 'targets_literal' => 'ANNOTATION_ANNOTATION', 'targets' => Target::TARGET_ANNOTATION, 'default_property' => 'name', 'properties' => [ 'name' => 'name', 'type' => 'type', 'required' => 'required', ], 'attribute_types' => [ 'value' => [ 'required' => true, 'type' => 'string', 'value' => 'string', ], 'type' => [ 'required' => true, 'type' => 'string', 'value' => 'string', ], 'required' => [ 'required' => false, 'type' => 'boolean', 'value' => 'boolean', ], ], ], Annotation\Attributes::class => [ 'is_annotation' => true, 'has_constructor' => false, 'targets_literal' => 'ANNOTATION_CLASS', 'targets' => Target::TARGET_CLASS, 'default_property' => 'value', 'properties' => ['value' => 'value'], 'attribute_types' => [ 'value' => [ 'type' => 'array', 'required' => true, 'array_type' => Annotation\Attribute::class, 'value' => 'array<' . Annotation\Attribute::class . '>', ], ], ], Annotation\Enum::class => [ 'is_annotation' => true, 'has_constructor' => true, 'targets_literal' => 'ANNOTATION_PROPERTY', 'targets' => Target::TARGET_PROPERTY, 'default_property' => 'value', 'properties' => ['value' => 'value'], 'attribute_types' => [ 'value' => [ 'type' => 'array', 'required' => true, ], 'literal' => [ 'type' => 'array', 'required' => false, ], ], ], ]; /** * Hash-map for handle types declaration. * * @var array */ private static $typeMap = [ 'float' => 'double', 'bool' => 'boolean', // allow uppercase Boolean in honor of George Boole 'Boolean' => 'boolean', 'int' => 'integer', ]; /** * Constructs a new DocParser. */ public function __construct() { $this->lexer = new DocLexer(); } /** * Sets the annotation names that are ignored during the parsing process. * * The names are supposed to be the raw names as used in the class, not the * fully qualified class names. * * @param bool[] $names indexed by annotation name * * @return void */ public function setIgnoredAnnotationNames(array $names) { $this->ignoredAnnotationNames = $names; } /** * Sets the annotation namespaces that are ignored during the parsing process. * * @param bool[] $ignoredAnnotationNamespaces indexed by annotation namespace name * * @return void */ public function setIgnoredAnnotationNamespaces($ignoredAnnotationNamespaces) { $this->ignoredAnnotationNamespaces = $ignoredAnnotationNamespaces; } /** * Sets ignore on not-imported annotations. * * @param bool $bool * * @return void */ public function setIgnoreNotImportedAnnotations($bool) { $this->ignoreNotImportedAnnotations = (bool) $bool; } /** * Sets the default namespaces. * * @param string $namespace * * @return void * * @throws RuntimeException */ public function addNamespace($namespace) { if ($this->imports) { throw new RuntimeException('You must either use addNamespace(), or setImports(), but not both.'); } $this->namespaces[] = $namespace; } /** * Sets the imports. * * @param array $imports * * @return void * * @throws RuntimeException */ public function setImports(array $imports) { if ($this->namespaces) { throw new RuntimeException('You must either use addNamespace(), or setImports(), but not both.'); } $this->imports = $imports; } /** * Sets current target context as bitmask. * * @param int $target * * @return void */ public function setTarget($target) { $this->target = $target; } /** * Parses the given docblock string for annotations. * * @param string $input The docblock string to parse. * @param string $context The parsing context. * * @throws AnnotationException * @throws ReflectionException * * @phpstan-return list Array of annotations. If no annotations are found, an empty array is returned. */ public function parse($input, $context = '') { $pos = $this->findInitialTokenPosition($input); if ($pos === null) { return []; } $this->context = $context; $this->lexer->setInput(trim(substr($input, $pos), '* /')); $this->lexer->moveNext(); return $this->Annotations(); } /** * Finds the first valid annotation * * @param string $input The docblock string to parse */ private function findInitialTokenPosition($input): ?int { $pos = 0; // search for first valid annotation while (($pos = strpos($input, '@', $pos)) !== false) { $preceding = substr($input, $pos - 1, 1); // if the @ is preceded by a space, a tab or * it is valid if ($pos === 0 || $preceding === ' ' || $preceding === '*' || $preceding === "\t") { return $pos; } $pos++; } return null; } /** * Attempts to match the given token with the current lookahead token. * If they match, updates the lookahead token; otherwise raises a syntax error. * * @param int $token Type of token. * * @return bool True if tokens match; false otherwise. * * @throws AnnotationException */ private function match(int $token): bool { if (! $this->lexer->isNextToken($token)) { throw $this->syntaxError($this->lexer->getLiteral($token)); } return $this->lexer->moveNext(); } /** * Attempts to match the current lookahead token with any of the given tokens. * * If any of them matches, this method updates the lookahead token; otherwise * a syntax error is raised. * * @throws AnnotationException * * @phpstan-param list $tokens */ private function matchAny(array $tokens): bool { if (! $this->lexer->isNextTokenAny($tokens)) { throw $this->syntaxError(implode(' or ', array_map([$this->lexer, 'getLiteral'], $tokens))); } return $this->lexer->moveNext(); } /** * Generates a new syntax error. * * @param string $expected Expected string. * @param mixed[]|null $token Optional token. */ private function syntaxError(string $expected, ?array $token = null): AnnotationException { if ($token === null) { $token = $this->lexer->lookahead; } $message = sprintf('Expected %s, got ', $expected); $message .= $this->lexer->lookahead === null ? 'end of string' : sprintf("'%s' at position %s", $token['value'], $token['position']); if (strlen($this->context)) { $message .= ' in ' . $this->context; } $message .= '.'; return AnnotationException::syntaxError($message); } /** * Attempts to check if a class exists or not. This never goes through the PHP autoloading mechanism * but uses the {@link AnnotationRegistry} to load classes. * * @param class-string $fqcn */ private function classExists(string $fqcn): bool { if (isset($this->classExists[$fqcn])) { return $this->classExists[$fqcn]; } // first check if the class already exists, maybe loaded through another AnnotationReader if (class_exists($fqcn, false)) { return $this->classExists[$fqcn] = true; } // final check, does this class exist? return $this->classExists[$fqcn] = AnnotationRegistry::loadAnnotationClass($fqcn); } /** * Collects parsing metadata for a given annotation class * * @param class-string $name The annotation name * * @throws AnnotationException * @throws ReflectionException */ private function collectAnnotationMetadata(string $name): void { if (self::$metadataParser === null) { self::$metadataParser = new self(); self::$metadataParser->setIgnoreNotImportedAnnotations(true); self::$metadataParser->setIgnoredAnnotationNames($this->ignoredAnnotationNames); self::$metadataParser->setImports([ 'enum' => Annotation\Enum::class, 'target' => Annotation\Target::class, 'attribute' => Annotation\Attribute::class, 'attributes' => Annotation\Attributes::class, ]); // Make sure that annotations from metadata are loaded class_exists(Enum::class); class_exists(Target::class); class_exists(Attribute::class); class_exists(Attributes::class); } $class = new ReflectionClass($name); $docComment = $class->getDocComment(); // Sets default values for annotation metadata $constructor = $class->getConstructor(); $metadata = [ 'default_property' => null, 'has_constructor' => $constructor !== null && $constructor->getNumberOfParameters() > 0, 'constructor_args' => [], 'properties' => [], 'property_types' => [], 'attribute_types' => [], 'targets_literal' => null, 'targets' => Target::TARGET_ALL, 'is_annotation' => strpos($docComment, '@Annotation') !== false, ]; if (PHP_VERSION_ID < 80000 && $class->implementsInterface(NamedArgumentConstructorAnnotation::class)) { foreach ($constructor->getParameters() as $parameter) { $metadata['constructor_args'][$parameter->getName()] = [ 'position' => $parameter->getPosition(), 'default' => $parameter->isOptional() ? $parameter->getDefaultValue() : null, ]; } } // verify that the class is really meant to be an annotation if ($metadata['is_annotation']) { self::$metadataParser->setTarget(Target::TARGET_CLASS); foreach (self::$metadataParser->parse($docComment, 'class @' . $name) as $annotation) { if ($annotation instanceof Target) { $metadata['targets'] = $annotation->targets; $metadata['targets_literal'] = $annotation->literal; continue; } if (! ($annotation instanceof Attributes)) { continue; } foreach ($annotation->value as $attribute) { $this->collectAttributeTypeMetadata($metadata, $attribute); } } // if not has a constructor will inject values into public properties if ($metadata['has_constructor'] === false) { // collect all public properties foreach ($class->getProperties(ReflectionProperty::IS_PUBLIC) as $property) { $metadata['properties'][$property->name] = $property->name; $propertyComment = $property->getDocComment(); if ($propertyComment === false) { continue; } $attribute = new Attribute(); $attribute->required = (strpos($propertyComment, '@Required') !== false); $attribute->name = $property->name; $attribute->type = (strpos($propertyComment, '@var') !== false && preg_match('/@var\s+([^\s]+)/', $propertyComment, $matches)) ? $matches[1] : 'mixed'; $this->collectAttributeTypeMetadata($metadata, $attribute); // checks if the property has @Enum if (strpos($propertyComment, '@Enum') === false) { continue; } $context = 'property ' . $class->name . '::$' . $property->name; self::$metadataParser->setTarget(Target::TARGET_PROPERTY); foreach (self::$metadataParser->parse($propertyComment, $context) as $annotation) { if (! $annotation instanceof Enum) { continue; } $metadata['enum'][$property->name]['value'] = $annotation->value; $metadata['enum'][$property->name]['literal'] = ( ! empty($annotation->literal)) ? $annotation->literal : $annotation->value; } } // choose the first property as default property $metadata['default_property'] = reset($metadata['properties']); } } self::$annotationMetadata[$name] = $metadata; } /** * Collects parsing metadata for a given attribute. * * @param mixed[] $metadata */ private function collectAttributeTypeMetadata(array &$metadata, Attribute $attribute): void { // handle internal type declaration $type = self::$typeMap[$attribute->type] ?? $attribute->type; // handle the case if the property type is mixed if ($type === 'mixed') { return; } // Evaluate type $pos = strpos($type, '<'); if ($pos !== false) { // Checks if the property has array $arrayType = substr($type, $pos + 1, -1); $type = 'array'; if (isset(self::$typeMap[$arrayType])) { $arrayType = self::$typeMap[$arrayType]; } $metadata['attribute_types'][$attribute->name]['array_type'] = $arrayType; } else { // Checks if the property has type[] $pos = strrpos($type, '['); if ($pos !== false) { $arrayType = substr($type, 0, $pos); $type = 'array'; if (isset(self::$typeMap[$arrayType])) { $arrayType = self::$typeMap[$arrayType]; } $metadata['attribute_types'][$attribute->name]['array_type'] = $arrayType; } } $metadata['attribute_types'][$attribute->name]['type'] = $type; $metadata['attribute_types'][$attribute->name]['value'] = $attribute->type; $metadata['attribute_types'][$attribute->name]['required'] = $attribute->required; } /** * Annotations ::= Annotation {[ "*" ]* [Annotation]}* * * @throws AnnotationException * @throws ReflectionException * * @phpstan-return list */ private function Annotations(): array { $annotations = []; while ($this->lexer->lookahead !== null) { if ($this->lexer->lookahead['type'] !== DocLexer::T_AT) { $this->lexer->moveNext(); continue; } // make sure the @ is preceded by non-catchable pattern if ( $this->lexer->token !== null && $this->lexer->lookahead['position'] === $this->lexer->token['position'] + strlen( $this->lexer->token['value'] ) ) { $this->lexer->moveNext(); continue; } // make sure the @ is followed by either a namespace separator, or // an identifier token $peek = $this->lexer->glimpse(); if ( ($peek === null) || ($peek['type'] !== DocLexer::T_NAMESPACE_SEPARATOR && ! in_array( $peek['type'], self::$classIdentifiers, true )) || $peek['position'] !== $this->lexer->lookahead['position'] + 1 ) { $this->lexer->moveNext(); continue; } $this->isNestedAnnotation = false; $annot = $this->Annotation(); if ($annot === false) { continue; } $annotations[] = $annot; } return $annotations; } /** * Annotation ::= "@" AnnotationName MethodCall * AnnotationName ::= QualifiedName | SimpleName * QualifiedName ::= NameSpacePart "\" {NameSpacePart "\"}* SimpleName * NameSpacePart ::= identifier | null | false | true * SimpleName ::= identifier | null | false | true * * @return object|false False if it is not a valid annotation. * * @throws AnnotationException * @throws ReflectionException */ private function Annotation() { $this->match(DocLexer::T_AT); // check if we have an annotation $name = $this->Identifier(); if ( $this->lexer->isNextToken(DocLexer::T_MINUS) && $this->lexer->nextTokenIsAdjacent() ) { // Annotations with dashes, such as "@foo-" or "@foo-bar", are to be discarded return false; } // only process names which are not fully qualified, yet // fully qualified names must start with a \ $originalName = $name; if ($name[0] !== '\\') { $pos = strpos($name, '\\'); $alias = ($pos === false) ? $name : substr($name, 0, $pos); $found = false; $loweredAlias = strtolower($alias); if ($this->namespaces) { foreach ($this->namespaces as $namespace) { if ($this->classExists($namespace . '\\' . $name)) { $name = $namespace . '\\' . $name; $found = true; break; } } } elseif (isset($this->imports[$loweredAlias])) { $namespace = ltrim($this->imports[$loweredAlias], '\\'); $name = ($pos !== false) ? $namespace . substr($name, $pos) : $namespace; $found = $this->classExists($name); } elseif ( ! isset($this->ignoredAnnotationNames[$name]) && isset($this->imports['__NAMESPACE__']) && $this->classExists($this->imports['__NAMESPACE__'] . '\\' . $name) ) { $name = $this->imports['__NAMESPACE__'] . '\\' . $name; $found = true; } elseif (! isset($this->ignoredAnnotationNames[$name]) && $this->classExists($name)) { $found = true; } if (! $found) { if ($this->isIgnoredAnnotation($name)) { return false; } throw AnnotationException::semanticalError(sprintf( <<<'EXCEPTION' The annotation "@%s" in %s was never imported. Did you maybe forget to add a "use" statement for this annotation? EXCEPTION , $name, $this->context )); } } $name = ltrim($name, '\\'); if (! $this->classExists($name)) { throw AnnotationException::semanticalError(sprintf( 'The annotation "@%s" in %s does not exist, or could not be auto-loaded.', $name, $this->context )); } // at this point, $name contains the fully qualified class name of the // annotation, and it is also guaranteed that this class exists, and // that it is loaded // collects the metadata annotation only if there is not yet if (! isset(self::$annotationMetadata[$name])) { $this->collectAnnotationMetadata($name); } // verify that the class is really meant to be an annotation and not just any ordinary class if (self::$annotationMetadata[$name]['is_annotation'] === false) { if ($this->isIgnoredAnnotation($originalName) || $this->isIgnoredAnnotation($name)) { return false; } throw AnnotationException::semanticalError(sprintf( <<<'EXCEPTION' The class "%s" is not annotated with @Annotation. Are you sure this class can be used as annotation? If so, then you need to add @Annotation to the _class_ doc comment of "%s". If it is indeed no annotation, then you need to add @IgnoreAnnotation("%s") to the _class_ doc comment of %s. EXCEPTION , $name, $name, $originalName, $this->context )); } //if target is nested annotation $target = $this->isNestedAnnotation ? Target::TARGET_ANNOTATION : $this->target; // Next will be nested $this->isNestedAnnotation = true; //if annotation does not support current target if ((self::$annotationMetadata[$name]['targets'] & $target) === 0 && $target) { throw AnnotationException::semanticalError( sprintf( <<<'EXCEPTION' Annotation @%s is not allowed to be declared on %s. You may only use this annotation on these code elements: %s. EXCEPTION , $originalName, $this->context, self::$annotationMetadata[$name]['targets_literal'] ) ); } $values = $this->MethodCall(); if (isset(self::$annotationMetadata[$name]['enum'])) { // checks all declared attributes foreach (self::$annotationMetadata[$name]['enum'] as $property => $enum) { // checks if the attribute is a valid enumerator if (isset($values[$property]) && ! in_array($values[$property], $enum['value'])) { throw AnnotationException::enumeratorError( $property, $name, $this->context, $enum['literal'], $values[$property] ); } } } // checks all declared attributes foreach (self::$annotationMetadata[$name]['attribute_types'] as $property => $type) { if ( $property === self::$annotationMetadata[$name]['default_property'] && ! isset($values[$property]) && isset($values['value']) ) { $property = 'value'; } // handle a not given attribute or null value if (! isset($values[$property])) { if ($type['required']) { throw AnnotationException::requiredError( $property, $originalName, $this->context, 'a(n) ' . $type['value'] ); } continue; } if ($type['type'] === 'array') { // handle the case of a single value if (! is_array($values[$property])) { $values[$property] = [$values[$property]]; } // checks if the attribute has array type declaration, such as "array" if (isset($type['array_type'])) { foreach ($values[$property] as $item) { if (gettype($item) !== $type['array_type'] && ! $item instanceof $type['array_type']) { throw AnnotationException::attributeTypeError( $property, $originalName, $this->context, 'either a(n) ' . $type['array_type'] . ', or an array of ' . $type['array_type'] . 's', $item ); } } } } elseif (gettype($values[$property]) !== $type['type'] && ! $values[$property] instanceof $type['type']) { throw AnnotationException::attributeTypeError( $property, $originalName, $this->context, 'a(n) ' . $type['value'], $values[$property] ); } } if (is_subclass_of($name, NamedArgumentConstructorAnnotation::class)) { if (PHP_VERSION_ID >= 80000) { return new $name(...$values); } $positionalValues = []; foreach (self::$annotationMetadata[$name]['constructor_args'] as $property => $parameter) { $positionalValues[$parameter['position']] = $parameter['default']; } foreach ($values as $property => $value) { if (! isset(self::$annotationMetadata[$name]['constructor_args'][$property])) { throw AnnotationException::creationError(sprintf( <<<'EXCEPTION' The annotation @%s declared on %s does not have a property named "%s" that can be set through its named arguments constructor. Available named arguments: %s EXCEPTION , $originalName, $this->context, $property, implode(', ', array_keys(self::$annotationMetadata[$name]['constructor_args'])) )); } $positionalValues[self::$annotationMetadata[$name]['constructor_args'][$property]['position']] = $value; } return new $name(...$positionalValues); } // check if the annotation expects values via the constructor, // or directly injected into public properties if (self::$annotationMetadata[$name]['has_constructor'] === true) { return new $name($values); } $instance = new $name(); foreach ($values as $property => $value) { if (! isset(self::$annotationMetadata[$name]['properties'][$property])) { if ($property !== 'value') { throw AnnotationException::creationError(sprintf( <<<'EXCEPTION' The annotation @%s declared on %s does not have a property named "%s". Available properties: %s EXCEPTION , $originalName, $this->context, $property, implode(', ', self::$annotationMetadata[$name]['properties']) )); } // handle the case if the property has no annotations $property = self::$annotationMetadata[$name]['default_property']; if (! $property) { throw AnnotationException::creationError(sprintf( 'The annotation @%s declared on %s does not accept any values, but got %s.', $originalName, $this->context, json_encode($values) )); } } $instance->{$property} = $value; } return $instance; } /** * MethodCall ::= ["(" [Values] ")"] * * @return mixed[] * * @throws AnnotationException * @throws ReflectionException */ private function MethodCall(): array { $values = []; if (! $this->lexer->isNextToken(DocLexer::T_OPEN_PARENTHESIS)) { return $values; } $this->match(DocLexer::T_OPEN_PARENTHESIS); if (! $this->lexer->isNextToken(DocLexer::T_CLOSE_PARENTHESIS)) { $values = $this->Values(); } $this->match(DocLexer::T_CLOSE_PARENTHESIS); return $values; } /** * Values ::= Array | Value {"," Value}* [","] * * @return mixed[] * * @throws AnnotationException * @throws ReflectionException */ private function Values(): array { $values = [$this->Value()]; while ($this->lexer->isNextToken(DocLexer::T_COMMA)) { $this->match(DocLexer::T_COMMA); if ($this->lexer->isNextToken(DocLexer::T_CLOSE_PARENTHESIS)) { break; } $token = $this->lexer->lookahead; $value = $this->Value(); if (! is_object($value) && ! is_array($value)) { throw $this->syntaxError('Value', $token); } $values[] = $value; } foreach ($values as $k => $value) { if (is_object($value) && $value instanceof stdClass) { $values[$value->name] = $value->value; } elseif (! isset($values['value'])) { $values['value'] = $value; } else { if (! is_array($values['value'])) { $values['value'] = [$values['value']]; } $values['value'][] = $value; } unset($values[$k]); } return $values; } /** * Constant ::= integer | string | float | boolean * * @return mixed * * @throws AnnotationException */ private function Constant() { $identifier = $this->Identifier(); if (! defined($identifier) && strpos($identifier, '::') !== false && $identifier[0] !== '\\') { [$className, $const] = explode('::', $identifier); $pos = strpos($className, '\\'); $alias = ($pos === false) ? $className : substr($className, 0, $pos); $found = false; $loweredAlias = strtolower($alias); switch (true) { case ! empty($this->namespaces): foreach ($this->namespaces as $ns) { if (class_exists($ns . '\\' . $className) || interface_exists($ns . '\\' . $className)) { $className = $ns . '\\' . $className; $found = true; break; } } break; case isset($this->imports[$loweredAlias]): $found = true; $className = ($pos !== false) ? $this->imports[$loweredAlias] . substr($className, $pos) : $this->imports[$loweredAlias]; break; default: if (isset($this->imports['__NAMESPACE__'])) { $ns = $this->imports['__NAMESPACE__']; if (class_exists($ns . '\\' . $className) || interface_exists($ns . '\\' . $className)) { $className = $ns . '\\' . $className; $found = true; } } break; } if ($found) { $identifier = $className . '::' . $const; } } /** * Checks if identifier ends with ::class and remove the leading backslash if it exists. */ if ( $this->identifierEndsWithClassConstant($identifier) && ! $this->identifierStartsWithBackslash($identifier) ) { return substr($identifier, 0, $this->getClassConstantPositionInIdentifier($identifier)); } if ($this->identifierEndsWithClassConstant($identifier) && $this->identifierStartsWithBackslash($identifier)) { return substr($identifier, 1, $this->getClassConstantPositionInIdentifier($identifier) - 1); } if (! defined($identifier)) { throw AnnotationException::semanticalErrorConstants($identifier, $this->context); } return constant($identifier); } private function identifierStartsWithBackslash(string $identifier): bool { return $identifier[0] === '\\'; } private function identifierEndsWithClassConstant(string $identifier): bool { return $this->getClassConstantPositionInIdentifier($identifier) === strlen($identifier) - strlen('::class'); } /** * @return int|false */ private function getClassConstantPositionInIdentifier(string $identifier) { return stripos($identifier, '::class'); } /** * Identifier ::= string * * @throws AnnotationException */ private function Identifier(): string { // check if we have an annotation if (! $this->lexer->isNextTokenAny(self::$classIdentifiers)) { throw $this->syntaxError('namespace separator or identifier'); } $this->lexer->moveNext(); $className = $this->lexer->token['value']; while ( $this->lexer->lookahead !== null && $this->lexer->lookahead['position'] === ($this->lexer->token['position'] + strlen($this->lexer->token['value'])) && $this->lexer->isNextToken(DocLexer::T_NAMESPACE_SEPARATOR) ) { $this->match(DocLexer::T_NAMESPACE_SEPARATOR); $this->matchAny(self::$classIdentifiers); $className .= '\\' . $this->lexer->token['value']; } return $className; } /** * Value ::= PlainValue | FieldAssignment * * @return mixed * * @throws AnnotationException * @throws ReflectionException */ private function Value() { $peek = $this->lexer->glimpse(); if ($peek['type'] === DocLexer::T_EQUALS) { return $this->FieldAssignment(); } return $this->PlainValue(); } /** * PlainValue ::= integer | string | float | boolean | Array | Annotation * * @return mixed * * @throws AnnotationException * @throws ReflectionException */ private function PlainValue() { if ($this->lexer->isNextToken(DocLexer::T_OPEN_CURLY_BRACES)) { return $this->Arrayx(); } if ($this->lexer->isNextToken(DocLexer::T_AT)) { return $this->Annotation(); } if ($this->lexer->isNextToken(DocLexer::T_IDENTIFIER)) { return $this->Constant(); } switch ($this->lexer->lookahead['type']) { case DocLexer::T_STRING: $this->match(DocLexer::T_STRING); return $this->lexer->token['value']; case DocLexer::T_INTEGER: $this->match(DocLexer::T_INTEGER); return (int) $this->lexer->token['value']; case DocLexer::T_FLOAT: $this->match(DocLexer::T_FLOAT); return (float) $this->lexer->token['value']; case DocLexer::T_TRUE: $this->match(DocLexer::T_TRUE); return true; case DocLexer::T_FALSE: $this->match(DocLexer::T_FALSE); return false; case DocLexer::T_NULL: $this->match(DocLexer::T_NULL); return null; default: throw $this->syntaxError('PlainValue'); } } /** * FieldAssignment ::= FieldName "=" PlainValue * FieldName ::= identifier * * @throws AnnotationException * @throws ReflectionException */ private function FieldAssignment(): stdClass { $this->match(DocLexer::T_IDENTIFIER); $fieldName = $this->lexer->token['value']; $this->match(DocLexer::T_EQUALS); $item = new stdClass(); $item->name = $fieldName; $item->value = $this->PlainValue(); return $item; } /** * Array ::= "{" ArrayEntry {"," ArrayEntry}* [","] "}" * * @return mixed[] * * @throws AnnotationException * @throws ReflectionException */ private function Arrayx(): array { $array = $values = []; $this->match(DocLexer::T_OPEN_CURLY_BRACES); // If the array is empty, stop parsing and return. if ($this->lexer->isNextToken(DocLexer::T_CLOSE_CURLY_BRACES)) { $this->match(DocLexer::T_CLOSE_CURLY_BRACES); return $array; } $values[] = $this->ArrayEntry(); while ($this->lexer->isNextToken(DocLexer::T_COMMA)) { $this->match(DocLexer::T_COMMA); // optional trailing comma if ($this->lexer->isNextToken(DocLexer::T_CLOSE_CURLY_BRACES)) { break; } $values[] = $this->ArrayEntry(); } $this->match(DocLexer::T_CLOSE_CURLY_BRACES); foreach ($values as $value) { [$key, $val] = $value; if ($key !== null) { $array[$key] = $val; } else { $array[] = $val; } } return $array; } /** * ArrayEntry ::= Value | KeyValuePair * KeyValuePair ::= Key ("=" | ":") PlainValue | Constant * Key ::= string | integer | Constant * * @throws AnnotationException * @throws ReflectionException * * @phpstan-return array{mixed, mixed} */ private function ArrayEntry(): array { $peek = $this->lexer->glimpse(); if ( $peek['type'] === DocLexer::T_EQUALS || $peek['type'] === DocLexer::T_COLON ) { if ($this->lexer->isNextToken(DocLexer::T_IDENTIFIER)) { $key = $this->Constant(); } else { $this->matchAny([DocLexer::T_INTEGER, DocLexer::T_STRING]); $key = $this->lexer->token['value']; } $this->matchAny([DocLexer::T_EQUALS, DocLexer::T_COLON]); return [$key, $this->PlainValue()]; } return [null, $this->Value()]; } /** * Checks whether the given $name matches any ignored annotation name or namespace */ private function isIgnoredAnnotation(string $name): bool { if ($this->ignoreNotImportedAnnotations || isset($this->ignoredAnnotationNames[$name])) { return true; } foreach (array_keys($this->ignoredAnnotationNamespaces) as $ignoredAnnotationNamespace) { $ignoredAnnotationNamespace = rtrim($ignoredAnnotationNamespace, '\\') . '\\'; if (stripos(rtrim($name, '\\') . '\\', $ignoredAnnotationNamespace) === 0) { return true; } } return false; } } lib/Doctrine/Common/Annotations/FileCacheReader.php000064400000020623144760114740016260 0ustar00> */ private $loadedAnnotations = []; /** @var array */ private $classNameHashes = []; /** @var int */ private $umask; /** * @param string $cacheDir * @param bool $debug * @param int $umask * * @throws InvalidArgumentException */ public function __construct(Reader $reader, $cacheDir, $debug = false, $umask = 0002) { if (! is_int($umask)) { throw new InvalidArgumentException(sprintf( 'The parameter umask must be an integer, was: %s', gettype($umask) )); } $this->reader = $reader; $this->umask = $umask; if (! is_dir($cacheDir) && ! @mkdir($cacheDir, 0777 & (~$this->umask), true)) { throw new InvalidArgumentException(sprintf( 'The directory "%s" does not exist and could not be created.', $cacheDir )); } $this->dir = rtrim($cacheDir, '\\/'); $this->debug = $debug; } /** * {@inheritDoc} */ public function getClassAnnotations(ReflectionClass $class) { if (! isset($this->classNameHashes[$class->name])) { $this->classNameHashes[$class->name] = sha1($class->name); } $key = $this->classNameHashes[$class->name]; if (isset($this->loadedAnnotations[$key])) { return $this->loadedAnnotations[$key]; } $path = $this->dir . '/' . strtr($key, '\\', '-') . '.cache.php'; if (! is_file($path)) { $annot = $this->reader->getClassAnnotations($class); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } $filename = $class->getFilename(); if ( $this->debug && $filename !== false && filemtime($path) < filemtime($filename) ) { @unlink($path); $annot = $this->reader->getClassAnnotations($class); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } return $this->loadedAnnotations[$key] = include $path; } /** * {@inheritDoc} */ public function getPropertyAnnotations(ReflectionProperty $property) { $class = $property->getDeclaringClass(); if (! isset($this->classNameHashes[$class->name])) { $this->classNameHashes[$class->name] = sha1($class->name); } $key = $this->classNameHashes[$class->name] . '$' . $property->getName(); if (isset($this->loadedAnnotations[$key])) { return $this->loadedAnnotations[$key]; } $path = $this->dir . '/' . strtr($key, '\\', '-') . '.cache.php'; if (! is_file($path)) { $annot = $this->reader->getPropertyAnnotations($property); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } $filename = $class->getFilename(); if ( $this->debug && $filename !== false && filemtime($path) < filemtime($filename) ) { @unlink($path); $annot = $this->reader->getPropertyAnnotations($property); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } return $this->loadedAnnotations[$key] = include $path; } /** * {@inheritDoc} */ public function getMethodAnnotations(ReflectionMethod $method) { $class = $method->getDeclaringClass(); if (! isset($this->classNameHashes[$class->name])) { $this->classNameHashes[$class->name] = sha1($class->name); } $key = $this->classNameHashes[$class->name] . '#' . $method->getName(); if (isset($this->loadedAnnotations[$key])) { return $this->loadedAnnotations[$key]; } $path = $this->dir . '/' . strtr($key, '\\', '-') . '.cache.php'; if (! is_file($path)) { $annot = $this->reader->getMethodAnnotations($method); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } $filename = $class->getFilename(); if ( $this->debug && $filename !== false && filemtime($path) < filemtime($filename) ) { @unlink($path); $annot = $this->reader->getMethodAnnotations($method); $this->saveCacheFile($path, $annot); return $this->loadedAnnotations[$key] = $annot; } return $this->loadedAnnotations[$key] = include $path; } /** * Saves the cache file. * * @param string $path * @param mixed $data * * @return void */ private function saveCacheFile($path, $data) { if (! is_writable($this->dir)) { throw new InvalidArgumentException(sprintf( <<<'EXCEPTION' The directory "%s" is not writable. Both the webserver and the console user need access. You can manage access rights for multiple users with "chmod +a". If your system does not support this, check out the acl package., EXCEPTION , $this->dir )); } $tempfile = tempnam($this->dir, uniqid('', true)); if ($tempfile === false) { throw new RuntimeException(sprintf('Unable to create tempfile in directory: %s', $this->dir)); } @chmod($tempfile, 0666 & (~$this->umask)); $written = file_put_contents( $tempfile, 'umask)); if (rename($tempfile, $path) === false) { @unlink($tempfile); throw new RuntimeException(sprintf('Unable to rename %s to %s', $tempfile, $path)); } } /** * {@inheritDoc} */ public function getClassAnnotation(ReflectionClass $class, $annotationName) { $annotations = $this->getClassAnnotations($class); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * {@inheritDoc} */ public function getMethodAnnotation(ReflectionMethod $method, $annotationName) { $annotations = $this->getMethodAnnotations($method); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * {@inheritDoc} */ public function getPropertyAnnotation(ReflectionProperty $property, $annotationName) { $annotations = $this->getPropertyAnnotations($property); foreach ($annotations as $annotation) { if ($annotation instanceof $annotationName) { return $annotation; } } return null; } /** * Clears loaded annotations. * * @return void */ public function clearLoadedAnnotations() { $this->loadedAnnotations = []; } } lib/Doctrine/Common/Annotations/ImplicitlyIgnoredAnnotationNames.php000064400000012147144760114740022002 0ustar00 true, 'Attribute' => true, 'Attributes' => true, /* Can we enable this? 'Enum' => true, */ 'Required' => true, 'Target' => true, ]; private const WidelyUsedNonStandard = [ 'fix' => true, 'fixme' => true, 'override' => true, ]; private const PhpDocumentor1 = [ 'abstract' => true, 'access' => true, 'code' => true, 'deprec' => true, 'endcode' => true, 'exception' => true, 'final' => true, 'ingroup' => true, 'inheritdoc' => true, 'inheritDoc' => true, 'magic' => true, 'name' => true, 'private' => true, 'static' => true, 'staticvar' => true, 'staticVar' => true, 'toc' => true, 'tutorial' => true, 'throw' => true, ]; private const PhpDocumentor2 = [ 'api' => true, 'author' => true, 'category' => true, 'copyright' => true, 'deprecated' => true, 'example' => true, 'filesource' => true, 'global' => true, 'ignore' => true, /* Can we enable this? 'index' => true, */ 'internal' => true, 'license' => true, 'link' => true, 'method' => true, 'package' => true, 'param' => true, 'property' => true, 'property-read' => true, 'property-write' => true, 'return' => true, 'see' => true, 'since' => true, 'source' => true, 'subpackage' => true, 'throws' => true, 'todo' => true, 'TODO' => true, 'usedby' => true, 'uses' => true, 'var' => true, 'version' => true, ]; private const PHPUnit = [ 'author' => true, 'after' => true, 'afterClass' => true, 'backupGlobals' => true, 'backupStaticAttributes' => true, 'before' => true, 'beforeClass' => true, 'codeCoverageIgnore' => true, 'codeCoverageIgnoreStart' => true, 'codeCoverageIgnoreEnd' => true, 'covers' => true, 'coversDefaultClass' => true, 'coversNothing' => true, 'dataProvider' => true, 'depends' => true, 'doesNotPerformAssertions' => true, 'expectedException' => true, 'expectedExceptionCode' => true, 'expectedExceptionMessage' => true, 'expectedExceptionMessageRegExp' => true, 'group' => true, 'large' => true, 'medium' => true, 'preserveGlobalState' => true, 'requires' => true, 'runTestsInSeparateProcesses' => true, 'runInSeparateProcess' => true, 'small' => true, 'test' => true, 'testdox' => true, 'testWith' => true, 'ticket' => true, 'uses' => true, ]; private const PhpCheckStyle = ['SuppressWarnings' => true]; private const PhpStorm = ['noinspection' => true]; private const PEAR = ['package_version' => true]; private const PlainUML = [ 'startuml' => true, 'enduml' => true, ]; private const Symfony = ['experimental' => true]; private const PhpCodeSniffer = [ 'codingStandardsIgnoreStart' => true, 'codingStandardsIgnoreEnd' => true, ]; private const SlevomatCodingStandard = ['phpcsSuppress' => true]; private const PhpStan = [ 'extends' => true, 'implements' => true, 'template' => true, 'use' => true, ]; private const Phan = ['suppress' => true]; public const LIST = self::Reserved + self::WidelyUsedNonStandard + self::PhpDocumentor1 + self::PhpDocumentor2 + self::PHPUnit + self::PhpCheckStyle + self::PhpStorm + self::PEAR + self::PlainUML + self::Symfony + self::SlevomatCodingStandard + self::PhpCodeSniffer + self::PhpStan + self::Phan; private function __construct() { } } lib/Doctrine/Common/Annotations/IndexedReader.php000064400000004346144760114740016041 0ustar00delegate = $reader; } /** * {@inheritDoc} */ public function getClassAnnotations(ReflectionClass $class) { $annotations = []; foreach ($this->delegate->getClassAnnotations($class) as $annot) { $annotations[get_class($annot)] = $annot; } return $annotations; } /** * {@inheritDoc} */ public function getClassAnnotation(ReflectionClass $class, $annotation) { return $this->delegate->getClassAnnotation($class, $annotation); } /** * {@inheritDoc} */ public function getMethodAnnotations(ReflectionMethod $method) { $annotations = []; foreach ($this->delegate->getMethodAnnotations($method) as $annot) { $annotations[get_class($annot)] = $annot; } return $annotations; } /** * {@inheritDoc} */ public function getMethodAnnotation(ReflectionMethod $method, $annotation) { return $this->delegate->getMethodAnnotation($method, $annotation); } /** * {@inheritDoc} */ public function getPropertyAnnotations(ReflectionProperty $property) { $annotations = []; foreach ($this->delegate->getPropertyAnnotations($property) as $annot) { $annotations[get_class($annot)] = $annot; } return $annotations; } /** * {@inheritDoc} */ public function getPropertyAnnotation(ReflectionProperty $property, $annotation) { return $this->delegate->getPropertyAnnotation($property, $annotation); } /** * Proxies all methods to the delegate. * * @param string $method * @param mixed[] $args * * @return mixed */ public function __call($method, $args) { return call_user_func_array([$this->delegate, $method], $args); } } lib/Doctrine/Common/Annotations/NamedArgumentConstructorAnnotation.php000064400000000332144760114740022355 0ustar00ReflectionClass object. * * @return array A list with use statements in the form (Alias => FQN). */ public function parseClass(ReflectionClass $class) { if (method_exists($class, 'getUseStatements')) { return $class->getUseStatements(); } $filename = $class->getFileName(); if ($filename === false) { return []; } $content = $this->getFileContent($filename, $class->getStartLine()); if ($content === null) { return []; } $namespace = preg_quote($class->getNamespaceName()); $content = preg_replace('/^.*?(\bnamespace\s+' . $namespace . '\s*[;{].*)$/s', '\\1', $content); $tokenizer = new TokenParser('parseUseStatements($class->getNamespaceName()); } /** * Gets the content of the file right up to the given line number. * * @param string $filename The name of the file to load. * @param int $lineNumber The number of lines to read from file. * * @return string|null The content of the file or null if the file does not exist. */ private function getFileContent($filename, $lineNumber) { if (! is_file($filename)) { return null; } $content = ''; $lineCnt = 0; $file = new SplFileObject($filename); while (! $file->eof()) { if ($lineCnt++ === $lineNumber) { break; } $content .= $file->fgets(); } return $content; } } lib/Doctrine/Common/Annotations/Reader.php000064400000004752144760114740014541 0ustar00 An array of Annotations. */ public function getClassAnnotations(ReflectionClass $class); /** * Gets a class annotation. * * @param ReflectionClass $class The ReflectionClass of the class from which * the class annotations should be read. * @param class-string $annotationName The name of the annotation. * * @return T|null The Annotation or NULL, if the requested annotation does not exist. * * @template T */ public function getClassAnnotation(ReflectionClass $class, $annotationName); /** * Gets the annotations applied to a method. * * @param ReflectionMethod $method The ReflectionMethod of the method from which * the annotations should be read. * * @return array An array of Annotations. */ public function getMethodAnnotations(ReflectionMethod $method); /** * Gets a method annotation. * * @param ReflectionMethod $method The ReflectionMethod to read the annotations from. * @param class-string $annotationName The name of the annotation. * * @return T|null The Annotation or NULL, if the requested annotation does not exist. * * @template T */ public function getMethodAnnotation(ReflectionMethod $method, $annotationName); /** * Gets the annotations applied to a property. * * @param ReflectionProperty $property The ReflectionProperty of the property * from which the annotations should be read. * * @return array An array of Annotations. */ public function getPropertyAnnotations(ReflectionProperty $property); /** * Gets a property annotation. * * @param ReflectionProperty $property The ReflectionProperty to read the annotations from. * @param class-string $annotationName The name of the annotation. * * @return T|null The Annotation or NULL, if the requested annotation does not exist. * * @template T */ public function getPropertyAnnotation(ReflectionProperty $property, $annotationName); } lib/Doctrine/Common/Annotations/SimpleAnnotationReader.php000064400000005241144760114740017740 0ustar00parser = new DocParser(); $this->parser->setIgnoreNotImportedAnnotations(true); } /** * Adds a namespace in which we will look for annotations. * * @param string $namespace * * @return void */ public function addNamespace($namespace) { $this->parser->addNamespace($namespace); } /** * {@inheritDoc} */ public function getClassAnnotations(ReflectionClass $class) { return $this->parser->parse($class->getDocComment(), 'class ' . $class->getName()); } /** * {@inheritDoc} */ public function getMethodAnnotations(ReflectionMethod $method) { return $this->parser->parse( $method->getDocComment(), 'method ' . $method->getDeclaringClass()->name . '::' . $method->getName() . '()' ); } /** * {@inheritDoc} */ public function getPropertyAnnotations(ReflectionProperty $property) { return $this->parser->parse( $property->getDocComment(), 'property ' . $property->getDeclaringClass()->name . '::$' . $property->getName() ); } /** * {@inheritDoc} */ public function getClassAnnotation(ReflectionClass $class, $annotationName) { foreach ($this->getClassAnnotations($class) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } /** * {@inheritDoc} */ public function getMethodAnnotation(ReflectionMethod $method, $annotationName) { foreach ($this->getMethodAnnotations($method) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } /** * {@inheritDoc} */ public function getPropertyAnnotation(ReflectionProperty $property, $annotationName) { foreach ($this->getPropertyAnnotations($property) as $annot) { if ($annot instanceof $annotationName) { return $annot; } } return null; } } lib/Doctrine/Common/Annotations/TokenParser.php000064400000014260144760114740015567 0ustar00 */ private $tokens; /** * The number of tokens. * * @var int */ private $numTokens; /** * The current array pointer. * * @var int */ private $pointer = 0; /** * @param string $contents */ public function __construct($contents) { $this->tokens = token_get_all($contents); // The PHP parser sets internal compiler globals for certain things. Annoyingly, the last docblock comment it // saw gets stored in doc_comment. When it comes to compile the next thing to be include()d this stored // doc_comment becomes owned by the first thing the compiler sees in the file that it considers might have a // docblock. If the first thing in the file is a class without a doc block this would cause calls to // getDocBlock() on said class to return our long lost doc_comment. Argh. // To workaround, cause the parser to parse an empty docblock. Sure getDocBlock() will return this, but at least // it's harmless to us. token_get_all("numTokens = count($this->tokens); } /** * Gets the next non whitespace and non comment token. * * @param bool $docCommentIsComment If TRUE then a doc comment is considered a comment and skipped. * If FALSE then only whitespace and normal comments are skipped. * * @return mixed[]|string|null The token if exists, null otherwise. */ public function next($docCommentIsComment = true) { for ($i = $this->pointer; $i < $this->numTokens; $i++) { $this->pointer++; if ( $this->tokens[$i][0] === T_WHITESPACE || $this->tokens[$i][0] === T_COMMENT || ($docCommentIsComment && $this->tokens[$i][0] === T_DOC_COMMENT) ) { continue; } return $this->tokens[$i]; } return null; } /** * Parses a single use statement. * * @return array A list with all found class names for a use statement. */ public function parseUseStatement() { $groupRoot = ''; $class = ''; $alias = ''; $statements = []; $explicitAlias = false; while (($token = $this->next())) { if (! $explicitAlias && $token[0] === T_STRING) { $class .= $token[1]; $alias = $token[1]; } elseif ($explicitAlias && $token[0] === T_STRING) { $alias = $token[1]; } elseif ( PHP_VERSION_ID >= 80000 && ($token[0] === T_NAME_QUALIFIED || $token[0] === T_NAME_FULLY_QUALIFIED) ) { $class .= $token[1]; $classSplit = explode('\\', $token[1]); $alias = $classSplit[count($classSplit) - 1]; } elseif ($token[0] === T_NS_SEPARATOR) { $class .= '\\'; $alias = ''; } elseif ($token[0] === T_AS) { $explicitAlias = true; $alias = ''; } elseif ($token === ',') { $statements[strtolower($alias)] = $groupRoot . $class; $class = ''; $alias = ''; $explicitAlias = false; } elseif ($token === ';') { $statements[strtolower($alias)] = $groupRoot . $class; break; } elseif ($token === '{') { $groupRoot = $class; $class = ''; } elseif ($token === '}') { continue; } else { break; } } return $statements; } /** * Gets all use statements. * * @param string $namespaceName The namespace name of the reflected class. * * @return array A list with all found use statements. */ public function parseUseStatements($namespaceName) { $statements = []; while (($token = $this->next())) { if ($token[0] === T_USE) { $statements = array_merge($statements, $this->parseUseStatement()); continue; } if ($token[0] !== T_NAMESPACE || $this->parseNamespace() !== $namespaceName) { continue; } // Get fresh array for new namespace. This is to prevent the parser to collect the use statements // for a previous namespace with the same name. This is the case if a namespace is defined twice // or if a namespace with the same name is commented out. $statements = []; } return $statements; } /** * Gets the namespace. * * @return string The found namespace. */ public function parseNamespace() { $name = ''; while ( ($token = $this->next()) && ($token[0] === T_STRING || $token[0] === T_NS_SEPARATOR || ( PHP_VERSION_ID >= 80000 && ($token[0] === T_NAME_QUALIFIED || $token[0] === T_NAME_FULLY_QUALIFIED) )) ) { $name .= $token[1]; } return $name; } /** * Gets the class name. * * @return string The found class name. */ public function parseClass() { // Namespaces and class names are tokenized the same: T_STRINGs // separated by T_NS_SEPARATOR so we can use one function to provide // both. return $this->parseNamespace(); } } phpbench.json.dist000064400000000204144760114740010174 0ustar00{ "bootstrap": "tests/Doctrine/Performance/Common/bootstrap.php", "path": "tests/Doctrine/Performance/Common/Annotations" } phpcs.xml.dist000064400000021763144760114740007366 0ustar00 lib tests */lib/Doctrine/Common/Annotations/DocParser.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/ClassNoNamespaceNoComment.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */tests/Doctrine/Tests/Common/Annotations/Fixtures/* */lib/Doctrine/Common/Annotations/DocParser.php */tests/Doctrine/Tests/Common/Annotations/PhpParserTest.php */tests/* */tests/* */tests/Doctrine/Tests/Common/Annotations/Ticket/DCOM58Test.php */tests/Doctrine/Tests/Common/Annotations/AbstractReaderTest.php */tests/Doctrine/Tests/Common/Annotations/PhpParserTest.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/NamespaceWithClosureDeclaration.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/ClassWithRequire.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/SingleClassLOC1000.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/NamespacedSingleClassLOC1000.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/Controller.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/SingleClassLOC1000.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/NonNamespacedClass.php */tests/Doctrine/Tests/Common/Annotations/Ticket/DCOM58Entity.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/ClassNoNamespaceNoComment.php */tests/Doctrine/Tests/Common/Annotations/TopLevelAnnotation.php */tests/Doctrine/Tests/Common/Annotations/AbstractReaderTest.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/ClassWithValidAnnotationTarget.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/GroupUseStatement.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/AnnotationWithVarType.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/EmptyInterface.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/InterfaceThatExtendsAnInterface.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/InterfaceThatExtendsAnInterface.php */tests/Doctrine/Tests/Common/Annotations/Fixtures/InterfaceWithConstants.php */lib/Doctrine/Common/Annotations/ImplicitlyIgnoredAnnotationNames.php phpstan.neon000064400000001454144760114740007116 0ustar00parameters: excludes_analyse: - %currentWorkingDirectory%/tests/*/Fixtures/* - %currentWorkingDirectory%/tests/Doctrine/Tests/Common/Annotations/ReservedKeywordsClasses.php - %currentWorkingDirectory%/tests/Doctrine/Tests/Common/Annotations/Ticket/DCOM58Entity.php - %currentWorkingDirectory%/tests/Doctrine/Tests/DoctrineTestCase.php polluteScopeWithLoopInitialAssignments: true ignoreErrors: - '#Instantiated class Doctrine_Tests_Common_Annotations_Fixtures_ClassNoNamespaceNoComment not found#' - '#Property Doctrine\\Tests\\Common\\Annotations\\DummyClassNonAnnotationProblem::\$foo has unknown class#' # That tag is empty on purpose - '#PHPDoc tag @var has invalid value \(\)\: Unexpected token "\*/", expected type at offset 9#'