Statamic Super Sections Laravel Package

Getting Started

Since v1.1.0 is the initial release, treat this as a greenfield onboarding rather than an upgrade. Start with the package's README.md and CHANGELOG.md, then check composer.json for the supported Laravel/PHP version constraints before installing.

Minimal steps:

1. composer require <vendor>/<package> (pin to ^1.1 until you've validated stability).
2. If the package ships a service provider, confirm it's auto-discovered; otherwise register it in config/app.php (Laravel 10 and below) or bootstrap/providers.php (Laravel 11+).
3. Publish assets/config: php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider".
4. Run any bundled migrations: php artisan migrate.
5. Smoke-test with a single call in tinker before wiring it into application code.

First use case: pick the smallest read-only path (e.g. a resolve()/->get() call, a single facade method, or a single artisan command) and confirm it works end-to-end before adopting it for write operations or queue-driven work.

Implementation Patterns

Resolve from the container, don't new it up. Inject the package's main contract/class through the constructor rather than instantiating it directly — that's what makes the package swappable and mockable later.

Wrap it in your own adapter. Even a thin service class (App\Services\FooService) that delegates to the package keeps vendor calls out of controllers, jobs, and models. If you ever swap the package or upgrade past a breaking change, you change one file.

Use the facade for terse call sites, the injected instance for testable ones. Facades are fine in Blade/controllers; injected instances are better in jobs and services where you want to mock without Facade::shouldReceive().

If the package exposes events, listen rather than poll. Many Laravel packages dispatch domain events (PackageEvent::class) — hooking those into listeners keeps your code decoupled from the package's internal API surface.

Queue long-running operations. If the package offers a sync driver and a queue driver, default to queue in production and only use sync in tests.

Testing. Use the package's fake() equivalent if it exists; otherwise bind a mock into the container in setUp() and assert on the contract, not the concrete class.

Gotchas and Tips

• Config caching will bite you. Any config you publish is cached by php artisan config:cache. If you're reading env vars inside the package config file, do it only there — env reads elsewhere return null in production.
• Facade mocking masks real bugs. Facade::shouldReceive() won't catch signature drift after an upgrade. Pair your facade mocks with at least one integration test that hits the real container binding.
• Migration ordering. If the package publishes migrations, they may run before or after your own depending on filenames. Check php artisan migrate:status after install; rename with a later timestamp if foreign keys fail.
• Version pinning. At 1.1.0, the public API is still forming. Pin to ^1.1 in composer.json and read each CHANGELOG.md before minor bumps — semver on 0.x/early packages is often aspirational.
• Publish tags matter. vendor:publish --tag=config vs --all differ; publishing everything can overwrite your app's own stubs. Prefer tagged publishes.
• Debugging. php artisan about confirms the provider is loaded; php artisan package:discover re-runs discovery if you've added it manually. Enable the package's own debug/log channel in config/logging.php rather than dumping inside the package.
• Extension points. Look for a driver/manager pattern (Manager class, extend() method, or a contracts namespace). Those are the sanctioned places to customize behavior without forking.
• No upgrade guide yet. Because this is the initial release, there's no deprecation path. Expect breaking changes on minor bumps more than you would with a mature package; budget time for re-reading the changelog each release.