Laravel Filesystem Qiniu Laravel Package

Getting Started

• Check your Laravel version before anything else. v3.0.0 is Laravel 13 only. There is no overlap with the 2.x line, so if the host app is on Laravel 10/11/12 you must stay on 2.x — this is a hard gate, not a soft deprecation.
• Verify the constraint resolves: composer require <vendor>/<package>:^3.0 and then composer why-not laravel/framework 13 if it refuses. Confirm the package's illuminate/* constraints and minimum PHP version match your app (Laravel 13's PHP floor applies transitively).
• Where to look first, in order: UPGRADE.md / CHANGELOG.md (the release notes here are terse — the real migration guide is the v2→v3 diff), the published config/*.php, the service provider's bindings, and the README's testing section.
• First use case: don't upgrade in place. Create a branch, bump the constraint, composer update <vendor>/<package> --with-dependencies, run the app's existing test suite, and only then walk the app's integration points. If the package ships a test suite or a smoke command, run it in a scratch Laravel 13 app first to confirm the package itself behaves on your PHP build.

Implementation Patterns

• Two-step upgrade. Land "app on Laravel 13" and "package on v3" as one atomic change in a dedicated branch. Because v3 drops older Laravel support, you cannot stage them separately in a single repo.
• Diff the config, don't overwrite it. Re-publish config to a scratch directory (php artisan vendor:publish --tag=<package>-config --force in a throwaway app) and diff against your committed copy. Majors routinely rename or restructure keys, and the release notes give no signal either way.
• Resolve from the container, not facades. Bind the package's contracts/interfaces (or use its fake/swap helpers if provided) in feature tests so the upgrade surface is one binding point rather than scattered static calls. This is what makes the next major cheap.
• Mirror the package's CI. The release adds CI and a refreshed test stack — adopt the same PHP matrix and static-analysis/lint tooling in your own pipeline. If the package now enforces a coding standard or PHPStan level, matching it locally catches the same class of breakage before it reaches the package's issue tracker.
• Pin during rollout. "<vendor>/<package>": "3.0.*" while stabilising, then loosen. If the package hooks framework internals (middleware, migrations, queue jobs, service container decorators), canary it behind a queue worker or staging deploy before a full release.
• Integration tip for downstream packages. If you maintain your own package that depends on this one, your composer.json now needs both an ^13.0 framework constraint and a ^3.0 constraint here — and a dropped-support policy of your own, since there's no shared version window with v2.

Gotchas and Tips

• No upgrade window exists. v3 supports Laravel 13 only and 2.x does not support Laravel 13. Any repo, internal package, or CI matrix still on Laravel ≤12 is blocked until the whole dependency graph moves together. Plan for a flag day, not a gradual rollout.
• Transitive constraints are the usual failure. A third-party package still capping illuminate/support at ^12 will make the install impossible even though your app is ready. composer why-not laravel/framework 13.0 names the culprit; composer update --with-dependencies after the fix confirms it.
• Major = permitted BC breaks, and the notes don't enumerate them. Grep your codebase for the package's public API surface (facade aliases, published config keys, event class names, view/route names, migration stubs) and compare against the v3 source. Assume nothing survives unchanged just because it wasn't listed.
• Laravel 13 removals can leak through. If the package previously carried compatibility shims for older framework versions, v3 likely deleted them. Deprecations your app relied on indirectly may now be fatal.
• Don't copy the package's dev dependencies. "Update test stack" means its PHPUnit/Pest/PHPStan versions moved — those may require a newer PHP than your app's production runtime. Read them for ideas, pin your own.
• Debugging order: php artisan about (confirm framework version actually installed), composer show -a <vendor>/<package> (verify resolved version and constraints), then a scratch app with a force-published config to compare against production config.
• Extension points: prefer container bindings, events, and published config over subclassing the package's internals. With the release notes this thin, treat every non-public class as unstable until you've read the diff — reach for the interfaces the package exposes, and if it doesn't expose one for a hook you need, file the issue rather than monkey-patching.