Build an Extension

Before you scaffold

Start with a working local developer installation and a feature small enough to test in isolation. Read the checkout’s docs/extensions/README.md, STRUCTURE.md, CODING-STANDARD.md, and the relevant extension-point catalog. The deployed project uses a capability-based extension system; a general Laravel package tutorial is not a replacement for this contract.

Create a starter extension

php artisan wento:make-app acme/hello-banner --title="Hello banner"

Run this from the project root. It creates extensions/acme/hello-banner/. Use your own vendor/name identifiers for a real package. Review the generated manifest and entry class before changing anything.

extensions/acme/hello-banner/
├── app.json
├── README.md
├── preview.svg
├── src/
│   └── Plugin.php
└── assets/

The actual generated/required files depend on the scaffold. app.json, README.md, and src/Plugin.php are required by the documented structure; preview artwork and approved frontend assets are optional/recommended as described in the handbook.

Understand the entry point and capabilities

namespace Modules\Acme\HelloBanner;

use App\Domain\Plugin\Support\BasePlugin;

class Plugin extends BasePlugin
{
    public function boot(): void
    {
        // Register only published extension points here.
    }
}

The namespace derives from the vendor/name. Declare every needed capability in app.json and use the BasePlugin helpers approved for it. A settings screen, an admin menu, a hosted page, a list column, and a storefront slot are different extension points; choose the one that matches the task.

The core validates capabilities and renders/dispatches hosted extension surfaces. Do not copy undocumented internal hook identifiers, create arbitrary routes/interceptors, or use unrestricted DB calls in a Safe extension. Undeclared or forbidden behavior can fail validation or leave the extension unhealthy.

Keep the package structure valid

• Keep the boot class in src/Plugin.php; use the approved namespace and file layout.
• Use approved one-level Http/*Controller.php files or pure Support helpers only where the contract permits them.
• Keep frontend assets under assets/ and declare them correctly.
• Do not include vendor, node_modules, tests, .env, private keys, arbitrary PHP at package root, or unrelated folders.
• Document requirements, capabilities, setup, licensing, and support in README.md.

Package and install on staging

php artisan wento:app-pack acme/hello-banner

The documented output is plugin-packs/acme-hello-banner.zip. Inspect its file list before upload. In the installed admin, use Design → Extensions/Apps, upload the ZIP, review requested capabilities, install, then enable as the interface requires. Labels may vary, but installation and enablement are distinct lifecycle states.

Test the feature with both authorized and unauthorized roles and, where relevant, the intended shop context. Check missing configuration, invalid input, and disabled-extension behavior—not just the happy path.

Upgrade and uninstall deliberately

Increment package version for a real release and test the supported upgrade path with existing settings. A reset/uninstall can clear settings or stored data; it is not a harmless refresh. Review lifecycle effects before recommending it to a merchant.

Use the release’s published SDK/write APIs for catalog, customer, cart, or order changes. Core validation must remain authoritative. Additive schema/data changes need a documented migration/upgrade plan and tests on a backed-up staging store.

Continue learning

Local Development Setup · Customize the Storefront · Upgrade Preparation