Statamic Bearhub Laravel Package

Getting Started

This release (v1.1.2) is a maintenance release, so the install path is unchanged from v1.1.x — but the loosened Statamic constraint means you should verify which Statamic version Composer actually resolves for you before writing any code.

1. composer require <vendor>/<package>:^1.1 and immediately run composer show <vendor>/<package> plus composer show statamic/cms to confirm the resolved Statamic version. Because the constraint was widened, the version you get is now driven by the rest of your dependency graph, not by this package.
2. Publish and review any config: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" (or --tag=<package>-config). Read the config file's comments first — they are usually the most accurate documentation of defaults.
3. Confirm the service provider is auto-discovered (php artisan about or php artisan package:discover output). Statamic add-ons and Laravel packages differ here; check whether the package registers itself as a Statamic addon (look for an AddonServiceProvider or a statamic key in composer.json's extra).
4. Clear caches before first use: php artisan config:clear && php artisan cache:clear && php artisan view:clear. Statamic's own caches (Stache, static caching) are a common source of "it installed but nothing happens".
5. First use case: exercise the package's primary entry point in a local, seeded environment — typically rendering the feature in a Statamic template/antlers view or calling the Laravel-side facade in a tinker session (php artisan tinker). Verify output before wiring it into existing content.

If you are upgrading from an earlier v1.1.x, the upgrade is low-risk: run composer update <vendor>/<package> --with-dependencies and then re-run your test suite, paying specific attention to any test that touches Statamic content resolution.

Implementation Patterns

Pin your Statamic version in CI, not in composer.json. The headline change is the loosened Statamic constraint. The safest day-to-day pattern is to let the package float but constrain Statamic explicitly in your root composer.json (e.g. "statamic/cms": "^5.0"). This keeps the package flexible while making your application's resolved Statamic version deterministic and reviewable in diffs.

Matrix-test on upgrade. If you maintain multiple Laravel/Statamic versions, run CI against the lowest and highest Statamic versions your constraint permits. A widened constraint in a dependency is exactly the scenario where composer update on a legacy project silently downgrades or upgrades Statamic underneath you.

Wrap the package behind a thin application-level service. Whether the package exposes a facade, a helper, or Statamic tags, define one small app class (e.g. App\Support\<Feature>Gateway) that calls into it. When the package's API shifts or you swap it out, you change one file instead of grepping templates.

Inject via the container rather than resolving statically. Prefer constructor injection of the package's classes in your own services/controllers so tests can substitute fakes. If the package only ships a facade, add a binding in a AppServiceProvider that resolves it, and use that binding from your code.

Compose with Statamic's data layer rather than duplicating it. If the package augments entries, terms, or globals, drive its behaviour from the Statamic object rather than re-fetching content with Eloquent. Watch for N+1 patterns when iterating a collection in an Antlers loop — resolve data once in a tag or a view composer and pass it in.

Use events for side effects. If the package dispatches events (typical for Statamic-integrated packages around save/publish), attach listeners in EventServiceProvider or via Event::listen in a dedicated provider. This keeps your custom logic decoupled and survives minor version bumps far better than subclassing.

Cache aggressively but key correctly. Any package that reads Statamic content is a candidate for Cache::remember. Build the cache key from the entry ID and $entry->updated_at (or the package's own hash if provided), otherwise Statamic's save in the CP won't invalidate your cache.

Local dev workflow. Keep a seeded content set in a test site or a statamic:install-ed fixture so you can exercise the package without touching client content. Pair this with php artisan statamic:stache:clear in your reset script.

Gotchas and Tips

A loosened dependency constraint is not a no-op. "Losen up Statamic dependency" changes what Composer can resolve. After composer update, always diff composer.lock — not just for this package but for statamic/cms and its transitive deps. CI that runs composer update (rather than composer install) becomes non-reproducible; switch it to composer install against a committed lock file.

"Updated packages" means your transitive tree moved. Even though this package's own code is likely unchanged, its dependency bumps can shift illuminate/*, symfony/*, or Statamic internals. Run composer outdated --direct and your full test suite rather than assuming a patch bump is inert.

Statamic's caches will lie to you. After installing or upgrading, symptoms like "config change has no effect" or "old template still rendering" are almost always Stache or static caching. Standard debugging order: config:clear → cache:clear → view:clear → statamic:stache:clear → statamic:static:clear (if using the static caching addon).

Config cache in production. If the package reads config at boot, php artisan config:cache will freeze it. Anything set at runtime (env-driven toggles, per-request overrides) must be read inside a closure or service method, not at provider boot, or it silently won't apply.

Check the addon-vs-package boundary. Statamic add-ons sometimes register routes, tags, or fieldtypes via a Statamic-specific provider, not Laravel's register()/boot(). If the package's features don't appear, verify the addon is listed under config/statamic/... or discovered via php please addons — a mismatched provider is a very common cause of silent no-ops.

Watch for a minimum-version floor. Loosening an upper bound is common; loosening a lower bound would let Composer install an older Statamic than the package supports. Confirm the constraint is ^X.Y toward newer releases only, and read the composer.json constraint directly rather than trusting the changelog wording.

Extension points to prefer over forks. Look for published config, container bindings, and any interfaces the package ships. If you need to alter behaviour, bind your own implementation of its interface in a provider — this survives composer update, whereas a forked copy becomes a maintenance liability on every Statamic major.

Logging when behaviour is opaque. Wrap the package's entry points in a Log::debug() with the inputs and Statamic context (entry ID, site handle, locale). Statamic's multi-site behaviour is a frequent source of "works on default site, fails on secondary" bugs, and locale/site is the first thing to log.

Don't skip the changelog for v1.1.0 and v1.1.1. With no prior assessment on record, treat v1.1.2 as your entry point and read backwards — if v1.1.0 introduced the Statamic support at all, the constraint history tells you which Statamic majors are actually tested versus merely permitted.