Add an api_version field to plugin.json

app/Console/Commands/Plugin/MakePluginCommand.php

@@ -4,6 +4,7 @@
 
 use App\Enums\PluginCategory;
 use App\Enums\PluginStatus;
+use App\Models\Plugin;
 use App\Services\Helpers\SoftwareVersionService;
 use Illuminate\Console\Command;
 use Illuminate\Filesystem\Filesystem;
@@ -112,6 +113,7 @@ public function handle(SoftwareVersionService $versionService): void
             'class' => $class,
             'panels' => $panels,
             'panel_version' => $panelVersion,
+            'api_version' => Plugin::SUPPORTED_API_VERSION,
             'composer_packages' => $composerPackages,
             'meta' => [
                 'status' => PluginStatus::Enabled,

app/Filament/Admin/Resources/Plugins/PluginResource.php

@@ -83,6 +83,7 @@ public static function table(Table $table): Table
                     ->label(trans('admin/plugin.status'))
                     ->badge()
                     ->tooltip(fn (Plugin $plugin) => $plugin->status_message)
+                    ->description(fn (Plugin $plugin) => is_null($plugin->api_version) ? trans('admin/plugin.api_version_missing') : null)
                     ->sortable(),
             ])
             ->recordActions([

app/Models/Plugin.php

@@ -32,6 +32,7 @@
  * @property string $class
  * @property string|null $panels
  * @property string|null $panel_version
+ * @property int|null $api_version
  * @property string|null $composer_packages
  * @property PluginStatus $status
  * @property string|null $status_message
@@ -63,6 +64,9 @@ class Plugin extends Model implements HasPluginSettings
 
     public const RESOURCE_NAME = 'plugin';
 
+    /** The highest plugin.json api_version this panel supports. */
+    public const SUPPORTED_API_VERSION = 1;
+
     protected $primaryKey = 'id';
 
     protected $keyType = 'string';
@@ -91,6 +95,7 @@ public function getSchema(): array
             'class' => 'string',
             'panels' => 'string',
             'panel_version' => 'string',
+            'api_version' => 'integer',
             'composer_packages' => 'string',
             'status' => 'string',
             'status_message' => 'string',
@@ -112,6 +117,7 @@ public function getSchema(): array
      *     class: string,
      *     panels: ?string,
      *     panel_version: ?string,
+     *     api_version: ?int,
      *     composer_packages: ?string,
      *     status: string,
      *     status_message: ?string,
@@ -162,6 +168,7 @@ public function getRows(): array
                     'class' => $data['class'],
                     'panels' => $panels,
                     'panel_version' => Arr::get($data, 'panel_version', null),
+                    'api_version' => Arr::get($data, 'api_version', null),
                     'composer_packages' => $composerPackages,
 
                     'status' => Str::lower(Arr::get($data, 'meta.status', PluginStatus::NotInstalled->value)),
@@ -189,6 +196,7 @@ public function getRows(): array
                         'class' => 'Error',
                         'panels' => null,
                         'panel_version' => null,
+                        'api_version' => null,
                         'composer_packages' => null,
 
                         'status' => PluginStatus::Errored->value,
@@ -257,6 +265,16 @@ public function isCompatible(): bool
         return version_compare($currentPanelVersion, $minimum, '>=') && version_compare($currentPanelVersion, $upper, '<');
     }
 
+    public function effectiveApiVersion(): int
+    {
+        return $this->api_version ?? 1;
+    }
+
+    public function isApiVersionSupported(): bool
+    {
+        return $this->effectiveApiVersion() <= self::SUPPORTED_API_VERSION;
+    }
+
     public function isPanelVersionStrict(): bool
     {
         if (!$this->panel_version) {

app/Services/Helpers/PluginService.php

@@ -42,6 +42,14 @@ public function loadPlugins(): void
         $plugins = Plugin::orderBy('load_order')->get();
         foreach ($plugins as $plugin) {
             try {
+                // Filter out plugins that require a newer plugin api than this panel supports
+                // (only in production, so plugin developers can work on fixing their plugin locally)
+                if ($this->app->isProduction() && !$plugin->isApiVersionSupported()) {
+                    $this->setStatus($plugin, PluginStatus::Incompatible, 'This Plugin requires plugin api version ' . $plugin->effectiveApiVersion() . ' but this Panel only supports up to version ' . Plugin::SUPPORTED_API_VERSION . '!');
+
+                    continue;
+                }
+
                 // Filter out plugins that are not compatible with the current panel version
                 if (!$plugin->isCompatible()) {
                     $this->setStatus($plugin, PluginStatus::Incompatible, 'This Plugin is only compatible with Panel version ' . $plugin->panel_version . (!$plugin->isPanelVersionStrict() ? ' or a compatible newer version' : '') . ' but you are using version ' . $this->app->make(SoftwareVersionService::class)->currentPanelVersion() . '!');

lang/en/admin/plugin.php

@@ -7,6 +7,7 @@
 
     'name' => 'Name',
     'update_available' => 'An update for this plugin is available',
+    'api_version_missing' => '⚠ plugin.json does not declare an api_version, assuming 1',
     'author' => 'Author',
     'version' => 'Version',
     'category' => 'Category',

tests/Unit/Models/PluginApiVersionTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Tests\Unit\Models;
+
+use App\Models\Plugin;
+use App\Tests\TestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class PluginApiVersionTest extends TestCase
+{
+    #[DataProvider('apiVersionDataProvider')]
+    public function test_api_version_support(?int $apiVersion, int $expectedEffective, bool $expectedSupported): void
+    {
+        $plugin = new Plugin();
+        $plugin->api_version = $apiVersion;
+
+        $this->assertSame($expectedEffective, $plugin->effectiveApiVersion());
+        $this->assertSame($expectedSupported, $plugin->isApiVersionSupported());
+    }
+
+    public static function apiVersionDataProvider(): array
+    {
+        return [
+            'declared supported version' => [Plugin::SUPPORTED_API_VERSION, Plugin::SUPPORTED_API_VERSION, true],
+            'missing defaults to 1' => [null, 1, true],
+            'newer than supported' => [Plugin::SUPPORTED_API_VERSION + 1, Plugin::SUPPORTED_API_VERSION + 1, false],
+        ];
+    }
+}