Merge branch 'master' into 158-ability-to-generate-documentation-for-invokable-controllers

Author: RGO230

composer.json

@@ -17,13 +17,14 @@
   "require": {
     "php": "^8.3",
     "laravel/framework": ">=11.34",
-    "phpunit/phpunit": "^11.4",
+    "phpunit/phpunit": ">=11.4",
     "ext-json": "*"
   },
   "require-dev": {
-    "orchestra/testbench": "^9.3",
+    "orchestra/testbench": ">=9.3",
     "php-coveralls/php-coveralls": "^2.7",
-    "php-mock/php-mock-phpunit": "^2.10"
+    "php-mock/php-mock-phpunit": ">=2.10",
+    "ronasit/laravel-helpers": "^3.4"
   },
   "autoload": {
     "psr-4": {

composer.lock

@@ -47,7 +47,7 @@
         'title' => env('APP_NAME', 'Name of Your Application'),
         'termsOfService' => '',
         'contact' => [
-            'email' => null
+            'email' => null,
         ],
         'license' => [
             'name' => '',
@@ -184,5 +184,32 @@
         'development',
     ],
 
-    'config_version' => '2.8',
+    /*
+    |--------------------------------------------------------------------------
+    | Paratests
+    |--------------------------------------------------------------------------
+    |
+    | The config for parallel tests execution setup
+    */
+    'paratests' => [
+        'tmp_file_lock' => [
+            /*
+            |--------------------------------------------------------------------------
+            | Maximum attempts count, int
+            |--------------------------------------------------------------------------
+            | The maximum number of attempts to append data to a temporary documentation file
+            */
+            'max_retries' => 20,
+
+            /*
+            |--------------------------------------------------------------------------
+            | Wait time between attempts, microseconds
+            |--------------------------------------------------------------------------
+            | The waiting time between attempts to write to the temporary documentation file while the file is locked
+            */
+            'wait_time' => 500,
+        ],
+    ],
+
+    'config_version' => '2.9',
 ];

config/auto-doc.php

@@ -43,8 +43,13 @@ passing PHPUnit tests.
 > ],
 > ```
 
-2. Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
-1. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\app.php`:
+2. Run
+
+```
+php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider
+```
+
+3. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\app.php`:
 
 ```php
     return Application::configure(basePath: dirname(__DIR__))
@@ -57,7 +62,8 @@ passing PHPUnit tests.
 ```
 
 4. Add `\RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait` trait to `tests/TestCase.php`
-1. Configure documentation saving using one of the next ways:
+
+5. Configure documentation saving using one of the next ways:
   - Add `SwaggerExtension` to the `<extensions>` block of your `phpunit.xml`.
   **Please note that this way will be removed after updating**
   **PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)**
@@ -232,4 +238,3 @@ can be found in the [Contributing guide](CONTRIBUTING.md).
 ## License
 
 Laravel Swagger plugin is open-sourced software licensed under the [MIT license](LICENSE).
- 

readme.md

@@ -5,16 +5,28 @@
 interface SwaggerDriverContract
 {
     /**
-     * Save temporary data
+     * Add current process tmp data to the temp documentation file
+     *
+     * @param callable $appendDataCallback with 1 array argument, containing the current temp file content as array
+     */
+    public function appendProcessDataToTmpFile(callable $appendDataCallback): void;
+
+    /**
+     * Get temporary data from the temp file shared between all PHPUnit processes
+     */
+    public function getTmpData(): ?array;
+
+    /**
+     * Save current process temporary data
      *
      * @param array $data
      */
-    public function saveTmpData($data);
+    public function saveProcessTmpData(array $data): void;
 
     /**
-     * Get temporary data
+     * Get current process temporary data
      */
-    public function getTmpData();
+    public function getProcessTmpData(): ?array;
 
     /**
      * Save production data

src/Contracts/SwaggerDriverContract.php

@@ -2,37 +2,70 @@
 
 namespace RonasIT\AutoDoc\Drivers;
 
+use Illuminate\Support\Facades\ParallelTesting;
 use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
+use RonasIT\AutoDoc\Support\Mutex;
 
 abstract class BaseDriver implements SwaggerDriverContract
 {
     protected string $tempFilePath;
+    protected string $processTempFilePath;
+    protected Mutex $mutex;
 
     public function __construct()
     {
         $this->tempFilePath = storage_path('temp_documentation.json');
+
+        $this->processTempFilePath = ($token = ParallelTesting::token())
+            ? storage_path("temp_documentation_{$token}.json")
+            : $this->tempFilePath;
+
+        $this->mutex = new Mutex(
+            maxRetries: config('auto-doc.paratests.tmp_file_lock.max_retries'),
+            waitTime: config('auto-doc.paratests.tmp_file_lock.wait_time'),
+        );
     }
 
-    public function saveTmpData($data): void
+    public function saveProcessTmpData(array $data): void
     {
-        file_put_contents($this->tempFilePath, json_encode($data));
+        file_put_contents($this->processTempFilePath, json_encode($data));
     }
 
-    public function getTmpData(): ?array
+    public function getProcessTmpData(): ?array
     {
-        if (file_exists($this->tempFilePath)) {
-            $content = file_get_contents($this->tempFilePath);
+        if (file_exists($this->processTempFilePath)) {
+            $content = file_get_contents($this->processTempFilePath);
 
             return json_decode($content, true);
         }
 
         return null;
     }
 
-    protected function clearTmpData(): void
+    public function appendProcessDataToTmpFile(callable $appendDataCallback): void
+    {
+        $this->mutex->writeFileWithLock($this->tempFilePath, function (string $tempFileContent) use ($appendDataCallback) {
+            $resultDocContent = $appendDataCallback(json_decode($tempFileContent, true));
+
+            return json_encode($resultDocContent);
+        });
+    }
+
+    public function getTmpData(): ?array
     {
         if (file_exists($this->tempFilePath)) {
-            unlink($this->tempFilePath);
+            $data = $this->mutex->readFileWithLock($this->tempFilePath);
+
+            return json_decode($data, true);
+        }
+
+        return null;
+    }
+
+    protected function clearProcessTmpData(): void
+    {
+        if (file_exists($this->processTempFilePath)) {
+            unlink($this->processTempFilePath);
         }
     }
 }

src/Drivers/BaseDriver.php

@@ -24,7 +24,7 @@ public function saveData(): void
     {
         file_put_contents($this->prodFilePath, json_encode($this->getTmpData()));
 
-        $this->clearTmpData();
+        $this->clearProcessTmpData();
     }
 
     public function getDocumentation(): array

src/Drivers/LocalDriver.php

@@ -28,7 +28,7 @@ public function saveData(): void
             'Content-Type: application/json',
         ]);
 
-        $this->clearTmpData();
+        $this->clearProcessTmpData();
     }
 
     public function getDocumentation(): array

src/Drivers/RemoteDriver.php

@@ -28,7 +28,7 @@ public function saveData(): void
     {
         $this->disk->put($this->prodFilePath, json_encode($this->getTmpData()));
 
-        $this->clearTmpData();
+        $this->clearProcessTmpData();
     }
 
     public function getDocumentation(): array

src/Drivers/StorageDriver.php

@@ -6,9 +6,11 @@
 use Illuminate\Http\Request;
 use Illuminate\Http\Testing\File;
 use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\ParallelTesting;
 use Illuminate\Support\Facades\URL;
 use Illuminate\Support\Str;
 use ReflectionClass;
+use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
 use RonasIT\AutoDoc\Exceptions\DocFileNotExistsException;
 use RonasIT\AutoDoc\Exceptions\EmptyContactEmailException;
 use RonasIT\AutoDoc\Exceptions\EmptyDocFileException;
@@ -18,7 +20,6 @@
 use RonasIT\AutoDoc\Exceptions\SwaggerDriverClassNotFoundException;
 use RonasIT\AutoDoc\Exceptions\UnsupportedDocumentationViewerException;
 use RonasIT\AutoDoc\Exceptions\WrongSecurityConfigException;
-use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
 use RonasIT\AutoDoc\Traits\GetDependenciesTrait;
 use RonasIT\AutoDoc\Validators\SwaggerSpecValidator;
 use Symfony\Component\HttpFoundation\Response;
@@ -75,12 +76,12 @@ public function __construct(Container $container)
 
             $this->security = $this->config['security'];
 
-            $this->data = $this->driver->getTmpData();
+            $this->data = $this->driver->getProcessTmpData();
 
             if (empty($this->data)) {
                 $this->data = $this->generateEmptyData();
 
-                $this->driver->saveTmpData($this->data);
+                $this->driver->saveProcessTmpData($this->data);
             }
         }
     }
@@ -188,7 +189,7 @@ public function addData(Request $request, $response)
         $this->parseRequest();
         $this->parseResponse($response);
 
-        $this->driver->saveTmpData($this->data);
+        $this->driver->saveProcessTmpData($this->data);
     }
 
     protected function prepareItem()
@@ -799,6 +800,18 @@ protected function saveTempData()
 
     public function saveProductionData()
     {
+        if (ParallelTesting::token()) {
+            $this->driver->appendProcessDataToTmpFile(function (array $sharedTmpData) {
+                $resultDocContent = (empty($sharedTmpData))
+                    ? $this->generateEmptyData()
+                    : $sharedTmpData;
+
+                $this->mergeOpenAPIDocs($resultDocContent, $this->data);
+
+                return $resultDocContent;
+            });
+        }
+
         $this->driver->saveData();
     }
 
@@ -875,6 +888,8 @@ protected function getClassAnnotations($class): array
 
         $annotations = $reflection->getDocComment();
 
+        $annotations = Str::of($annotations)->remove("\r");
+
         $blocks = explode("\n", $annotations);
 
         $result = [];