Statamic Original Filename Laravel Package

Getting Started

This is a Statamic addon, so it slots into a Laravel app that already has statamic/cms installed. Release 1.1.1 only tightens the Composer constraint to require Statamic from a stable version — there are no API changes to learn, but it is the signal that the addon is now intended for production installs rather than beta projects.

Minimal steps:

composer require <vendor>/<package>:^1.1
php artisan vendor:publish --tag=<package>-config   # check README for the exact tag
php artisan config:clear

Then confirm the addon registered itself:

php artisan about          # or
php please addons:list     # Statamic 3/4 style listing

Where to look first, in this order:

1. composer.json → extra.statamic — tells you whether this is a tags, fieldtypes, modifiers, widgets or commands addon. That single key determines 90% of how you'll use it.
2. The service provider — what it binds, what it registers, whether it publishes config/views/migrations.
3. The config file — almost every gotcha in a Statamic addon is a config or cache issue, not a logic issue.
4. README usage block — the tag/fieldtype handle you'll actually type into templates.

First real use case: render whatever the addon exposes inside an Antlers template on a single entry, with the config defaults untouched. Get one visible output before touching config — that isolates "is it installed" from "is it configured".

Implementation Patterns

Config-driven setup. Prefer publishing the config file and editing it over relying on defaults, then drive environment-specific values through config/<package>.php reading env(). Commit the published config; keep secrets in .env. Cache with php artisan config:cache in deploy scripts — but only after the config is final, since Statamic addons frequently read config at boot.

Template usage (Antlers). Typical shape for a tag-based addon:

{{ <tag_handle> }}
  {{ if <flag> }}...{{ /if }}
{{ /<tag_handle> }}

Pair it with {{ cache }} or Statamic's static caching only after you've confirmed the output is not user-specific. For modifiers, chain them like any other: {{ title | <modifier_handle> }}.

Blade / Laravel-side usage. If the addon exposes a facade or injectable service, resolve it from the container rather than instantiating:

public function __construct(private PackageService $service) {}

Wrap it in your own thin class when you call it from controllers, jobs or commands — that keeps the addon's namespace out of your domain code and makes a future major version a one-file change.

Fieldtype integration. If the addon is a fieldtype, add it to a blueprint, then read the value through augmentation ($entry->augmentedValue('handle')) rather than the raw value. Raw values in a fieldtype almost always need the addon's own augmentation step, and skipping it is the most common "it returns an array instead of a string" bug.

Multi-site. Check the README for site-specific config. Where the addon is site-aware, the pattern is to key config by Statamic::getCurrentSite()->handle() and clear the Stache after changing it.

Testing. Use Statamic's test helpers (Statamic\Testing\AddonTestCase if the addon ships one) so the addon boots correctly in the test suite. Without a proper test case, tests fail with "class not found" on tag handles rather than a meaningful assertion.

Deployment checklist. composer install --no-dev → config:cache → statamic:stache:clear → view:clear. Skipping the Stache clear after a config change is the single most common cause of "my change didn't apply".

Gotchas and Tips

• The 1.1.1 constraint is a hard floor. Because the addon now requires Statamic from stable, installing it alongside a Statamic beta/RC will fail dependency resolution. If you're pinned to a pre-release Statamic, stay on the addon version below 1.1.1. If you're on stable Statamic, 1.1.1 is a safe drop-in — no code changes needed.
• composer update alone isn't enough. After updating, run php artisan vendor:publish --force only if the README says the config changed; otherwise you'll silently overwrite local tweaks.
• Stache and static caches don't know you changed config. Always php please stache:clear (and php please static:clear if you use the static cache) after touching the addon's config or a blueprint.
• Addon discovery is cached by Composer. Newly installed addons that "don't exist" usually need composer dump-autoload. In production, --optimize-autoloader builds the classmap the addon registers from.
• Antlers escaping. Output from a tag is escaped by default; if the addon returns HTML, you need {{ ... | raw }} or the addon's own markdown/sanitize handling. Don't reach for raw before checking whether the addon ships a modifier for it.
• Config read too early. Statamic addons often read config in boot(). If you set config at runtime (in a middleware or test), do it before the addon boots — otherwise you're editing an already-resolved value.
• Version constraints in your app. Pin the addon with ^1.1 rather than *. Statamic addons have historically shipped constraint-only patches like this one, and a caret keeps you on the stable-Statamic line while still getting bug fixes.
• Extension points worth knowing. Prefer Statamic events (EntrySaved, BlueprintSaved) over editing the addon's source; add a custom modifier/tag that wraps the addon if you need behaviour it doesn't expose. Anything you fork, you maintain.
• Debugging order when nothing happens: (1) composer show <vendor>/<package> confirms the version, (2) php artisan about / addon listing confirms registration, (3) the config file confirms the handle matches what you typed in the template, (4) stache:clear and view:clear, (5) storage/logs/laravel.log. That order resolves nearly all installation issues without reading the source.
• Note on scope: the package metadata supplied was empty, so the specifics above are the general shape for a stable-Statamic addon at 1.1.1. Confirm the exact tag handles, config keys and publish tags against the README before wiring it into a blueprint.