php 8.2

composer.json

@@ -41,7 +41,7 @@
     "doctrine/annotations": "^1.0 || ^2.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^11.0 || ^10.0 || ^9.5",
+    "phpunit/phpunit": "^11.0",
     "mockery/mockery": "1.*",
     "orchestra/testbench": "^9.0 || ^8.0 || 7.* || ^6.15 || 5.*",
     "php-coveralls/php-coveralls": "^2.0"

src/ConfigFactory.php

@@ -7,12 +7,11 @@
 class ConfigFactory
 {
     /**
-     * Get documentation config.
+     * Retrieves and merges the configuration for the specified documentation.
      *
-     * @param  string|null  $documentation
-     * @return array
-     *
-     * @throws L5SwaggerException
+     * @param string|null $documentation The name of the documentation configuration to retrieve. If null, the default documentation configuration is used.
+     * @return array The merged configuration for the specified documentation.
+     * @throws L5SwaggerException If the specified documentation configuration is not found.
      */
     public function documentationConfig(?string $documentation = null): array
     {
@@ -30,6 +29,15 @@ public function documentationConfig(?string $documentation = null): array
         return $this->mergeConfig($defaults, $documentations[$documentation]);
     }
 
+
+    /**
+     * Merges two configuration arrays recursively, with the values from the second array
+     * overriding those in the first array when keys overlap.
+     *
+     * @param array $defaults The default configuration array.
+     * @param array $config The configuration array to merge into the defaults.
+     * @return array The merged configuration array.
+     */
     private function mergeConfig(array $defaults, array $config): array
     {
         $merged = $defaults;
@@ -49,7 +57,13 @@ private function mergeConfig(array $defaults, array $config): array
         return $merged;
     }
 
-    private function isAssociativeArray($value): bool
+    /**
+     * Determines whether a given value is an associative array.
+     *
+     * @param mixed $value The value to be checked.
+     * @return bool True if the value is an associative array, false otherwise.
+     */
+    private function isAssociativeArray(mixed $value): bool
     {
         return is_array($value) && count(array_filter(array_keys($value), 'is_string')) > 0;
     }

src/Console/GenerateDocsCommand.php

@@ -28,14 +28,11 @@ public function __construct()
     protected $description = 'Regenerate docs';
 
     /**
-     * Execute the console command.
-     *
-     * @param  GeneratorFactory  $generatorFactory
-     * @return void
+     * @param GeneratorFactory $generatorFactory
      *
      * @throws L5SwaggerException
      */
-    public function handle(GeneratorFactory $generatorFactory)
+    public function handle(GeneratorFactory $generatorFactory): void
     {
         $all = $this->option('all');
 
@@ -59,12 +56,14 @@ public function handle(GeneratorFactory $generatorFactory)
     }
 
     /**
-     * @param  GeneratorFactory  $generatorFactory
-     * @param  string  $documentation
+     * Generates documentation using the specified generator factory.
      *
+     * @param GeneratorFactory $generatorFactory The factory used to create the documentation generator.
+     * @param string $documentation The name or identifier of the documentation to be generated.
+     * @return void
      * @throws L5SwaggerException
      */
-    private function generateDocumentation(GeneratorFactory $generatorFactory, string $documentation)
+    private function generateDocumentation(GeneratorFactory $generatorFactory, string $documentation): void
     {
         $this->info('Regenerating docs '.$documentation);
 

src/Generator.php

@@ -3,12 +3,14 @@
 namespace L5Swagger;
 
 use Exception;
+use Illuminate\Contracts\Filesystem\FileNotFoundException;
 use Illuminate\Filesystem\Filesystem;
 use Illuminate\Support\Arr;
 use L5Swagger\Exceptions\L5SwaggerException;
 use OpenApi\Annotations\OpenApi;
 use OpenApi\Annotations\Server;
 use OpenApi\Generator as OpenApiGenerator;
+use OpenApi\OpenApiException;
 use OpenApi\Pipeline;
 use OpenApi\Util;
 use Symfony\Component\Finder\Finder;
@@ -32,74 +34,41 @@ class Generator
         self::SCAN_OPTION_EXCLUDE,
     ];
 
-    /**
-     * @var string|array
-     */
-    protected $annotationsDir;
+    protected string|array $annotationsDir;
 
-    /**
-     * @var string
-     */
-    protected $docDir;
+    protected string $docDir;
 
-    /**
-     * @var string
-     */
-    protected $docsFile;
+    protected string $docsFile;
 
-    /**
-     * @var string
-     */
-    protected $yamlDocsFile;
+    protected string $yamlDocsFile;
 
-    /**
-     * @var array
-     */
-    protected $excludedDirs;
+    protected array $excludedDirs;
 
-    /**
-     * @var array
-     */
-    protected $constants;
+    protected array $constants;
 
-    /**
-     * @var OpenApi
-     */
-    protected $openApi;
+    protected OpenApi $openApi;
 
-    /**
-     * @var bool
-     */
-    protected $yamlCopyRequired;
+    protected bool $yamlCopyRequired;
 
-    /**
-     * @var string
-     */
-    protected $basePath;
+    protected ?string $basePath;
 
-    /**
-     * @var SecurityDefinitions
-     */
-    protected $security;
+    protected SecurityDefinitions $security;
 
-    /**
-     * @var array
-     */
-    protected $scanOptions;
+    protected array $scanOptions;
 
-    /**
-     * @var ?Filesystem
-     */
-    protected $fileSystem;
+    protected ?Filesystem $fileSystem;
 
     /**
-     * Generator constructor.
+     * Constructor to initialize documentation generation settings and dependencies.
+     *
+     * @param array $paths Array of paths including annotations, docs, excluded directories, and base path.
+     * @param array $constants Array of constants to be used during documentation generation.
+     * @param bool $yamlCopyRequired Determines if a YAML copy of the documentation is required.
+     * @param SecurityDefinitions $security Security definitions for the documentation.
+     * @param array $scanOptions Additional options for scanning files or directories.
+     * @param Filesystem|null $filesystem Filesystem instance, optional, defaults to a new Filesystem.
      *
-     * @param  array  $paths
-     * @param  array  $constants
-     * @param  bool  $yamlCopyRequired
-     * @param  SecurityDefinitions  $security
-     * @param  array  $scanOptions
+     * @return void
      */
     public function __construct(
         array $paths,
@@ -124,7 +93,12 @@ public function __construct(
     }
 
     /**
+     * Generate necessary documentation files by scanning and processing the required data.
+     *
+     * @return void
+     *
      * @throws L5SwaggerException
+     * @throws Exception
      */
     public function generateDocs(): void
     {
@@ -137,11 +111,11 @@ public function generateDocs(): void
     }
 
     /**
-     * Check directory structure and permissions.
+     * Prepares the directory for storing documentation by ensuring it exists and is writable.
      *
-     * @return Generator
+     * @return self
      *
-     * @throws L5SwaggerException
+     * @throws L5SwaggerException If the directory is not writable or cannot be created.
      */
     protected function prepareDirectory(): self
     {
@@ -161,9 +135,9 @@ protected function prepareDirectory(): self
     }
 
     /**
-     * Define constant which will be replaced.
+     * Define and set constants if not already defined.
      *
-     * @return Generator
+     * @return self
      */
     protected function defineConstants(): self
     {
@@ -177,9 +151,9 @@ protected function defineConstants(): self
     }
 
     /**
-     * Scan directory and create Swagger.
+     * Scans files to generate documentation.
      *
-     * @return Generator
+     * @return self
      */
     protected function scanFilesForDocumentation(): self
     {
@@ -195,28 +169,23 @@ protected function scanFilesForDocumentation(): self
     }
 
     /**
-     * Prepares generator for generating the documentation.
+     * Create and configure an instance of OpenApiGenerator.
      *
-     * @return OpenApiGenerator $generator
+     * @return OpenApiGenerator
      */
     protected function createOpenApiGenerator(): OpenApiGenerator
     {
         $generator = new OpenApiGenerator();
 
-        // Only from zircote/swagger-php 4
         if (! empty($this->scanOptions['default_processors_configuration'])
             && is_array($this->scanOptions['default_processors_configuration'])
-            && method_exists($generator, 'setConfig')
         ) {
             $generator->setConfig($this->scanOptions['default_processors_configuration']);
         }
 
-        // OpenApi spec version - only from zircote/swagger-php 4
-        if (method_exists($generator, 'setVersion')) {
-            $generator->setVersion(
-                $this->scanOptions['open_api_spec_version'] ?? self::OPEN_API_DEFAULT_SPEC_VERSION
-            );
-        }
+        $generator->setVersion(
+            $this->scanOptions['open_api_spec_version'] ?? self::OPEN_API_DEFAULT_SPEC_VERSION
+        );
 
         // Processors.
         $this->setProcessors($generator);
@@ -228,7 +197,10 @@ protected function createOpenApiGenerator(): OpenApiGenerator
     }
 
     /**
-     * @param  OpenApiGenerator  $generator
+     * Set the processors for the OpenAPI generator.
+     *
+     * @param OpenApiGenerator $generator The OpenAPI generator instance to configure.
+     *
      * @return void
      */
     protected function setProcessors(OpenApiGenerator $generator): void
@@ -253,7 +225,10 @@ function (callable $pipe) use ($processorClasses, &$newPipeLine) {
     }
 
     /**
-     * @param  OpenApiGenerator  $generator
+     * Set the analyser for the OpenAPI generator based on scan options.
+     *
+     * @param OpenApiGenerator $generator The OpenAPI generator instance.
+     *
      * @return void
      */
     protected function setAnalyser(OpenApiGenerator $generator): void
@@ -266,7 +241,7 @@ protected function setAnalyser(OpenApiGenerator $generator): void
     }
 
     /**
-     * Prepares finder for determining relevant files.
+     * Create and return a Finder instance configured for scanning directories.
      *
      * @return Finder
      */
@@ -281,9 +256,9 @@ protected function createScanFinder(): Finder
     }
 
     /**
-     * Generate servers section or basePath depending on Swagger version.
+     * Populate the servers list in the OpenAPI configuration using the base path.
      *
-     * @return Generator
+     * @return self
      */
     protected function populateServers(): self
     {
@@ -299,11 +274,12 @@ protected function populateServers(): self
     }
 
     /**
-     * Save documentation as json file.
+     * Saves the JSON data and applies security measures to the file.
      *
-     * @return Generator
+     * @return self
      *
-     * @throws Exception
+     * @throws FileNotFoundException
+     * @throws OpenApiException
      */
     protected function saveJson(): self
     {
@@ -315,7 +291,14 @@ protected function saveJson(): self
     }
 
     /**
-     * Save documentation as yaml file.
+     * Creates a YAML copy of the OpenAPI documentation if required.
+     *
+     * This method converts the JSON documentation file to YAML format and saves it
+     * to the specified file path when the YAML copy requirement is enabled.
+     *
+     * @return void
+     *
+     * @throws FileNotFoundException
      */
     protected function makeYamlCopy(): void
     {