Laravel Theme Laravel Package

Getting Started

Version 1.1.0 is a compatibility release ("Add Support for Laravel 13"), so the first job is confirming the constraint actually widened rather than assuming it did.

1. Install / upgrade

   composer require <vendor>/<package>:"^1.1"
   # or, if already installed
   composer update <vendor>/<package> --with-dependencies
   

2. Confirm the constraint. Open composer.json of the package and check the illuminate/* / laravel/framework requirements now include ^13.0. A release note that says "support for Laravel 13" without a widened constraint is a red flag — verify before you plan an upgrade.
3. Check the framework floor it implies. Laravel 13 raises the PHP floor, so confirm your runtime, CI matrix, and any other pinned dependencies match before bumping.
4. Publish config (once):

   php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
   

5. Where to look first: the published config file for defaults/toggles, the package's service provider for container bindings (that's your real API surface), and the README quickstart for the canonical first call.

First use case: wire the package into one existing route or artisan command — not a new feature — and exercise it via php artisan tinker or a single feature test. That isolates upgrade breakage from new-code breakage, which matters on a framework-major release.

Implementation Patterns

• Resolve from the container, never new. Inject the package's contract/class into constructors, or use its facade in a controller. This is what lets you swap in fakes and what keeps you insulated from constructor signature changes across minor releases.
• Bind behind your own interface. Wrap the package in a thin adapter (App\Contracts\Thing → package implementation registered in a service provider). For a package whose only 1.x signal is framework compatibility, this is your cheapest insurance against the next major.
• Config over code. Anything the package exposes as config (timeouts, drivers, credentials, feature flags) belongs in config/<package>.php with env() reads — not hardcoded at the call site. Keep .env.example in sync.
• Upgrade workflow:

  composer update <vendor>/<package> --with-dependencies
  php artisan config:clear && php artisan cache:clear
  php artisan test
  

  Run the full suite plus composer outdated --direct to catch transitive constraint conflicts the resolver papered over.
• Test with fakes, not the network. Use Http::fake(), Bus::fake(), or the package's own fake if it ships one; assert on the interaction rather than the payload shape.
• Queue long work. If the package performs I/O, dispatch a job that calls it rather than calling it inline in a request — you get retries and visibility for free.

Gotchas and Tips

• Stale config cache is the #1 "it doesn't work after upgrade" cause. php artisan config:clear before debugging anything else.
• Auto-discovery can mask registration problems. If bindings look missing, check bootstrap/cache/packages.php and run php artisan package:discover.
• Read the diff, not just the note. "Add Support for Laravel 13" is one line; the actual changes are in the constraint and possibly in test matrix only. Diff composer.json between 1.0.x and 1.1.0 — that tells you whether this is a no-op for your current Laravel 12 app.
• CI matrix: add a laravel: 13.* job alongside your existing one before dropping the old one; run both for at least one release cycle.
• Deprecations surface as warnings, not failures. Run the suite with --display-warnings (or check storage/logs/laravel.log) after the bump so you catch framework deprecations early.
• Extension points: publishable config, container bindings in the service provider, and (if offered) macros on the facade. Never edit vendor/ — a patched vendor file is invisible until the next composer update wipes it.
• Pin and commit composer.lock for the app; deploy with composer install --no-dev --optimize-autoloader, and run php artisan optimize post-deploy so config/route caches match the new version.
• Debugging: php artisan about for framework/runtime context, Telescope for the actual call path, and Log::debug() at the adapter boundary to see what crosses into the package.