Laravel Medialibrary Ext Laravel Package

Getting Started

1. Confirm the compatibility window first. Release 10.2.0 supports PHP 8.1 and 8.2 only and Laravel 10. It drops Laravel 8. Before installing, check your app’s composer.json for php and laravel/framework constraints. If you are still on Laravel 8, either stay on the previous package release or upgrade the application before adopting 10.2.0.
2. Install with an explicit constraint. Use composer require vendor/package:^10.2 rather than an unconstrained update. If Composer reports a conflict, run composer why-not vendor/package 10.2.0 to identify the blocking dependency.
3. Look at the package service provider and config first. Read the README’s requirements/installation section, then inspect the package’s config/*.php, service provider register()/boot() methods, migrations, and any facade or contract it exposes. This tells you what is auto-discovered versus what must be published.
4. Publish only what the documentation requires. If config, migrations, or assets are publishable, use the documented vendor:publish tag/provider command. Avoid editing vendor files.
5. Start with one narrow use case. Wire the package into a single service, job, or controller path behind configuration, then verify with a feature test or php artisan tinker. This validates container binding, configuration, and database assumptions before a broader rollout.
6. Treat 10.2.0 as a compatibility release. The release notes list framework/PHP support changes, not new runtime features. Your first evaluation should be installation, boot, and existing behavior—not new APIs.

Implementation Patterns

• Inject contracts, not facades, in application code. Resolve the package’s contract or service through Laravel’s container and bind it in a dedicated application service provider. Keep facades at the edges (controllers, commands) so the integration remains testable and replaceable.
• Keep package configuration environment-backed. Publish the config file, reference env() only inside config/*.php, and cache configuration in deployment. This is especially important after upgrading because stale cached config can make a successful install appear broken.
• Use Laravel’s fake/test utilities around package boundaries. If the package dispatches events, jobs, or HTTP calls, use Event::fake(), Bus::fake(), and Http::fake() in tests. Assert that your application dispatches the expected package interaction rather than testing the package internals.
• Queue long-running package work. If the package exposes jobs or slow operations, route them through queues with explicit retry and timeout settings. This keeps the Laravel 10 upgrade path predictable and avoids request-level timeouts.
• Upgrade Laravel and the package in the right order. For Laravel 8 applications, upgrade the framework and PHP runtime to 8.1/8.2 first, then move the package to ^10.2. Run the full application test suite between steps and use composer update --with-all-dependencies when resolving the package upgrade.
• Pin the CI matrix to the supported runtime. Test PHP 8.1 and 8.2 with Laravel 10. Do not add PHP 8.3 to the matrix until the package explicitly supports it. Consider setting config.platform.php in composer.json so dependency resolution matches production even when developers run a newer local PHP.
• Check package extension points before subclassing. Prefer documented drivers, manager extend methods, events, or config-driven customization. If none exist, wrap the package behind your own interface rather than inheriting from internals.

Gotchas and Tips

• The PHP lock is a real constraint. “Locked to PHP 8.1 and 8.2” likely means PHP 8.3 is unsupported or blocked by Composer. A developer on PHP 8.3 may see resolution failures that do not reproduce in CI. Pin the platform PHP and document the supported runtime.
• Dropping Laravel 8 is a breaking ecosystem change. Audit transitive dependencies, not just the root package. Use composer why-not vendor/package 10.2.0 and review composer.lock after upgrading. A package can claim Laravel 10 support while an add-on still constrains the framework.
• Do not assume composer update will move you to 10.2.0. Existing constraints may hold the old version. Require the new constraint explicitly and confirm the installed version with composer show vendor/package.
• Clear config cache after publishing or upgrading. Use php artisan config:clear locally and rebuild with php artisan config:cache in deployment. Many “package not working after upgrade” issues are stale cached configuration or auto-discovery metadata.
• Verify service provider discovery. If the package relies on Laravel package discovery, run php artisan package:discover after installation. If discovery is disabled, register the provider manually.
• Debug binding failures at the container level. Use php artisan tinker to check app()->bound(...), inspect the provider’s bindings, and review storage/logs/laravel.log. A missing binding often surfaces as a confusing facade or dependency-injection error.
• Read the upgrade guide, not just the release notes. The notes are sparse. Check the package changelog and upgrade documentation for configuration renames, migration changes, or behavioral differences that may accompany the Laravel 10 compatibility work.
• Keep monorepos in lockstep. If multiple applications share the package, upgrade PHP, Laravel, and the package together. Mixing Laravel 8 and 10 services against the same package version will create inconsistent behavior and dependency conflicts.