Reference Extension Laravel Package

Getting Started

This package is a scaffold, not a library. Treat it as a template you copy once per extension you build, then own the resulting code. Installing it as a runtime dependency (composer require acmecorp/reference-extension) gives you nothing — there is no service to call from your app code.

Minimal path to a first working extension:

1. Clone, don't require. git clone https://github.com/bolt/reference-extension my-extension && cd my-extension && rm -rf .git composer.lock vendor.
2. Read composer.json first. It carries the three things Bolt actually keys off: "type": "bolt-extension", the PSR-4 autoload mapping (Acme\ReferenceExtension\ → src/), and the require block pinning bolt/core / PHP versions. Rename the package (acmecorp/reference-extension → yourorg/your-extension) and the namespace here and everywhere under src/.
3. Read the entry class in src/. It extends Bolt's base Extension class and is where services, routes, Twig functions, and event subscribers are wired. This one file is 80% of what the template is teaching.
4. Read config/ and templates/ next. The config file plus its schema shows how extension config gets merged with site config; the templates show the Twig namespace registration pattern.
5. Wire it into a host site with a path repository so you get live editing without tagging releases:

"repositories": [{ "type": "path", "url": "../my-extension", "options": { "symlink": true } }]

then composer require yourorg/your-extension:@dev and clear cache.

First use case to validate the scaffold: make the extension expose one Twig function (e.g. {{ my_greeting('world') }}) and one backend route. If both work, discovery, autoloading, DI, and config are all correct — everything else is additive.

Implementation Patterns

Fork-per-extension, not shared base. The healthy pattern is one copy of this repo per extension, with divergent src/ code. Resist the urge to abstract a shared parent package until you have three extensions with genuinely identical needs; the coupling cost with a 5-star, zero-dependent template is not worth it.

Service registration over fat classes. Keep the extension class thin: register services in the container, and put logic in plain injectable classes under src/. This is the single biggest maintainability lever, and it makes the code testable outside of Bolt's kernel.

Event subscribers for cross-cutting behaviour. Rather than editing templates or core, subscribe to the events the template already demonstrates (request/kernel, storage, backend menu). Each subscriber is a small class; the extension class just lists them. This keeps upgrade pain localized.

Twig extensions as the public surface. For most day-to-day work — exposing data to templates, formatting helpers, small queries — a Twig function/filter is what you ship. Register it once in the extension class, keep the implementation in a service, and template authors get a stable API.

Config with a schema, always. Define extension config in config/ with a schema file rather than reading ad-hoc values. It documents the knobs, gives validation errors instead of silent nulls, and means site owners can override without touching your code.

Path repository during development, VCS repository for staging. Symlink locally for instant feedback; only tag a release when the extension stabilizes. Because this template ships no versioning contract, pin your own tags and use @dev explicitly rather than relying on implicit constraints.

Frontend assets: build, don't commit node_modules. The template's asset pipeline expects a build step. Commit the built output only if the host site's deploy can't run the build; otherwise document the build command in your README, because nobody will guess it.

Testing harness is the real value. Port the PHPUnit/PHPStan/ECS configs into your fork and keep them green. With no dependents and no external users, your own CI is the only thing catching regressions.

Gotchas and Tips

• Version skew is the top failure mode. A starter template pins bolt/core at whatever version was current when it was generated. Check composer.json against the Bolt version on the host site before copying code, and expect the extension-class API (service registration signature, event names, base class location) to have moved between major versions. Diff the template's src/ against the docs for your installed version rather than trusting it.
• The package name lies. Whatever name is on Packagist, the code inside expects its own namespace. If you skip the namespace rename, autoloading silently fails and Bolt reports "extension not found" with no hint about the cause. Do the rename in composer.json, all of src/, and templates/ in one pass, then composer dump-autoload.
• Discovery requires a cache clear. New or renamed extensions, changed config, and new Twig namespaces frequently don't appear until you clear Bolt's cache. Make cache:clear your reflex before debugging anything.
• Symlinked path repos and asset paths. Symlinks plus a webroot-relative asset path produce 404s that look like routing bugs. If assets vanish, check the resolved real path first.
• Config merges are shallow in places. Nested arrays can be replaced wholesale rather than deep-merged depending on the loader. If a site-level override is silently dropping sibling keys, that's why — flatten your config or read defaults defensively.
• Don't leave the template's identity in place. Leftover acmecorp strings in composer.json, the extension's display name, translations, or the README are the most common review finding on scaffolds. Grep for the original vendor and extension name before your first commit.
• No support contract. Five stars, zero dependents, and a recent release date means one maintainer's side project. Read the whole src/ before depending on it (it's small enough to read), vendor-copy rather than require it, and don't file issues expecting SLA responses. MIT license means forking is the sanctioned escape hatch — take it early rather than working around template limitations.
• Extension points worth knowing exist: custom field types, storage entities/repositories, backend menu entries, console commands, and migrations. The template likely stubs only two or three; the rest are documented in Bolt's extension docs and are where most real day-to-day work lands.