Laravel Docweaver Laravel Package

Getting Started

v5.1.0 is a compatibility release, so "getting started" is really "getting started on the right Laravel version".

1. Check your framework version first. This release requires Laravel 9 or 10. On Laravel 8 you are pinned to the 5.0.x line — do not attempt composer require until you have upgraded the framework or you will burn time on resolver errors that have nothing to do with the package.
2. Read the upgrade guide / CHANGELOG before the README. For a major-line package the changelog tells you which public API moved; the README quick-start assumes a clean install and won't warn you about removals.
3. Install into a scratch app, not your product.

   composer require vendor/package:^5.1
   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Confirm the service provider is auto-discovered (extra.laravel.providers in the package's composer.json) — if it isn't, that is your first integration task, and it is the most common reason "the package does nothing" on a fresh install.
4. First use case: exercise the package's happy path end-to-end on a stock Laravel 10 skeleton with default config, before wiring it into application code. If it works there and fails in your app, the problem is your app (config cache, stale container binding, conflicting provider).

Implementation Patterns

Constraint strategy. Depend on ^5.1 rather than a patch pin, and mirror the package's own framework constraint in your composer.json (laravel/framework: ^9.0|^10.0). Keeping the two aligned means Composer can resolve the whole graph in one pass instead of backtracking.

Upgrade as an isolated PR. Do the framework bump and the package bump in a single branch, but as two commits: composer update laravel/framework --with-dependencies, then composer require vendor/package:^5.1. If tests go red you need to know which commit did it.

Test against the matrix, not just your app. If you maintain anything downstream of this package, use orchestra/testbench with a matching major (^8 for Laravel 10, ^7 for Laravel 9) and run a CI matrix of laravel: [9.*, 10.*] × php: [8.1, 8.2]. The Laravel 8 drop is exactly the kind of change that silently breaks a package you own if you only test on your own app's version.

Bind, don't facade, in application code. Resolve the package's contract from the container in constructors and inject it. Facade calls are fine in controllers and Blade, but constructor injection is what lets you swap in a fake in tests and is what survives the package renaming its facade alias.

Config is code — publish and commit it. Publish the config file once, commit it, and read every value through config() at the point of use rather than at boot. That keeps you compatible when the package adds a new key with a default in a minor release.

Multi-package upgrade ordering. Framework → this package → your own packages that depend on it → application tests. Upgrading leaf packages first is how you end up debugging a half-migrated dependency graph.

Gotchas and Tips

The Laravel 8 drop is the only breaking change here, and it surfaces as a resolver error, not a runtime error. Expect Conclusion: don't install laravel/framework v8.x or vendor/package 5.1.0 requires laravel/framework ^9.0|^10.0. Diagnose with:

composer why-not vendor/package 5.1.0
composer why laravel/framework

The first command names the exact blocking constraint; the second tells you who else is holding the framework back.

PHP floor moves to 8.1. Check your CI images, Dockerfiles, and any platform.php override in composer.json — a stale "platform": {"php": "8.0"} will make Composer resolve as if you were still on 8.0 and quietly refuse the upgrade.

Clear caches after upgrading, every time. php artisan config:clear && php artisan cache:clear && composer dump-autoload. A cached config or a stale compiled service manifest is the number-one cause of "I upgraded and the package's new behaviour isn't there". In production, ship config:cache as an explicit deploy step, not an implicit one.

Illuminate API drift is where the real breakage hides. Code written against Laravel 8 idioms (Str:: helpers since deprecated, older Http client signatures, removed *able traits) may still run on 9 but behaves differently on 10. Grep for the package's touched facades and helpers, and run deprecation-tolerant test runs (phpunit --display-deprecations) so you see the warnings before they become removals.

Extension points to reach for before forking: the published config file, container bindings for the package's interfaces, and macros on its facades. If you find yourself subclassing a concrete package class, check the changelog for a contract first — concrete classes are the least stable surface across a major line.

Watch indirect dependencies. A transitive dependency still declaring laravel/framework: ^8.0|^9.0 will block you from 10 regardless of what this package allows. composer update --with-dependencies on a branch, and read the full resolution output rather than the summary line.