Laravel Data Sync Laravel Package

Getting Started

v3.0 is a hard platform bump rather than a feature release: PHP 7 support is dropped and the test bench moves to v7, which is what makes the package runnable on Laravel 9. Treat your first step as an environment audit, not a code change.

1. Confirm your runtime first. You need PHP 8.0+ and Laravel 9. On Laravel 8 or PHP 7.4, stay on the v2 line — v3 will not install, and forcing it with --ignore-platform-reqs will get you a package that boots and then fails at runtime.
2. Check the constraint before upgrading. Run composer why-not vendor/package ^3.0 to see exactly which of your dependencies (or your own php platform requirement) is blocking the upgrade. Nine times out of ten the blocker is a sibling package still pinned to the old test bench, not this one.
3. Read the service provider. Because the release is compatibility-only, the public API surface should be unchanged from v2. Skim the provider's register()/boot() and the config file to confirm nothing was renamed or removed as collateral — that's the one place a "compatibility release" can silently break you.
4. Publish and diff the config. php artisan vendor:publish --tag=config (confirm the tag from the provider) and diff against your existing published copy. Any new keys will fall back to defaults, but you want them visible in version control.
5. First use case. The fastest smoke test is a single feature test that resolves the package's main entry point from the container and exercises one happy path. If that passes on Laravel 9 / PHP 8, the upgrade is almost certainly done.

Implementation Patterns

Upgrade in a branch, with the lockfile rewritten, not patched. Bump the constraint to ^3.0, delete composer.lock, and re-resolve. Incremental composer update vendor/package on a major with a test bench bump tends to leave orphaned dev dependencies that mask real incompatibilities until CI.

Pin the platform in CI, not just locally. Because the package now requires PHP 8, add an explicit config.platform.php entry to composer.json so that a developer on 7.4 gets a clear resolution error instead of a confusing runtime failure in production. Run a matrix of PHP 8.0 and your highest supported version — Laravel 9 supports both 8.0 and 8.1, and the package's own CI may only cover one.

Wrap the package behind your own boundary. For anything beyond a trivial integration, inject the package's contract/manager class into a thin application-level service and let your controllers and jobs depend on that. This is the pattern that makes the next major release a one-file change instead of a grep across the codebase. It costs about twenty lines and pays for itself the first time a package does a v4.

Resolve from the container; don't new it up. Use constructor injection or app(...) and avoid the facade in long-lived workers (queue workers, Octane, Swoole). Facades cache the resolved instance and can hold stale config across requests if you're not careful with Facade::clearResolvedInstances().

Configuration over code. Anything the package exposes as a config key — timeouts, credentials, driver selection, feature toggles — belongs in config/ and an env var, not hardcoded. Keep the published config file as the single source of truth and reference config('package.key') at the point of use rather than caching values in properties during boot(), which breaks under config:cache.

Test with the same bench the package uses. Since v3 aligns with Testbench 7, mirror that in your own package/app tests: orchestra/testbench:^7.0, phpunit/phpunit:^9.5. Extend Orchestra\Testbench\TestCase and register the provider explicitly in getPackageProviders() so your tests don't depend on auto-discovery.

Integration tips that hold up in production. Register any package event listeners in your own EventServiceProvider rather than relying on the package's internal wiring, and if the package ships queued jobs or listeners, review them for PHP 8 compatibility issues (null-to-string coercions, implicit float-to-int, dynamic properties) — that's the class of bug a PHP 7 → 8 jump surfaces most often, and a compatibility release won't have fixed them for you.

Gotchas and Tips

This is a breaking change even though no API changed. Dropping PHP 7 is a semver-major for a reason: if you support a library ecosystem that still ships 7.4, you cannot upgrade. Decide deliberately whether v3 is your floor or whether you need to maintain a v2 branch for older consumers.

PHP 8 deprecations will bite before failures do. Dynamic properties are deprecated in 8.2 and several 8.0/8.1 behaviours changed coercions. After upgrading, run your suite with error_reporting(E_ALL) and treat deprecation output as a to-do list — Laravel's HandleExceptions will happily swallow them until they become errors in 9.0.

composer update resolution failures are usually transitive, not this package. If Composer reports a conflict on php or orchestra/testbench, trace it with composer why-not rather than loosening constraints. Removing config.platform.php to "make it install" is the most common way teams ship a broken deploy.

Watch the lockfile in CI caches. A stale composer.lock in a CI cache keyed only on composer.json will keep running v2 after you've bumped the constraint. Key the cache on the lockfile hash.

Config caching hides boot-time reads. If you register routes, bind interfaces, or read credentials in boot(), verify with php artisan config:cache && php artisan config:clear and a full test run. A package that reads env directly in boot() will break under config:cache — and major-version releases are exactly when that gets introduced.

Test bench 7 is a dev-only upgrade — but it isn't invisible. It changes the default Laravel version your tests boot against, so tests that were passing against the old bench may start failing for reasons unrelated to the package. If a previously green suite goes red, check whether it's bench behaviour before you go looking for a regression in the package.

Debugging checklist, in order: confirm the installed version with composer show vendor/package; confirm the provider is registered with php artisan about; dump the merged config to check your overrides actually landed; and if behaviour differs between php artisan tinker and a request, suspect a facade/container caching issue before you suspect the package.

Extension points still apply. Even though v3 is compatibility-only, keep your customisations in published config, bound interface implementations, and your own listeners rather than editing vendor files. If you find yourself needing to touch vendor/, the package likely exposes a contract for it — check the provider's bindings before you fork.

Verify the release before you commit to it. The release notes describe one change; confirm it by checking the diff and the composer.json require block. If the maintainer also removed a method or bumped another dependency, composer.json is where it shows up first.