Statamic Live Preview Tag Laravel Package

Getting Started

v1.0.0 is the initial release, so there is no upgrade path to worry about — install fresh and pin the constraint (^1.0) so future minor bumps stay predictable. Because this is the first tagged version, treat the public API as "new and still settling": verify the README against the actual source before you build habits around it.

Minimal steps:

composer require <vendor>/<package>:^1.0
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"

The service provider should be auto-discovered via extra.laravel.providers in the package's composer.json, so there is nothing to register by hand in config/app.php unless the package targets an older Laravel version.

Where to look first, in this order:

1. README.md — the only place that documents the intended entry point for v1.0.0.
2. composer.json — check the require block for the supported Laravel/PHP range before assuming compatibility with your app.
3. config/<package>.php — the published config file is effectively the package's API surface at first release; read it before reading source.
4. src/ — look for the service provider, then follow the container bindings it registers; that reveals the intended resolution path.
5. tests/ — at v1.0.0 the test suite is the most reliable documentation of real usage, especially for edge cases the README omits.

First use case: wire up the simplest end-to-end path — resolve the package's main class out of the container, run it against a single record in a local/dev database, and confirm the result before integrating it into a request lifecycle or a job.

Implementation Patterns

Constructor injection over facades. At first release, prefer injecting the package's concrete class or its bound interface into your controller, job, or service. Facades are convenient but hide the dependency and make it harder to see when the package's API shifts in a later minor version.

Bind once, in a dedicated service provider. If you need to swap an implementation, register the binding in your own AppServiceProvider rather than editing the published config. Config is for values; the container is for substitutions.

Keep package calls out of controllers when the call does I/O. Wrap package usage in a small application-level service or action class. When v1.1.0 changes a method signature, you edit one file instead of grepping your codebase.

Drive behavior from the published config. Read the config file and set explicit values for every key you care about rather than relying on package defaults. Defaults are the most likely thing to change in a 1.x minor release.

Test against the real binding. Use the package in feature tests with your configured test database rather than mocking it, at least initially — you don't yet know which seams are stable enough to mock.

Queue anything that touches the network or a remote API. If the package makes outbound calls, put it behind a job so retries, backoff, and failed() handling are yours rather than the package's.

Version-pin in CI. Run your test suite against ^1.0 and, separately, against the lowest supported Laravel version from the package's composer.json so a future release that drops support fails loudly.

Gotchas and Tips

Config caching. After any config edit run php artisan config:clear in development. A stale cached config is the most common cause of "the package is ignoring my settings" on a fresh install.

Publish tags are your friend. Use --tag=<package>-config and --tag=<package>-migrations individually rather than publishing everything. A blanket publish at v1.0.0 often drags in example files you'll never use and can silently overwrite later.

Migrations and existing data. If the package ships migrations, run them in a scratch database first. At an initial release, migration defaults (column types, nullable flags, index names) are the least battle-tested part of a package.

No deprecations to worry about yet — but no stability guarantees either. v1.0.0 means "tagged," not "frozen." Follow the CHANGELOG and read the diff before bumping the minor version. If the package follows semver you're safe on ^1.0; if the README doesn't state a policy, pin exactly (1.0.*) until it's clear.

Static analysis will complain at first. Facades and magic __call resolution usually need a Laravel Idea / barryvdh/laravel-ide-helper hint or a @method docblock. Don't suppress the error globally; add the annotation at the call site.

Debugging a silent no-op. When a package call appears to do nothing, check in this order: (1) the service provider actually registered — php artisan about or app()->getLoadedProviders(); (2) your config is loaded, not just published; (3) the package isn't swallowing an exception internally — check storage/logs/laravel.log; (4) you're not resolving a different implementation than you configured.

Extension points to look for before you fork. Scan the service provider for bind/singleton calls and any *Manager or driver-style class. If the package exposes a driver or manager pattern, extend it rather than patching vendor code — that keeps you on the upgrade path.

Vendor directory is not your codebase. Never edit vendor/<vendor>/<package>. If you need a behavior change, publish the config, bind your own implementation, or open an issue — patched vendor code disappears on the next composer update.