Architect Laravel Package

Getting Started

• Confirm the app meets Laravel 12 requirements: PHP 8.2+ and a Laravel 12 application skeleton.
• Install the package with Composer using the package name from its README, then let Laravel package discovery register the service provider.
• Publish config, migrations, or assets only if the package documentation instructs it:
  • php artisan vendor:publish --provider="Vendor\\Package\\ServiceProvider"
• Look first at:
  • composer.json for illuminate/* and PHP constraints
  • the package README for the primary public API
  • the service provider for bindings, config merges, and publishable resources
  • the config file, if published
• First use case: integrate the package into one small Laravel 12 workflow, such as a controller action, console command, or queued job, then cover it with a feature test. This validates Laravel 12 compatibility and the package’s real integration path before wider adoption.

Implementation Patterns

• Treat 1.0.0 as the Laravel 12 compatibility baseline. Pin it with ^1.0 and run the application test suite before rolling it out.
• Check whether 1.0.0 adds Laravel 12 support while retaining older Laravel versions, or whether it drops older framework support. This determines upgrade sequencing for existing apps.
• Prefer dependency injection over app() resolution in application code. Bind package services in the container where appropriate and keep package usage behind your own service or adapter if the package is used in many places.
• Keep deployment-specific values in environment variables and package behavior in config/*.php. Run php artisan config:cache in CI to catch config issues early.
• Add feature tests that exercise the package through Laravel 12’s HTTP, console, queue, or event layers, not only isolated unit tests.
• If the package dispatches events or jobs, test those flows explicitly. Use Laravel fakes where available and verify queue serialization under Laravel 12.
• For existing applications, upgrade Laravel first, then install or upgrade this package. For new applications, install on a fresh Laravel 12 app and smoke-test the documented primary workflow.

Gotchas and Tips

• The release notes only mention Laravel 12 support. Do not assume new package features or API changes; verify the changelog and README before relying on undocumented behavior.
• Inspect composer.json for Illuminate version constraints. If installation conflicts, use composer why-not vendor/package 1.0.0 to identify the blocking dependency.
• Clear and rebuild Laravel caches after install or upgrade:
  • php artisan optimize:clear
  • php artisan config:cache
  • php artisan route:cache if applicable
• Watch for PHP 8.2+ and Laravel 12 deprecations. Run tests with deprecation reporting enabled so compatibility issues surface before production.
• If config files are published, commit them and review diffs after package upgrades. Published config can drift from package defaults.
• Main extension points are usually service provider bindings, package config, published migrations, and dispatched events. Confirm documented extension points before subclassing or replacing internals.
• Because the release is compatibility-focused, keep the upgrade small: install, run the full test suite, smoke-test one real workflow, then expand usage.