Report a missing plugin without PluginNotFoundException on Matomo before 5.7.0

Annotations/AnnotationGenerator.php

@@ -15,7 +15,6 @@
 use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlock\Tags\Param;
 use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
 use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlockFactory;
-use Piwik\Exception\PluginNotFoundException;
 use Piwik\API\DocumentationGenerator;
 use Piwik\API\NoDefaultValue;
 use Piwik\API\Proxy;
@@ -148,7 +147,7 @@ public function __construct(
      *
      * @return string[]|array[] The collection of all the lines which make up the generated annotations for the public API
      * endpoints defined by the plugin.
-     * @throws PluginNotFoundException If the plugin is not present in the filesystem.
+     * @throws \Exception If the plugin is not present in the filesystem.
      * @throws \Throwable
      */
     public function generatePluginApiAnnotations(string $pluginName, bool $writeToFile = false): array
@@ -160,7 +159,7 @@ public function generatePluginApiAnnotations(string $pluginName, bool $writeToFi
         }
 
         if (!Manager::getInstance()->isPluginInFilesystem($pluginName)) {
-            throw new PluginNotFoundException($pluginName);
+            ApiReference::throwPluginNotFound($pluginName);
         }
 
         // Posted so that existing subscribers keep being called for the rest of the 5.x cycle. The result is

Annotations/ApiMethodInfoExtractor.php

@@ -11,10 +11,10 @@
 
 namespace Piwik\Plugins\ApiReference\Annotations;
 
-use Piwik\Exception\PluginNotFoundException;
 use Piwik\API\Proxy;
 use Piwik\API\Request;
 use Piwik\Plugin\Manager;
+use Piwik\Plugins\ApiReference\ApiReference;
 use Piwik\Plugins\ApiReference\Artifact\ArtifactWriter;
 use Piwik\Plugins\ApiReference\Specs\PathResolver;
 use Piwik\Validators\BaseValidator;
@@ -59,7 +59,7 @@ public function extractMethodInfo(string $pluginName, bool $writeToFile = false)
         foreach ($pluginNames as $plugin) {
             BaseValidator::check('pluginName', $plugin, [new NotEmpty()]);
             if (!Manager::getInstance()->isPluginInFilesystem($plugin)) {
-                throw new PluginNotFoundException($plugin);
+                ApiReference::throwPluginNotFound($plugin);
             }
 
             $className = Request::getClassNameAPI($plugin);

ApiReference.php

@@ -9,6 +9,8 @@
 
 namespace Piwik\Plugins\ApiReference;
 
+use Piwik\Exception\PluginNotFoundException;
+
 class ApiReference extends \Piwik\Plugin
 {
     public const DEFAULT_SPEC_VERSION = '1.0.0';
@@ -61,4 +63,17 @@ public function uninstall()
         $config = new Configuration();
         $config->uninstall();
     }
+
+    /**
+     * @throws \Exception
+     */
+    public static function throwPluginNotFound(string $pluginName): void
+    {
+        // PluginNotFoundException only exists from Matomo 5.7.0.
+        if (class_exists(PluginNotFoundException::class)) {
+            throw new PluginNotFoundException($pluginName);
+        }
+
+        throw new \Exception("The plugin $pluginName was not found.", 404);
+    }
 }

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Changelog
 
+5.0.10
+- Fixed generating the API spec or annotations for a plugin that is not installed failing with a missing class error, rather than reporting the plugin as not found, on Matomo versions before 5.7.0
+
 5.0.9 - 2026-10-19
 - Fixed the plugin cards on the API Reference page picking up the Marketplace's card style, and the API method panels staying light in dark mode
 

Specs/SpecGenerator.php

@@ -12,7 +12,6 @@
 use Matomo\Dependencies\ApiReference\OpenApi\Annotations\OpenApi;
 use Matomo\Dependencies\ApiReference\OpenApi\Generator;
 use Piwik\Container\StaticContainer;
-use Piwik\Exception\PluginNotFoundException;
 use Piwik\Log\LoggerInterface;
 use Piwik\Log\NullLogger;
 use Piwik\Plugin\Manager;
@@ -67,7 +66,7 @@ public function generatePluginDoc(string $pluginName, string $format = 'json', s
      * @return string
      * @throws \Piwik\Exception\DI\DependencyException
      * @throws \Piwik\Exception\DI\NotFoundException
-     * @throws PluginNotFoundException
+     * @throws \Exception
      * @throws \Exception
      */
     public function generateSpec(array $pluginNames, string $format = 'json', string $version = ApiReference::DEFAULT_SPEC_VERSION, bool $writeToFile = false): string
@@ -90,7 +89,7 @@ public function generateSpec(array $pluginNames, string $format = 'json', string
         foreach ($pluginNames as $pluginName) {
             BaseValidator::check('pluginName', $pluginName, [new NotEmpty()]);
             if (!Manager::getInstance()->isPluginInFilesystem($pluginName)) {
-                throw new PluginNotFoundException($pluginName);
+                ApiReference::throwPluginNotFound($pluginName);
             }
 
             $pluginAnnotationsSource = $this->specPathResolver->getAnnotationFilePath($pluginName);

plugin.json

@@ -1,7 +1,7 @@
 {
     "name": "ApiReference",
     "description": "Modern interactive API documentation for Matomo based on OpenAPI (Swagger). Explore endpoints, parameters, and responses directly in your browser. ",
-    "version": "5.0.9",
+    "version": "5.0.10",
     "theme": false,
     "keywords": [
         "API",

tests/Unit/ApiReferenceTest.php

@@ -0,0 +1,32 @@
+<?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\ApiReference\tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\ApiReference\ApiReference;
+
+/**
+ * @group ApiReference
+ * @group ApiReference_Unit
+ * @group ApiReference_ApiReferenceTest
+ */
+class ApiReferenceTest extends TestCase
+{
+    public function testThrowPluginNotFoundReportsTheMissingPluginAsNotFound(): void
+    {
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('The plugin NotARealPlugin was not found.');
+        $this->expectExceptionCode(404);
+
+        ApiReference::throwPluginNotFound('NotARealPlugin');
+    }
+}