Statamic How To Addon Laravel Package

Getting Started

This is a Statamic addon, not a general Laravel package — everything runs inside the Statamic control panel. Treat it as a client-facing documentation surface rather than application logic.

1. Install into a Statamic app (v1.5.0 adds Statamic 4 support):

   composer require jonassiewertsen/statamic-how-to-addon
   

   Statamic 4 implies Laravel 10 / PHP 8.1+. If you're still on Statamic 3, stay on ^1.4 until you've validated v1.5.0.
2. Publish what's publishable. The addon's service provider registers its config/views/assets. Run php artisan vendor:publish and pick the addon's provider, or target the specific tags defined in src/ServiceProvider.php. Read that file first — it tells you the publish tags, view namespace, and any CP nav registration in one place.
3. Clear caches. php artisan cache:clear, php please stache:clear, and php artisan view:clear after install or upgrade. Statamic's Stache and compiled Blade views are the usual cause of "the addon installed but nothing changed".
4. First use case: ship an in-CP handbook for editors — "how to publish a page", "how to resize images", "who to call when the site is down" — so content editors never need to leave the control panel or hunt through a Notion doc.

Where to look first, in order: composer.json (version constraints and extra.statamic discovery block), src/ServiceProvider.php, config/, then resources/.

Implementation Patterns

Documentation as versioned content. Author the how-to entries in the repo and deploy them with the code, rather than typing them into a production CP. That makes docs reviewable in PRs and reproducible across local/staging/production. If the addon stores entries as flat files, commit them; if it stores them in the database, export and re-import in your deploy script.

Onboarding surface for clients. The strongest day-to-day use is scoping the how-to area to a curated set of guides for each client site. Pair it with Statamic's permission system so editor roles see the guides while super users see everything.

Theming to match the CP. Publish the views and override the namespace (view('statamic-how-to-addon::...')) so guides inherit your CP branding rather than looking like a bolted-on third-party panel. Keep overrides thin — the more you fork, the more v1.5.x → v1.6.x becomes a merge job.

Multi-site awareness. On multi-site installs, verify whether guide content is site-scoped or global. If it's global, write guides that are site-agnostic (or explicitly label them "applies to the UK site only"); if it's per-site, wire the guide content into each site's onboarding flow.

Deployment. No migrations means this is deployment-cheap: add the composer bump, run the publish step, clear caches, done. Put the publish + cache-clear commands in your deploy script's after: hooks so upgraded view assets never go stale.

Upgrade validation workflow. Branch, bump to ^1.5, load the CP, open the how-to area, confirm nav entry, styling, and any Vue/asset-driven UI renders. Statamic 4 moved addon asset builds to Vite; addons still shipping Laravel Mix assets are the common breakage point.

Gotchas and Tips

• v1.5.0 is explicitly untested by the author. The release note says "Let me know if you run into any problems." That is not a red flag on its own, but it means you are the QA. Do not roll it to a client site's production without a staging smoke test of the CP nav, the addon's routes, and any compiled assets. Budget the time rather than assuming "Statamic 4 support" means done.
• Pin deliberately. Use "jonassiewertsen/statamic-how-to-addon": "^1.4" if you're on Statamic 3 and not ready to move; use ^1.5 only after your smoke test passes. Avoid dev-main on client projects.
• Stale published assets after upgrade are the most likely visible failure. Re-run the publish step with --force for the addon's asset/view tags, then clear Statamic's cache and compiled views. Symptom: the panel renders but styles or scripts 404.
• Addon discovery. Statamic finds addons via the extra.statamic block in composer.json plus the service provider's manifest. If the CP nav item is missing after install, check that block first, then php artisan route:list | grep -i how to confirm routes registered at all.
• Route and namespace collisions. A generic name like "how-to" can collide with your own app routes or a second documentation addon. Confirm there's no duplicate prefix before debugging phantom behaviour.
• Statamic version drift. If you get a composer conflict on statamic/cms, read the addon's constraint rather than forcing --with-all-dependencies. A constraint that hasn't been widened is a reliable signal of where the author's testing stopped.
• Extension points. Prefer config values and published-view overrides over editing vendor/. Anything you patch inside vendor/jonassiewertsen/ disappears on the next composer update, and this release is exactly the kind of small, infrequent bump where that happens unnoticed.
• Debugging path when something breaks: storage/logs/laravel.log → php please support:details (captures Statamic/PHP versions for a useful bug report) → the addon's GitHub issues. Since the author asked for problem reports on this release, a reproducible issue with support:details output is the fastest route to a fix.