Statamic Wrapped Laravel Package

Getting Started

1. Require the addon (composer require <vendor>/<addon>) and let Statamic's addon discovery register it — no manual service provider entry needed in a standard install.
2. Publish the config (php artisan vendor:publish --tag=<addon>-config) so you have a file-backed baseline for the addon's three settings groups: the look/appearance options, soundtracks, and the public-links switch.
3. Open the addon's settings screen in the Control Panel and save something non-default. This is your first real use case: confirm that a CP-saved value actually overrides the published config value on the front end.
4. On v1.6.5 specifically, also confirm which statamic/cms version you are on. The release was published to align with an upstream fix (statamic/cms#15495); running the addon on an older CMS is supported but you are relying on the addon's own compatibility path.

Where to look first when something looks wrong: the addon's config file (the fallback source of truth), then the CP settings screen, then the addons settings entry in your Statamic storage/config.

Implementation Patterns

Treat config as defaults, CP settings as overrides. The addon reads saved settings first and silently falls back to the config file. That makes config a genuinely useful pattern: ship sane defaults in config/<addon>.php, commit them, and let editors adjust look/soundtracks/public-links per environment through the CP.

Per-environment settings. Because the fallback is silent, you can keep config committed with production values and still have local/staging CP overrides — but only if you are deliberate about which environment's CP data ships in your database. For multi-environment setups where editors change settings in production, treat the settings record as content: include it in your database sync/export routine rather than assuming config alone is enough.

Reading settings in your own code. If you are extending the addon (custom views, a blade partial for the look, custom soundtrack rendering), retrieve values through the addon's settings API rather than reading the config file directly. Going straight to config() bypasses the CP and is exactly the failure mode v1.6.5 is guarding against — you would get consistent values but silently ignore editor intent.

Front-end integration. The public-links switch is the one to wire into route/middleware decisions and into any sitemap or share-link generation. Read it once per request (or cache it) rather than in a loop, and make sure your own templates respect it — the addon controls its own output, not links you build yourself.

Deployment workflow. After deploying, hit the CP settings screen once and re-save if you upgraded across 1.6.4 → 1.6.5 with existing saved settings. This is cheap insurance against a settings record that was written under the older lookup behaviour.

Gotchas and Tips

• Silent fallback is the core hazard. If the settings lookup misses, the addon does not error — the look, your soundtracks and the public-links switch quietly revert to config. Any "why did my appearance change after deploy?" bug should start with "did the settings record resolve?" not with the template.
• Package name vs slug. v1.6.5 changes how the addon asks for its saved settings: by package name, matching Statamic's own settings screen. The 1.6.4 behaviour (lookup by slug) was a workaround for statamic/cms#15495 and would break once that upstream fix shipped. Practical consequence: keep statamic/cms and this addon roughly in step. Pinning the CMS far behind while upgrading the addon (or vice versa) puts you on the less-tested side of that handshake.
• No upgrade steps. v1.6.5 explicitly requires none, so a plain composer update is fine. Do not add a migration or a settings re-save to your deploy script on account of this release.
• Verify, don't assume, after a CMS bump. The upstream fix lands in a future statamic/cms release. When you take it, re-check the three settings groups in the CP on a non-production environment before trusting the upgrade — the whole point of the release is that this pairing is now correct on both sides, and it is worth one manual confirmation.
• Cache clearing. Statamic caches settings/addon manifests. If a CP save appears not to take effect, php artisan cache:clear and php artisan statamic:stache:clear before you go digging into the addon code.
• Extension point worth knowing. The config file remains the reliable, version-independent way to set values — it is the one path that does not depend on the package-name lookup at all. For values that must never drift (for example, a compliance-driven public-links default), set them in config and treat the CP toggle as a per-site convenience, not the source of truth.
• Debugging tip. Temporarily set a config value to something obviously different from the CP value. Whichever one renders tells you immediately whether the settings lookup resolved or fell through — much faster than reading the addon source.