Laravelresources Laravel Package

Getting Started

• Install the Laravel 10-compatible line explicitly:

  composer require <vendor>/<package>:^3.0
  

  Confirm composer.json accepts laravel/framework:^10.0 and PHP ^8.1 before upgrading an existing app.
• Read README.md, CHANGELOG.md, and any UPGRADE.md first. For v3.0.0, focus on Laravel 10 support and any major-version breaking changes, renamed config keys, or dropped Laravel/PHP versions.
• Publish package assets only if the package provides them:

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

• First use case: wire the package into one narrow path—a single controller, job, or artisan command—before rolling it across the app. Resolve it from the container rather than calling static helpers directly.
• If the package ships a facade or helper, use it only at the edges of your application. Prefer constructor injection in services, actions, and jobs so the integration stays testable.

Implementation Patterns

• Container-first integration: bind the package contract or client in a service provider and inject it into your own action/service classes. This keeps package calls isolated and makes it easy to swap or fake them in tests.
• Config-driven setup: keep package-specific settings in config/<package>.php and reference them through config(). Avoid scattering credentials or driver names through application code.
• Queue and event integration: if the package dispatches events or supports queued work, listen for its events in your own listeners and restart queue workers after deployment. Treat package events as integration boundaries, not as your domain model.
• Feature-scoped rollout: introduce the package behind a service class or interface first. That gives you one place to change behavior if v3.0.0 requires adjustments after deployment.
• Testing pattern: use the package’s fake/mock if provided; otherwise bind a test double for its contract in the container. Assert your application behavior, not the package’s internals.
• Artisan and scheduling: if the package exposes commands or scheduled tasks, register them through Laravel’s scheduler and run them manually once in staging before enabling them in production.
• Upgrade workflow: create a branch, update the constraint to ^3.0, run composer update <vendor>/<package>, then run php artisan config:clear, php artisan cache:clear, and your test suite. Diff published config and migration files against the new vendor defaults.

Gotchas and Tips

• Major-version upgrade risk: v3.0.0 is a major release. Confirm whether Laravel 9 and older are still supported; if not, apps on older Laravel versions should stay on v2 until they upgrade Laravel first.
• PHP and Laravel constraints: Laravel 10 requires PHP 8.1+. Use composer why-not <vendor>/<package> 3.0.0 to diagnose constraint conflicts instead of forcing an update.
• Stale caches: after upgrading, run php artisan config:clear, php artisan route:clear, php artisan view:clear, and composer dump-autoload. Package discovery issues are often fixed by php artisan package:discover.
• Published file drift: if you previously published config or migrations, re-publish into a temporary directory and diff. Do not blindly overwrite production config.
• Queue workers: restart workers after deploying a new major version. Long-running workers can hold old package code and stale config in memory.
• Auto-discovery assumptions: verify the service provider is still auto-discovered in v3. If the package changed provider names or registration behavior, add it explicitly to config/app.php.
• Facade/helper overuse: facades are convenient for quick scripts, but constructor injection makes package upgrades and tests much easier to manage.
• Extension points: look for custom drivers, macros, events, or bindings in the package’s service provider. Those are usually safer customization points than subclassing internal classes.
• Debugging: start with php artisan about, composer show <vendor>/<package>, and the package’s log channel. If behavior differs between local and production, compare published config, environment variables, and cached config first.