Statamic Plausible Laravel Package

Getting Started

This release (1.2.0) is primarily a compatibility release: it adds support for Statamic 3.2. Treat the upgrade as a dependency alignment task first, then verify runtime behavior.

Minimal steps:

1. Confirm your application is already on Statamic 3.2 (composer show statamic/cms should report a 3.2.x version). If you are still on an earlier 3.x line, plan the Statamic upgrade before pulling this release.

2. Require the new version explicitly and inspect what Composer resolves:

   composer require <vendor>/<package>:^1.2 --with-dependencies
   

3. If the addon publishes configuration, views, or assets, publish them and diff against your existing copies rather than overwriting blindly:

   php artisan vendor:publish --provider="Vendor\\Package\\ServiceProvider"
   

4. Clear Laravel and Statamic caches so addon discovery and the Stache pick up the new code:

   php artisan config:clear
   php artisan cache:clear
   php artisan statamic:stache:clear
   php artisan package:discover
   

5. Smoke-test the package's main entry point in a non-production environment — typically a fieldtype, tag, modifier, widget, or facade call — on a single test entry or route before rolling it into shared templates.

Where to look first: the package's composer.json (for the statamic/cms constraint and PHP requirement), its service provider (for bindings, publish tags, and registration), and its config file (for environment-driven behavior). The first real use case is usually rendering the package's output inside an Antlers template or invoking it from a Laravel route/controller; start with the smallest possible surface area.

Implementation Patterns

Pin and test the compatibility matrix. Because 1.2.0 targets Statamic 3.2, keep the addon and statamic/cms pinned in composer.json and mirror those versions in CI. A matrix of one Laravel version and one Statamic minor is usually enough for an addon of this scope, but it prevents accidental drift onto 3.3+ before the package declares support.

Prefer container resolution over static calls. If the package exposes a facade, resolve the underlying service from the container in application code and tests. This keeps you insulated if the package changes its binding in a future release and makes mocking straightforward.

Keep configuration in config/. Publish the config file and reference it via config('package.key') rather than reading environment variables directly at runtime. This is especially important in production, where php artisan config:cache will freeze configuration and env() calls outside config files will return null.

Use it behind a thin application-level wrapper. For anything used in more than one template or controller — a formatter, an API client, a fieldtype renderer — wrap the package call in a small service class. That gives you one place to adapt when the addon's API shifts across Statamic minors, and one place to add caching.

Follow Statamic's addon testing conventions. Extend the package's addon test case (or Statamic's addon test case) so the Statamic application boots with the addon registered. Test the integration point — the tag output, the fieldtype's augmentation, the saved value — rather than the package internals.

Stage the upgrade on a branch. Upgrade in this order: bump Statamic to 3.2, run the app's test suite, then bump the addon to 1.2.0, then run the suite again. If something breaks, you will know which side caused it.

Watch the Stache after upgrading. If the addon stores or indexes content, warm the Stache in the same deploy step that clears it, and verify in staging that entries still resolve correctly before promoting.

Gotchas and Tips

• Compatibility support is not the same as a breaking-change guarantee. The release notes only state Statamic 3.2 support. Check the package's composer.json for whether older Statamic constraints were dropped; if your app still runs 3.0 or 3.1, composer update may resolve to an older addon release or fail outright.
• Addon discovery is cached. After upgrading, a stale bootstrap/cache/packages.php can leave the old service provider registered. Run php artisan package:discover and, if behavior still looks stale, delete bootstrap/cache/*.php and rebuild.
• Statamic caches are separate from Laravel caches. php artisan cache:clear does not clear the Stache. Use the Statamic-specific clear commands, and remember that published views and config are files on disk — clearing caches will not update them.
• Published config files win. Once published, config/<package>.php is yours; new default keys added in 1.2.0 will not appear automatically. Compare the package's shipped config against yours after every minor upgrade.
• Antlers output is not escaped the way Blade output is. If the package returns user-influenced content, check whether you need to escape it in the template layer. Debug rendering issues by isolating the tag in a bare template rather than inside a complex layout.
• Config caching and closures. If the package's config contains closures or environment reads, config:cache can behave unexpectedly. Test a production-like build (config:cache + route:cache) before deploying.
• Version conflicts surface as confusing runtime errors. A Class not found or a method-signature error after upgrading usually means two packages are pinned to different Statamic expectations. Use composer why statamic/cms and composer depends <vendor>/<package> to trace it.
• Debugging order: check storage/logs/laravel.log first, then clear config and Stache, then verify addon registration with php artisan about or by dumping the resolved provider list. Only then start instrumenting the package code.
• Extension points to prefer: Statamic events and hooks, custom tags, and published views are more stable than subclassing internal package classes. If you must extend internals, note the exact class and version you depend on — that is the first thing to re-check at the next Statamic minor.