diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index e8bbfdfd..bc6d95b3 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -15,20 +15,8 @@ jobs: fail-fast: true matrix: operating-system: [ ubuntu-latest ] - php: [ '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ] + php: [ '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ] dependencies: [ 'lowest', 'highest' ] - exclude: - - php: '8.1' - dependencies: 'lowest' - - php: '8.2' - dependencies: 'lowest' - - php: '8.3' - dependencies: 'lowest' - - php: '8.4' - dependencies: 'lowest' - include: - - php: '8.2' - composer-options: "--ignore-platform-req=php+" name: PHP ${{ matrix.php }} on ${{ matrix.operating-system }} with ${{ matrix.dependencies }} dependencies @@ -50,8 +38,3 @@ jobs: - name: PHPUnit Tests run: bin/phpunit --configuration phpunit.xml.dist --coverage-text - - - name: PHPUnit Legacy Tests - run: bin/phpunit --configuration phpunit.xml.dist --coverage-text - env: - PHPUNIT_ANALYSER: 'legacy' diff --git a/.github/workflows/security-checks.yml b/.github/workflows/security-checks.yml index 949602e0..f6474c3a 100644 --- a/.github/workflows/security-checks.yml +++ b/.github/workflows/security-checks.yml @@ -15,7 +15,7 @@ jobs: fail-fast: true matrix: operating-system: [ ubuntu-latest ] - php: [ '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ] + php: [ '7.4', '8.0', '8.1', '8.2', '8.3', '8.4' ] dependencies: [ 'highest' ] name: PHP ${{ matrix.php }} on ${{ matrix.operating-system }} with ${{ matrix.dependencies }} dependencies diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php index 2affc46d..93291364 100644 --- a/.php-cs-fixer.dist.php +++ b/.php-cs-fixer.dist.php @@ -6,9 +6,15 @@ $finder = PhpCsFixer\Finder::create() ->path('src')->name('*.php') ->path('tests')->name('*.php') - // ContextTest::testFullyQualifiedName relies on the 'use Exception' statement... ->filter(function (\SplFileInfo $file) { - return !strpos($file->getPathname(), 'tests/Fixtures/Customer.php'); + return + // ContextTest::testFullyQualifiedName relies on the 'use Exception' statement... + !strpos($file->getPathname(), 'tests/Fixtures/Customer.php') + // multi arg use; 'use a, b;` + && !strpos($file->getPathname(), 'tests/Fixtures/Parser/HelloTrait.php') + // FQDN in docblock + && !strpos($file->getPathname(), 'tests/Fixtures/TypedProperties.php') + ; }) ->path('Examples')->name('*.php') ->filter(function (\SplFileInfo $file) { @@ -24,10 +30,11 @@ (new ScopedDeclareStrictTypesFixer())->scope(['/src/', '/tests/']), ]) ->setRules([ - '@PSR2' => true, + '@PSR12' => true, '@DoctrineAnnotation' => true, 'OpenApi/license' => true, 'OpenApi/declare_strict_types' => true, + 'blank_line_after_opening_tag' => false, 'array_syntax' => ['syntax' => 'short'], 'no_unused_imports' => true, 'blank_line_before_statement' => ['statements' => ['return']], diff --git a/README.md b/README.md index 30764f6e..7f1ac3b2 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # swagger-php -Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or +Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (requires additional `doctrine/annotations` library). See the [documentation website](https://zircote.github.io/swagger-php/guide/attributes.html) for supported attributes and annotations. @@ -98,9 +98,6 @@ The `openapi` command line interface can be used to generate the documentation t ```shell ./vendor/bin/openapi --help ``` -Starting with version 4 the default analyser used on the command line is the new `ReflectionAnalyser`. - -Using the `--legacy` flag (`-l`) the legacy `TokenAnalyser` can still be used. ### Usage from the Deserializer diff --git a/bin/openapi b/bin/openapi index a41fa0d7..dae40fbb 100755 --- a/bin/openapi +++ b/bin/openapi @@ -4,7 +4,6 @@ use OpenApi\Analysers\AttributeAnnotationFactory; use OpenApi\Analysers\DocBlockAnnotationFactory; use OpenApi\Analysers\ReflectionAnalyser; -use OpenApi\Analysers\TokenAnalyser; use OpenApi\Annotations\OpenApi; use OpenApi\Generator; use OpenApi\Util; @@ -23,7 +22,6 @@ error_reporting(E_ALL); // Possible options and their default values. $options = [ 'config' => [], - 'legacy' => false, 'output' => false, 'format' => 'auto', 'exclude' => [], @@ -36,7 +34,6 @@ $options = [ ]; $aliases = [ 'c' => 'config', - 'l' => 'legacy', 'o' => 'output', 'e' => 'exclude', 'n' => 'pattern', @@ -132,7 +129,6 @@ Usage: openapi [--option value] [/path/to/project ...] Options: --config (-c) Generator config ex: -c operationId.hash=false - --legacy (-l) Use legacy TokenAnalyser; default is the new ReflectionAnalyser --output (-o) Path to store the generated documentation. ex: --output openapi.yaml --exclude (-e) Exclude path(s). @@ -222,9 +218,7 @@ foreach ($options["processor"] as $processor) { $generator->getProcessorPipeline()->add($processor); } -$analyser = $options['legacy'] - ? new TokenAnalyser() - : new ReflectionAnalyser([new DocBlockAnnotationFactory(), new AttributeAnnotationFactory()]); +$analyser = new ReflectionAnalyser([new DocBlockAnnotationFactory(), new AttributeAnnotationFactory()]); $openapi = $generator ->setVersion($options['version']) diff --git a/composer.json b/composer.json index 62414402..1dce1a1f 100644 --- a/composer.json +++ b/composer.json @@ -40,16 +40,17 @@ "minimum-stability": "stable", "extra": { "branch-alias": { - "dev-master": "4.x-dev" + "dev-master": "5.x-dev" } }, "require": { - "php": ">=7.2", + "php": ">=7.4", "ext-json": "*", + "nikic/php-parser": "^4.19", "psr/log": "^1.1 || ^2.0 || ^3.0", "symfony/deprecation-contracts": "^2 || ^3", - "symfony/finder": ">=2.2", - "symfony/yaml": ">=3.3" + "symfony/finder": "^5.0 || ^6.0 || ^7.0", + "symfony/yaml": "^5.0 || ^6.0 || ^7.0" }, "autoload": { "psr-4": { @@ -58,17 +59,18 @@ }, "require-dev": { "composer/package-versions-deprecated": "^1.11", - "doctrine/annotations": "^1.7 || ^2.0", - "friendsofphp/php-cs-fixer": "^2.17 || 3.62.0", + "doctrine/annotations": "^2.0", + "friendsofphp/php-cs-fixer": "^3.62.0", "phpstan/phpstan": "^1.6", - "phpunit/phpunit": ">=8", - "vimeo/psalm": "^4.23" + "phpunit/phpunit": "^9.0", + "rector/rector": "^1.0", + "vimeo/psalm": "^4.30" }, "conflict": { "symfony/process": ">=6, <6.4.14" }, "suggest": { - "doctrine/annotations": "^1.7 || ^2.0" + "doctrine/annotations": "^2.0" }, "autoload-dev": { "exclude-from-classmap": [ @@ -82,10 +84,9 @@ }, "scripts-descriptions": { "cs": "Fix all codestyle issues", + "rector": "Automatic refactoring", "lint": "Test codestyle", - "test": "Run all non-legacy and codestyle tests", - "testlegacy": "Run tests using the legacy TokenAnalyser", - "testall": "Run all tests (test + testlegacy)", + "test": "Run all PHP, codestyle and rector tests", "analyse": "Run static analysis (phpstan/psalm)", "spectral-examples": "Run spectral lint over all .yaml files in the Examples folder", "spectral-scratch": "Run spectral lint over all .yaml files in the tests/Fixtures/Scratch folder", @@ -96,16 +97,15 @@ }, "scripts": { "cs": "export XDEBUG_MODE=off && php-cs-fixer fix --allow-risky=yes", - "lint": "@cs --dry-run", + "rector": "rector process src", + "lint": [ + "@cs --dry-run", + "@rector --dry-run" + ], "test": [ "export XDEBUG_MODE=off && phpunit", "@lint" ], - "testlegacy": "export XDEBUG_MODE=off && export PHPUNIT_ANALYSER=legacy && phpunit", - "testall": [ - "@test", - "@testlegacy" - ], "analyse": [ "export XDEBUG_MODE=off && phpstan analyse --memory-limit=2G", "export XDEBUG_MODE=off && psalm" diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 670afcf1..4a04e2c3 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -20,6 +20,7 @@ function getGuideSidebar() { { text: 'Upgrading', children: [ + { text: 'Migration from 4.x to 5.x', link: '/guide/migrating-to-v5' }, { text: 'Migration from 3.x to 4.x', link: '/guide/migrating-to-v4' }, { text: 'Migration from 2.x to 3.x', link: '/guide/migrating-to-v3' }, ] diff --git a/docs/guide/generating-openapi-documents.md b/docs/guide/generating-openapi-documents.md index 92fa204b..e19ba23e 100644 --- a/docs/guide/generating-openapi-documents.md +++ b/docs/guide/generating-openapi-documents.md @@ -36,7 +36,6 @@ Usage: openapi [--option value] [/path/to/project ...] Options: --config (-c) Generator config ex: -c operationId.hash=false - --legacy (-l) Use legacy TokenAnalyser; default is the new ReflectionAnalyser --output (-o) Path to store the generated documentation. ex: --output openapi.yaml --exclude (-e) Exclude path(s). diff --git a/docs/guide/migrating-to-v5.md b/docs/guide/migrating-to-v5.md new file mode 100644 index 00000000..387fba67 --- /dev/null +++ b/docs/guide/migrating-to-v5.md @@ -0,0 +1,15 @@ +# Migrating to v5 + +## Overview + +v5 is mostly a cleanup release with updated dependencies. The main changes are: + +* Minimum required PHP version is now 7.4 +* The legacy `TokenAnalyser` and the `--legacy` CLI option have been removed +* Defaults now prefer attributes over annotations +* PHP parsing now uses `nicic/php-parser` +* Removal of deprecated features + * empty/unused `ProcessorInterface` + * `Context::clone()` and `Context::detect()` + +For most installations upgrading should not require any changes. diff --git a/docs/guide/under-the-hood.md b/docs/guide/under-the-hood.md index 7ee2dbb1..7506bf12 100644 --- a/docs/guide/under-the-hood.md +++ b/docs/guide/under-the-hood.md @@ -5,6 +5,7 @@ - The `Generator` iterates over the given sources (Symfony `Finder`, file/directory list, etc) - The configured analyser (`AnalyserInterface`) reads the files and builds an `Analysis` object. Default (as of v4) is the `ReflectionAnalyser`. Alternatively, there is the `TokenAnalyser` which was the default in v3. +- The legacy `TokenAnalyser` was removed in v5. - The `Analysis` object and its annotations are then processed by the configured processors. - If enabled, the analysis/annotations are validated. - The root `OpenApi` annotation then contains all annotations and is serialized into YAML/JSON. @@ -16,7 +17,7 @@ about the PHP context where the annotation was found. Typically, there will be a processor that uses the data to augment/enrich the annotation. -**Examples of the data collected:** +**Examples of the data collected:** - class/interface/trait/enum names - property names - doctype or native type hints @@ -35,7 +36,7 @@ This documentation is generated with [VitePress](https://vitepress.vuejs.org/) ### Installation ```shell cd docs -npm install vitepress +npm install vitepress ``` ### Workflow diff --git a/docs/index.md b/docs/index.md index 84a7a3fa..ab34f8e2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,10 @@ features: ### 2. Update your code -Add `swagger-php` attributes or annotations to your source code. +Add `swagger-php` attributes (or legacy annotations) to your source code. + +⚠️ `doctrine/annotations` is going to be deprecated in the future, so wherever +possible attributes should be used.