Plugin skeleton

About 377 wordsAbout 1 min

Skeleton for a Spora plugin.

Use this repository as a template for any new spora-plugin:

  1. Click Use this template → Create a new repository on GitHub.
  2. Rename the package in composer.json (e.g. spora-ai/spora-plugin-tavily).
  3. Rename the namespace (Spora\Plugins\Skeleton → Spora\Plugins\<YourPlugin>) in every PHP file.
  4. Update plugin.json’s slug, description, class, and icon.
  5. Replace src/Tools/EchoTool.php with your real tool(s); add more files under src/Tools/ and list them in src/Plugin.php::tools().
  6. If your plugin needs database tables, add Laravel migrations under database/migrations/ and bump SkeletonPlugin::schemaVersion().

Note on the skeleton’s src/Plugin.php: the class is named SkeletonPlugin (not Plugin), which is a violation of the PSR-4 file-must-match-FQCN rule the rest of the docs follow. The skeleton is the historical exception; the PluginLoader resolves the class via the class field in plugin.json, not via the file name. For any new plugin, name the file to match the FQCN — src/AcmeSearchPlugin.php for Spora\Plugins\AcmeSearch\AcmeSearchPlugin.

Layout

.
├── composer.json          # name=spora-ai/spora-plugin-<x>, type=spora-plugin
├── plugin.json            # manifest the PluginLoader reads at boot
├── src/
│   ├── Plugin.php         # PluginInterface implementation
│   └── Tools/
│       └── EchoTool.php   # one tool per file (replace this one)
├── tests/                 # Pest unit tests
│   ├── Pest.php
│   └── Unit/
└── .github/workflows/
    └── ci.yml             # pest + phpstan + cs-fixer

Local development

Clone the repo, install dependencies, and run the tests:

composer install
./vendor/bin/pest

Publishing

  1. Tag the release: git tag v0.1.0 && git push --tags.
  2. (Optional) Configure Packagist to auto-pull from the GitHub repo.

There’s nothing to bump in plugin.json or composer.json — the runtime reads the version from the git tag via Composer\InstalledVersions::getPrettyVersion(), so the tag is the single source of truth.

CI

Three parallel jobs run on every push to main, on v* tags, and on pull requests:

  • test — Pest on PHP 8.4 + 8.5
  • static-analysis — PHPStan level 5
  • code-style — php-cs-fixer dry-run (same ruleset as Spora core)

External actions are pinned to full commit SHAs per the project’s supply-chain policy.

Repo: spora-ai/spora-plugin-skeleton · MIT