Updated OpenApiDocs to use Cloud shared storage if available, #PG-4593 (#27)

* Moved API documentation from hard coded paths to a resolver service, if on Cloud, it will use CloudDistributedCachePath, else, it will use /tmp in the plugin

* simplified code now, using generic file writing service

* Adding better tests for path resolving

* Added cloud pr suggestion, check if path exists and is writable

* fix tests

Author: lachiebol

API.php

@@ -12,6 +12,7 @@
 use Piwik\Piwik;
 use Piwik\Plugin\Manager;
 use Piwik\Plugins\OpenApiDocs\Specs\SpecGenerator;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 
 /**
  * API for plugin OpenApiDocs
@@ -67,9 +68,7 @@ public function getOpenApiSpec(string $pluginName, string $format = 'json'): arr
 
     protected function getSpecFilePath(string $pluginName): string
     {
-        $currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
-
-        return $currentPluginDir . OpenApiDocs::GENERATED_SPECS_PATH . $pluginName . '_openapi_spec_v' . OpenApiDocs::DEFAULT_SPEC_VERSION . '.json';
+        return $this->getSpecPathResolver()->getSpecFilePath($pluginName);
     }
 
     protected function isSpecFileReadable(string $filePath): bool
@@ -98,6 +97,11 @@ protected function validateJsonFormat(string $format): void
         }
     }
 
+    protected function getSpecPathResolver(): PathResolver
+    {
+        return new PathResolver();
+    }
+
     /**
      * Get the generated API documentation data for the specified plugin.
      *

Annotations/AnnotationGenerator.php

@@ -23,7 +23,9 @@
 use Piwik\Http;
 use Piwik\Piwik;
 use Piwik\Plugin\Manager;
+use Piwik\Plugins\OpenApiDocs\Artifact\ArtifactWriter;
 use Piwik\Plugins\OpenApiDocs\OpenApiDocs;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 use Piwik\SettingsPiwik;
 use Piwik\Url;
 use Piwik\UrlHelper;
@@ -72,6 +74,16 @@ class AnnotationGenerator
      */
     protected $generator;
 
+    /**
+     * @var PathResolver
+     */
+    protected $pathResolver;
+
+    /**
+     * @var ArtifactWriter
+     */
+    protected $artifactWriter;
+
     /**
      * @var array[]
      */
@@ -82,9 +94,14 @@ class AnnotationGenerator
      */
     protected $missingImportantDataWarnings;
 
-    public function __construct(DocumentationGenerator $generator)
-    {
+    public function __construct(
+        DocumentationGenerator $generator,
+        ?PathResolver $pathResolver = null,
+        ?ArtifactWriter $artifactWriter = null
+    ) {
         $this->generator = $generator;
+        $this->pathResolver = $pathResolver ?? new PathResolver();
+        $this->artifactWriter = $artifactWriter ?? new ArtifactWriter();
         $this->missingImportantDataWarnings = [];
         $this->currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
     }
@@ -115,8 +132,7 @@ public function generatePluginApiAnnotations(string $pluginName, bool $writeToFi
         }
 
         $rules = require $this->currentPluginDir . '/Annotations/config.php';
-        $pluginAnnotationDir = $this->currentPluginDir . OpenApiDocs::GENERATED_ANNOTATIONS_PATH;
-        $pluginAnnotationPath = $pluginAnnotationDir . "/{$pluginName}GeneratedAnnotations.php";
+        $pluginAnnotationPath = $this->pathResolver->getAnnotationFilePath($pluginName);
 
         $className = Request::getClassNameAPI($pluginName);
 
@@ -231,8 +247,7 @@ public function getContentForGeneratedAnnotationsFile(array $annotations, string
      */
     protected function writeAnnotationsToFile(array $annotations, string $filePath, string $pluginName)
     {
-        // Create or overwrite the annotations file
-        return file_put_contents($filePath, $this->getContentForGeneratedAnnotationsFile($annotations, $pluginName));
+        return $this->writeFile($filePath, $this->getContentForGeneratedAnnotationsFile($annotations, $pluginName));
     }
 
     /**
@@ -903,11 +918,11 @@ protected function getExampleIfAvailable(string $url, bool $useLocalToken = fals
         }
         $method = $queryParams['method'];
         $format = strtolower($queryParams['format']);
-        $exampleFilePath = $this->currentPluginDir . OpenApiDocs::EXAMPLE_RESPONSES_PATH . $method . '.' . $format;
+        [$pluginName, $methodName] = explode('.', $method);
+        $exampleFilePath = $this->pathResolver->getExampleResponseFilePath($pluginName, $methodName, $format);
         // If there's already a file, use that instead of making a new server call. Ignore the file when the flag is set.
         if (!$ignoreCached) {
             // If an example file is found, return its contents instead of making the server call.
-            [$pluginName, $methodName] = explode('.', $method);
             $exampleContents = $this->getCachedExampleResponseFile($pluginName, $methodName, $format);
             if (!empty($exampleContents)) {
                 return $exampleContents;
@@ -962,7 +977,7 @@ protected function getExampleIfAvailable(string $url, bool $useLocalToken = fals
         $body = $response['data'];
 
         // Write the example response to file as a cache and reference.
-        file_put_contents($exampleFilePath, $body);
+        $this->writeFile($exampleFilePath, $body);
 
         // Convert the XML responses into a JSON object and then encode it into a string. This is helpful for building schemas.
         if ($format === 'xml') {
@@ -994,7 +1009,7 @@ protected function getExampleIfAvailable(string $url, bool $useLocalToken = fals
      */
     protected function getCachedExampleResponseFile(string $pluginName, string $methodName, string $format, bool $rawResult = false, bool $applyMaxLength = true): string
     {
-        $exampleFilePath = $this->currentPluginDir . OpenApiDocs::EXAMPLE_RESPONSES_PATH . $pluginName . '.' . $methodName . '.' . $format;
+        $exampleFilePath = $this->pathResolver->getExampleResponseFilePath($pluginName, $methodName, $format);
         // Simply return an empty string if the file doesn't exist yet.
         if (!file_exists($exampleFilePath)) {
             return '';
@@ -1021,6 +1036,11 @@ protected function getCachedExampleResponseFile(string $pluginName, string $meth
         return $exampleContents;
     }
 
+    protected function writeFile(string $filePath, string $contents)
+    {
+        return $this->artifactWriter->writeFile($filePath, $contents);
+    }
+
     /**
      * Try to build an example URL for a specific API method using report metadata. This queries the demo server for
      * report metadata to get examples of existing reports which can be used as example URLS. If no metadata matches the

Annotations/ApiMethodInfoExtractor.php

@@ -15,12 +15,29 @@
 use Piwik\API\Proxy;
 use Piwik\API\Request;
 use Piwik\Plugin\Manager;
-use Piwik\Plugins\OpenApiDocs\OpenApiDocs;
+use Piwik\Plugins\OpenApiDocs\Artifact\ArtifactWriter;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 use Piwik\Validators\BaseValidator;
 use Piwik\Validators\NotEmpty;
 
 class ApiMethodInfoExtractor
 {
+    /**
+     * @var PathResolver
+     */
+    private $pathResolver;
+
+    /**
+     * @var ArtifactWriter
+     */
+    private $artifactWriter;
+
+    public function __construct(?PathResolver $pathResolver = null, ?ArtifactWriter $artifactWriter = null)
+    {
+        $this->pathResolver = $pathResolver ?? new PathResolver();
+        $this->artifactWriter = $artifactWriter ?? new ArtifactWriter();
+    }
+
     /**
      * Look up the Matomo Reporting API methods for the specified plugin(s) and output the basic information for each.
      * This includes the comment block, parameter information, and things like that. This can then be fed to a secure
@@ -38,8 +55,6 @@ public function extractMethodInfo(string $pluginName, bool $writeToFile = false)
         $pluginNames = explode(',', $pluginName);
 
         BaseValidator::check('pluginNames', $pluginNames, [new NotEmpty()]);
-        $currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
-
         $methodInfoArray = [];
         foreach ($pluginNames as $plugin) {
             BaseValidator::check('pluginName', $plugin, [new NotEmpty()]);
@@ -63,8 +78,8 @@ public function extractMethodInfo(string $pluginName, bool $writeToFile = false)
         }
 
         if ($writeToFile) {
-            $pluginSpecPath = $currentPluginDir . OpenApiDocs::GENERATED_ANNOTATIONS_PATH . $fileBaseName . '_api_method_info.json';
-            file_put_contents($pluginSpecPath, $methodInfoString);
+            $pluginSpecPath = $this->pathResolver->getApiMethodInfoFilePath($fileBaseName);
+            $this->artifactWriter->writeFile($pluginSpecPath, $methodInfoString);
         }
 
         return $methodInfoString;

Artifact/ArtifactWriter.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\OpenApiDocs\Artifact;
+
+use Piwik\Filesystem;
+
+class ArtifactWriter
+{
+    /**
+     * @return false|int
+     */
+    public function writeFile(string $filePath, string $contents)
+    {
+        Filesystem::mkdir(dirname($filePath));
+
+        return file_put_contents($filePath, $contents);
+    }
+}

Commands/ExtractReportingApiMethodInfo.php

@@ -11,8 +11,10 @@
 
 namespace Piwik\Plugins\OpenApiDocs\Commands;
 
+use Piwik\Container\StaticContainer;
 use Piwik\Plugin\ConsoleCommand;
 use Piwik\Plugins\OpenApiDocs\Annotations\ApiMethodInfoExtractor;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 
 /**
  * This class lets you define a new command. To read more about commands have a look at our Matomo Console guide on
@@ -86,7 +88,7 @@ protected function doExecute(): int
         $result = (new ApiMethodInfoExtractor())->extractMethodInfo($plugin, $notDryRun);
 
         if ($notDryRun) {
-            $output->writeln('<info>Results written to plugins/OpenApiDocs/tmp/annotations directory.</info>');
+            $output->writeln('<info>Results written to ' . StaticContainer::get(PathResolver::class)->getAnnotationsDirectory() . '</info>');
 
             return $result ? self::SUCCESS : self::FAILURE;
         }

Commands/GenerateAnnotations.php

@@ -12,6 +12,7 @@
 use Piwik\Container\StaticContainer;
 use Piwik\Plugin\ConsoleCommand;
 use Piwik\Plugins\OpenApiDocs\Annotations\AnnotationGenerator;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 
 /**
  * This class lets you define a new command. To read more about commands have a look at our Matomo Console guide on
@@ -83,7 +84,7 @@ protected function doExecute(): int
         $result = (StaticContainer::get(AnnotationGenerator::class))->generatePluginApiAnnotations($plugin, $notDryRun);
 
         if ($notDryRun) {
-            $output->writeln('<info>Results written to plugins/OpenApiDocs/tmp/annotations/ directory.</info>');
+            $output->writeln('<info>Results written to ' . StaticContainer::get(PathResolver::class)->getAnnotationsDirectory() . '</info>');
 
             return $result ? self::SUCCESS : self::FAILURE;
         }

Commands/GenerateSpecFile.php

@@ -13,6 +13,7 @@
 use Piwik\Plugin\ConsoleCommand;
 use Piwik\Plugins\OpenApiDocs\Generation\SpecGenerationService;
 use Piwik\Plugins\OpenApiDocs\OpenApiDocs;
+use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
 
 /**
  * This class lets you define a new command. To read more about commands have a look at our Matomo Console guide on
@@ -28,9 +29,15 @@ class GenerateSpecFile extends ConsoleCommand
      */
     private $specGenerationService;
 
-    public function __construct(?SpecGenerationService $specGenerationService = null)
+    /**
+     * @var PathResolver
+     */
+    private $specPathResolver;
+
+    public function __construct(?SpecGenerationService $specGenerationService = null, ?PathResolver $specPathResolver = null)
     {
         $this->specGenerationService = $specGenerationService ?: StaticContainer::get(SpecGenerationService::class);
+        $this->specPathResolver = $specPathResolver ?: StaticContainer::get(PathResolver::class);
 
         parent::__construct();
     }
@@ -116,12 +123,12 @@ protected function doExecute(): int
 
         if ($addAnnotations) {
             foreach ($pluginNames as $pluginName) {
-                $output->writeln('<info>Created Annotations for ' . $pluginName . ' and wrote results to plugins/OpenApiDocs/tmp/annotations.</info>');
+                $output->writeln('<info>Created Annotations for ' . $pluginName . ' and wrote results to ' . $this->specPathResolver->getAnnotationsDirectory() . '</info>');
             }
         }
 
         if ($notDryRun) {
-            $output->writeln('<info>Results written to plugins/OpenApiDocs/tmp/specs/ directory.</info>');
+            $output->writeln('<info>Results written to ' . $this->specPathResolver->getSpecDirectory() . '</info>');
             return self::SUCCESS;
         }