Plugin manifest and capabilities

2026-06-01 23:16:17

Declaring requirements, hooks, and permissions.

Manifest contract

Struxa validates plugin.json before activation and shows a compatibility report in Extensions → Plugins.

Key fields

Field	Purpose
`requires_cms_version`	Minimum Struxa semver
`requires_php`	Minimum PHP version
`requires_plugins`	Other plugins must be installed and active
`conflicts`	Slugs that cannot be active simultaneously
`capabilities`	Declared APIs used at boot
`hooks.filters` / `hooks.events`	Filters and events registered in boot
`database.tables`	Tables owned (documentation + preflight)
`load.public/admin/cli`	Skip boot on unused contexts

Capabilities

database.read / database.write — PDO access
filesystem.write — Plugin storage path
admin.nav — Admin routes and menu items
frontend.render — Public routes and reserved slugs
user.read — Auth service access
settings.write — Persist plugin settings
media.upload — Media integration

Example manifest

{
  "name": "My Plugin",
  "slug": "my-plugin",
  "version": "1.0.0",
  "requires_cms_version": "1.1.33",
  "requires_php": "8.2",
  "capabilities": ["database.write", "admin.nav", "frontend.render"],
  "hooks": {
    "filters": ["seo.meta", "menu.items"],
    "events": ["ContentEntrySavedEvent"]
  },
  "database": {
    "migrations": "migrations",
    "tables": ["cms_my_plugin_items"]
  }
}

Legacy permissive mode

Plugins with no capabilities and no declared hooks run in legacy permissive mode (full boot API), but filters must still use valid FilterHook constants.

Activation checks

Errors block activation; warnings (untested CMS version, destructive migrations) display but may not block.