Add an api_version field to plugin.json

[lancepioch]

Part of the plugin API contract work.

Plugins can declare which plugin api version they target so the panel can refuse to load plugins written against a future incompatible api instead of failing unpredictably. The field is optional and defaults to 1. Plugins declaring a higher version than the panel supports are marked incompatible before loading using the same status flow as the panel_version check, plugins missing the field get a warning note under their status badge on the plugins page, and p:plugin:make scaffolds the field.

Screenshot

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 1831815b-b3c9-4cbb-82b8-b0470cc69b8f

📥 Commits

Reviewing files that changed from the base of the PR and between ae4b26e and 41e2c35.

📒 Files selected for processing (3)

• app/Console/Commands/Plugin/MakePluginCommand.php
• app/Models/Plugin.php
• app/Services/Helpers/PluginService.php

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The panel now reads plugin API versions from plugin.json, defaults missing values to version 1, and evaluates compatibility. Generated plugins include the supported API version, and the admin interface warns when the field is missing.

Changes

Plugin API compatibility

Layer / File(s)	Summary
API version contract and validation app/Models/Plugin.php, tests/Unit/Models/PluginApiVersionTest.php	Plugin defines supported API version 1, reads api_version, defaults missing values to 1, and evaluates compatibility. Tests cover supported, missing, and newer versions.
Generated plugin metadata app/Console/Commands/Plugin/MakePluginCommand.php	The command uses SoftwareVersionService for the panel version prompt and writes api_version set to Plugin::SUPPORTED_API_VERSION into generated plugin.json files.
Plugin loading and admin status app/Services/Helpers/PluginService.php, app/Filament/Admin/Resources/Plugins/PluginResource.php, lang/en/admin/plugin.php	Plugin API compatibility filtering remains in place. Panel-version messages identify compatible newer versions, and the admin status display warns when api_version is missing.

Sequence Diagram(s)

sequenceDiagram
  participant MakePluginCommand
  participant Plugin
  participant PluginService
  participant PluginResource
  MakePluginCommand->>Plugin: read SUPPORTED_API_VERSION
  MakePluginCommand-->>PluginService: write api_version to plugin.json
  PluginService->>Plugin: evaluate isApiVersionSupported()
  Plugin-->>PluginService: return compatibility status
  PluginService-->>PluginResource: provide plugin status
  PluginResource-->>PluginResource: display missing-version warning

Loading

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 41e2c

The API-version compatibility flow has no confirmed merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: adding an api_version field to plugin.json.
Description check	✅ Passed	The description directly explains the api_version behavior, compatibility checks, missing-field warning, and scaffolding changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Boy132]

Why do we need both a panel_version and a api_version? A specific panel version contraint also implies a specific api version constraint.

[lancepioch]

Why do we need both a panel_version and a api_version? A specific panel version contraint also implies a specific api version constraint.

panel_version only works in one direction. It can say "this plugin needs panel 1.6 or newer". It cannot say "this plugin stops working after panel X", because the plugin author does not know which future panel version will break the plugin API.

Example: a plugin says panel_version: ^1.2. Later, panel 1.9 changes the plugin API in a breaking way. The old check still passes (1.9 is newer than 1.2), so the panel loads the plugin and it crashes. With api_version, the panel sees the plugin was built for API 1, knows it now uses API 2, and can refuse to load it with a clear message instead.

Also, panel versions change all the time (features, bug fixes). The API version only changes when the plugin API actually breaks. Paper/Bukkit does the same thing: plugins declare api-version separately from the server version.