Install & run PHP-CS-Fixer (#2250)

* Install, configure & use PHP-CS-Fixer

* Run PHP-CS-Fixer

* Extract dependency setup to composite action

* Replace StyleCI with PHP-CS-Fixer workflow job

* Remove 'nullable_type_declaration_for_default_null_value' rule

* Apply suggestions from code review

---------

Co-authored-by: Djordy Koert <djordy.koert@live.nl>

.github/workflows/common/composer-install/action.yaml

@@ -0,0 +1,51 @@
+name: Composer setup
+description: Setup, install and cache Composer dependencies
+
+inputs:
+  symfony-version:
+    description: The required Symfony version that will be installed
+    required: true
+    type: string
+
+  install-doctrine-annotations:
+    description: If the doctrine/annotations package should be additionally installed as a dependency
+    required: true
+    type: boolean
+
+  composer-flags:
+    description: Additional flags that are passed to the `composer update` step
+    required: false
+    type: string
+
+runs:
+  using: composite
+  steps:
+    - name: Get Composer cache directory
+      id: composer-cache
+      run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+      shell: bash
+
+    - name: Cache Composer dependencies
+      uses: actions/cache@v3
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+        restore-keys: |
+          ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+          ${{ runner.os }}-composer-
+
+    - name: Install doctrine/annotations
+      if: ${{ inputs.install-doctrine-annotations == 'true' }}
+      run: composer require --no-update doctrine/annotations
+      shell: bash
+
+    - name: Remove packages not compatible Symfony 7
+      if: ${{ inputs.symfony-version == '7.0.*' }}
+      run: composer remove --dev --no-update friendsofsymfony/rest-bundle sensio/framework-extra-bundle
+      shell: bash
+
+    - name: Install dependencies with Composer
+      env:
+        SYMFONY_REQUIRE: ${{ inputs.symfony-version }}
+      run: composer update --no-interaction --no-progress ${{ inputs.composer-flags }}
+      shell: bash

.github/workflows/continuous-integration.yml

@@ -1,7 +1,7 @@
 # from doctrine/instantiator:
 # https://github.com/doctrine/instantiator/blob/97aa11bb71ad6259a8c5a1161b4de2d6cdcc5501/.github/workflows/continuous-integration.yml
 
-name: "CI"
+name: CI
 
 on:
   pull_request:
@@ -18,8 +18,8 @@ env:
 
 jobs:
   phpunit:
-    name: "PHPUnit"
-    runs-on: "ubuntu-22.04"
+    name: PHPUnit
+    runs-on: ubuntu-22.04
 
     strategy:
       fail-fast: false
@@ -54,43 +54,50 @@ jobs:
             doctrine-annotations: false
 
     steps:
-      - name: "Checkout"
+      - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 2
 
-      - name: "Install PHP without coverage"
+      - name: Install PHP without coverage
         uses: shivammathur/setup-php@v2
         with:
-          php-version: "${{ matrix.php-version }}"
+          php-version: ${{ matrix.php-version }}
           tools: composer, flex
           coverage: pcov
 
-      - name: "Get composer cache directory"
-        id: composercache
-        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache dependencies"
-        uses: actions/cache@v3
+      - name: Setup dependencies
+        uses: ./.github/workflows/common/composer-install
         with:
-          path: ${{ steps.composercache.outputs.dir }}
-          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
-          restore-keys: ${{ runner.os }}-composer-
+          symfony-version: ${{ matrix.symfony-require }}
+          install-doctrine-annotations: ${{ matrix.doctrine-annotations }}
+          composer-flags: ${{ matrix.composer-flags }}
 
-      - name: Install doctrine/annotations
-        if: matrix.doctrine-annotations == true
-        run: |
-          composer require doctrine/annotations --no-update
+      - name: PHPUnit Tests
+        run: vendor/bin/phpunit --configuration phpunit.xml.dist --coverage-text
 
-      - name: Remove packages not compatible symfony 7
-        if: matrix.symfony-require == '7.0.*'
-        run: |
-          composer remove friendsofsymfony/rest-bundle sensio/framework-extra-bundle --no-update --dev
+  php-cs-fixer:
+    name: PHP-CS-Fixer
+    runs-on: ubuntu-22.04
 
-      - name: "Install dependencies with composer"
-        env:
-          SYMFONY_REQUIRE: "${{ matrix.symfony-require }}"
-        run: composer update --no-interaction --no-progress ${{ matrix.composer-flags }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
-      - name: "PHPUnit Tests"
-        run: vendor/bin/phpunit --configuration phpunit.xml.dist --coverage-text
+      - name: Install PHP without coverage
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          tools: composer, flex
+          coverage: pcov
+
+      - name: Setup dependencies
+        uses: ./.github/workflows/common/composer-install
+        with:
+          symfony-version: "7.0.*"
+          install-doctrine-annotations: false
+
+      - name: Run PHP-CS-Fixer
+        run: vendor/bin/php-cs-fixer check -v --diff

.gitignore

@@ -2,11 +2,14 @@
 /vendor/
 /composer.phar
 /composer.lock
-/.php_cs.cache
-/.php_cs
 /phpunit.xml
 /.phpunit
 /.phpunit.result.cache
 /Tests/Functional/cache
 /Tests/Functional/logs
 .idea
+
+###> friendsofphp/php-cs-fixer ###
+/.php-cs-fixer.php
+/.php-cs-fixer.cache
+###< friendsofphp/php-cs-fixer ###

.php_cs.dist → .php-cs-fixer.dist.php

@@ -1,16 +1,15 @@
 <?php
 
-$finder = PhpCsFixer\Finder::create()
+declare(strict_types=1);
+
+$finder = (new PhpCsFixer\Finder())
     ->in(__DIR__)
     ->exclude('var')
-    ->exclude('Tests/Functional/cache')
-;
+    ->exclude('tests/Functional/cache');
 
-return PhpCsFixer\Config::create()
+return (new PhpCsFixer\Config())
     ->setRules([
         '@Symfony' => true,
-        'ordered_imports' => true,
-        'phpdoc_order' => true,
         'header_comment' => [
             'header' => <<<HEADER
 This file is part of the NelmioApiDocBundle package.
@@ -22,5 +21,4 @@
 HEADER
         ],
     ])
-    ->setFinder($finder)
-;
+    ->setFinder($finder);

composer.json

@@ -55,7 +55,8 @@
         "composer/package-versions-deprecated": "1.11.99.1",
 
         "phpunit/phpunit": "^8.5|^9.6",
-        "doctrine/annotations": "^2.0"
+        "doctrine/annotations": "^2.0",
+        "friendsofphp/php-cs-fixer": "^3.52"
     },
     "conflict": {
         "zircote/swagger-php": "4.8.7"
@@ -91,9 +92,13 @@
         }
     },
     "scripts-descriptions": {
+        "phpcs-check": "Run PHP-CS-Fixer in dry-run mode",
+        "phpcs-fix": "Run PHP-CS-Fixer",
         "phpunit": "Run phpunit"
     },
     "scripts": {
+        "phpcs-check": "vendor/bin/php-cs-fixer check -v --diff",
+        "phpcs-fix": "vendor/bin/php-cs-fixer fix -v",
         "phpunit": "phpunit"
     }
 }

src/Annotation/Model.php

@@ -21,7 +21,6 @@
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class Model extends Attachable
 {
-    /** {@inheritdoc} */
     public static $_types = [
         'type' => 'string',
         'groups' => '[string]',
@@ -63,8 +62,8 @@ final class Model extends Attachable
     public function __construct(
         array $properties = [],
         string $type = Generator::UNDEFINED,
-        array $groups = null,
-        array $options = null,
+        ?array $groups = null,
+        ?array $options = null,
         array $serializationContext = []
     ) {
         parent::__construct($properties + [

src/Annotation/Security.php

@@ -19,7 +19,6 @@
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 class Security extends AbstractAnnotation
 {
-    /** {@inheritdoc} */
     public static $_types = [
         'name' => 'string',
         'scopes' => '[string]',
@@ -39,7 +38,7 @@ class Security extends AbstractAnnotation
 
     public function __construct(
         array $properties = [],
-        string $name = null,
+        ?string $name = null,
         array $scopes = []
     ) {
         parent::__construct($properties + [

src/ApiDocGenerator.php

@@ -51,7 +51,7 @@ final class ApiDocGenerator
     /**
      * @var ?string
      */
-    private $openApiVersion = null;
+    private $openApiVersion;
 
     /** @var Generator */
     private $generator;
@@ -60,7 +60,7 @@ final class ApiDocGenerator
      * @param DescriberInterface[]|iterable      $describers
      * @param ModelDescriberInterface[]|iterable $modelDescribers
      */
-    public function __construct($describers, $modelDescribers, CacheItemPoolInterface $cacheItemPool = null, string $cacheItemId = null, Generator $generator = null)
+    public function __construct($describers, $modelDescribers, ?CacheItemPoolInterface $cacheItemPool = null, ?string $cacheItemId = null, ?Generator $generator = null)
     {
         $this->describers = $describers;
         $this->modelDescribers = $modelDescribers;

src/Controller/YamlDocumentationController.php

@@ -11,7 +11,6 @@
 
 namespace Nelmio\ApiDocBundle\Controller;
 
-use InvalidArgumentException;
 use Nelmio\ApiDocBundle\Render\RenderOpenApi;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -39,7 +38,7 @@ public function __invoke(Request $request, $area = 'default')
             );
 
             return $response->setCharset('UTF-8');
-        } catch (InvalidArgumentException $e) {
+        } catch (\InvalidArgumentException $e) {
             throw new BadRequestHttpException(sprintf('Area "%s" is not supported as it isn\'t defined in config.', $area));
         }
     }

src/DependencyInjection/NelmioApiDocExtension.php

@@ -47,9 +47,6 @@
 
 final class NelmioApiDocExtension extends Extension implements PrependExtensionInterface
 {
-    /**
-     * {@inheritdoc}
-     */
     public function prepend(ContainerBuilder $container): void
     {
         $container->prependExtensionConfig('framework', ['property_info' => ['enabled' => true]]);
@@ -62,9 +59,6 @@ public function prepend(ContainerBuilder $container): void
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function load(array $configs, ContainerBuilder $container): void
     {
         $config = $this->processConfiguration(new Configuration(), $configs);

src/Describer/OpenApiPhpDescriber.php

@@ -144,10 +144,10 @@ public function describe(OA\OpenApi $api)
                 }
 
                 if (
-                    !$annotation instanceof OA\Response &&
-                    !$annotation instanceof OA\RequestBody &&
-                    !$annotation instanceof OA\Parameter &&
-                    !$annotation instanceof OA\ExternalDocumentation
+                    !$annotation instanceof OA\Response
+                    && !$annotation instanceof OA\RequestBody
+                    && !$annotation instanceof OA\Parameter
+                    && !$annotation instanceof OA\ExternalDocumentation
                 ) {
                     throw new \LogicException(sprintf('Using the annotation "%s" as a root annotation in "%s::%s()" is not allowed.', get_class($annotation), $method->getDeclaringClass()->name, $method->name));
                 }

src/Exception/UndocumentedArrayItemsException.php

@@ -19,7 +19,7 @@ class UndocumentedArrayItemsException extends \LogicException
     private $class;
     private $path;
 
-    public function __construct(string $class = null, string $path = '')
+    public function __construct(?string $class = null, string $path = '')
     {
         $this->class = $class;
         $this->path = $path;

src/Model/Model.php

@@ -23,7 +23,7 @@ final class Model
     /**
      * @param string[]|null $groups
      */
-    public function __construct(Type $type, array $groups = null, array $options = null, array $serializationContext = [])
+    public function __construct(Type $type, ?array $groups = null, ?array $options = null, array $serializationContext = [])
     {
         $this->type = $type;
         $this->options = $options;

src/ModelDescriber/Annotations/AnnotationsReader.php

@@ -54,7 +54,7 @@ public function getPropertyName($reflection, string $default): string
         return $this->openApiAnnotationsReader->getPropertyName($reflection, $default);
     }
 
-    public function updateProperty($reflection, OA\Property $property, array $serializationGroups = null): void
+    public function updateProperty($reflection, OA\Property $property, ?array $serializationGroups = null): void
     {
         $this->openApiAnnotationsReader->updateProperty($reflection, $property, $serializationGroups);
         $this->phpDocReader->updateProperty($reflection, $property);

src/ModelDescriber/Annotations/OpenApiAnnotationsReader.php

@@ -67,7 +67,7 @@ public function getPropertyName($reflection, string $default): string
         return Generator::UNDEFINED !== $oaProperty->property ? $oaProperty->property : $default;
     }
 
-    public function updateProperty($reflection, OA\Property $property, array $serializationGroups = null): void
+    public function updateProperty($reflection, OA\Property $property, ?array $serializationGroups = null): void
     {
         /** @var OA\Property|null $oaProperty */
         if (!$oaProperty = $this->getAnnotation($property->_context, $reflection, OA\Property::class)) {
@@ -86,8 +86,6 @@ public function updateProperty($reflection, OA\Property $property, array $serial
 
     /**
      * @param \ReflectionClass|\ReflectionProperty|\ReflectionMethod $reflection
-     *
-     * @return mixed
      */
     private function getAnnotation(Context $parentContext, $reflection, string $className)
     {

src/ModelDescriber/BazingaHateoasModelDescriber.php

@@ -41,9 +41,6 @@ public function setModelRegistry(ModelRegistry $modelRegistry)
         $this->JMSModelDescriber->setModelRegistry($modelRegistry);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function describe(Model $model, OA\Schema $schema): void
     {
         $this->JMSModelDescriber->describe($model, $schema);
@@ -106,9 +103,6 @@ private function getHateoasMetadata(Model $model)
         return null;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function supports(Model $model): bool
     {
         return $this->JMSModelDescriber->supports($model) || null !== $this->getHateoasMetadata($model);