17 — Extensibility#

Three levels, in increasing order of power and of the trust required to use them:

17.1 Level A — a block folder#

Covered in 04-block-system.md. The contract in one sentence: a folder under app/Blocks/<Name>/ with schema.php, view.blade.php and preview.png becomes a block in the palette, and no admin code changes.

That property is load-bearing and is asserted by a test (block_added_at_runtime_appears_in_palette) which creates a temporary block folder during the test run. If adding a field type is ever needed to express a new block, add the field type to the generated-form system — never special-case the block in the editor.

17.2 Level B — block packs#

A zip with a manifest:

pack.json
blocks/Testimonial/{schema.php,view.blade.php,preview.png,block.css}
blocks/LogoWall/{...}
templates/section-testimonials.json
lang/{bn,en}/blocks-<pack>.php
assets/              (optional images used by templates)

{
  "name": "Marketing Blocks",
  "slug": "marketing-blocks",
  "version": "1.2.0",
  "author": "Example Ltd",
  "requires": { "kodepress": ">=1.0", "php": ">=8.3" },
  "blocks": ["testimonial", "logo_wall"],
  "templates": ["section-testimonials"],
  "checksum": "sha256:..."
}

Import (Settings -> Block packs -> Import) does, in order:

1. Verify the zip structure and the manifest against a schema; reject anything unexpected.
2. Verify the version requirements.
3. Static-check every PHP file: schema.php must be a single return [...] of literals — no function calls, no new, no includes, no superglobals. A schema.php that is anything other than a data literal is rejected.
4. Compile every Blade file and reject any that contains @php, {!! !!} outside an allow-list, or a call to anything outside a small allow-list of helpers (__, kp_media, kp_url, kp_token).
5. Extract into storage/app/block-packs/<slug>/, which is a configured block path.
6. Refresh the block manifest, import the templates, merge the language files.

A block pack cannot register routes, run migrations, or execute code at boot. It is data plus templates. That is what makes it safe to import from the UI. Anything more powerful is a plugin, which is installed over SSH by someone who accepts the risk.

Export produces the same structure from the blocks and templates an Admin selects, including a checksum.

17.3 Level C — plugins (Phase 5)#

plugins/property-listings/
├── plugin.json              manifest
├── src/
│   ├── PropertyListingsServiceProvider.php
│   ├── Models/Property.php
│   ├── Http/Controllers/PropertyController.php
│   ├── Livewire/PropertyManager.php
│   └── Policies/PropertyPolicy.php
├── blocks/PropertyGrid/{schema.php,view.blade.php,preview.png}
├── database/migrations/2026_11_01_000000_create_properties_table.php
├── resources/views/
├── lang/{bn,en}/property.php
└── routes/{web.php,admin.php}

{
  "name": "Property Listings",
  "slug": "property-listings",
  "version": "1.0.0",
  "provider": "KodePress\\PropertyListings\\PropertyListingsServiceProvider",
  "requires": { "kodepress": ">=1.0" },
  "adds": { "blocks": ["property_grid"], "content_types": ["property"], "admin_screens": 2 },
  "permissions": ["property.view", "property.manage"],
  "settings_screen": true
}

Lifecycle#

Disabling must never break a page. The renderer treats an unknown block type as empty output with a logged warning, and the editor shows This block comes from a plugin that is turned off with the option to delete it. This is the single most important plugin rule — a site must not go down because someone toggled a checkbox.

What a plugin may do#

What a plugin may not do#

• Add a top-level sidebar item (the 7-item rule).
• Modify core tables, core migrations, or core files.
• Write to pages, template_parts or menus schema; it may create and read rows through the models.
• Bypass BlockRegistry, HtmlCache or CacheInvalidator — it calls them.
• Register middleware globally, or alter the public request lifecycle outside its own routes.
• Ship its own copy of a dependency that core already provides.

Events a plugin may listen to#

Listeners run synchronously (QUEUE_CONNECTION=sync), so a slow listener slows a publish. The plugin docs state a 200 ms budget per listener and anything heavier must defer its work to the scheduler.

Extension points other than events#

17.4 Multi-site (Phase 5)#

Already prepared for: every content table carries site_id and a global SiteScope is applied from Phase 0.

What Phase 5 adds:

Nothing about multi-site changes the editor. An owner who never adds a second site never sees any of it — the switcher is hidden when only one site exists.

17.5 Upgrade safety for extensions#

• The tree format is versioned and upcast on read (04.10), so a block pack built against format v1 keeps rendering after a v2.
• schema.php keys are additive; an unknown key is ignored, so a pack built for a newer KodePress degrades rather than crashes.
• The plugin API surface is exactly what this document lists. Anything a plugin reaches for beyond it is unsupported and may break on any release, and the plugin docs say so plainly.
• A kodepress:extensions-check command reports, for every installed pack and plugin, whether it declares compatibility with the running version and whether it uses anything outside the API.

KodePress documentation · generated from the Markdown sources by tools/build-docs-site.py · internal preview, not indexed.