Laravel Repository Laravel Package

Getting Started

• Verify your platform: Laravel 10.x requires PHP 8.1+. Confirm with php -v and check composer.json for the framework constraint.
• Install the release with an explicit constraint so you get the Laravel 10-compatible version:

  composer require vendor/package:^1.0
  

  Replace vendor/package with the actual Composer name.
• Let Laravel auto-discovery register the service provider. Confirm it was discovered:

  php artisan package:discover
  php artisan about
  

• Publish any package config or assets if the package provides them:

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

• Where to look first:
  1. The package README and changelog.
  2. composer.json inside the package for illuminate/* and PHP constraints.
  3. The service provider’s register() and boot() methods.
  4. The published config file and any bound interfaces.
• First use case: resolve the package’s main entry point from the container in a throwaway environment and run a safe smoke test before integrating it into application code:

  php artisan tinker
  >>> app(\Vendor\Package\MainClass::class);
  

  Then try the smallest documented operation, preferably a read-only call or a test double, and only afterwards wire it into a controller, command, or job.

Implementation Patterns

• Inject, don’t resolve globally. Type-hint the package’s main class or interface in controllers, jobs, commands, and services. Keep app() and facades out of domain code where possible.
• Keep configuration in config and environment. Publish the package config, commit safe defaults, and keep credentials or environment-specific values in .env. Avoid hard-coding package options in application code.
• Wrap the package behind your own adapter. Create a small application-level service that delegates to the package. This makes it easier to fake in tests, swap implementations later, and isolate package-specific types from your domain.
• Use it in queued work for slow or remote operations. If the package performs HTTP calls, file operations, or external synchronization, call it from a job rather than directly in a request. For long-lived workers and Laravel Octane, prefer scoped() bindings over singletons if the package holds request state.
• Test with container fakes. Bind a mock or fake implementation of the package interface in your test container. If the package uses Laravel’s HTTP client, combine your fake with Http::fake() and assert the expected outgoing requests.
• Upgrade deliberately. After changing the package version:

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

  Run the full application test suite, not only package-specific tests.
• Use Laravel 10 conventions. Constructor property promotion, typed properties, and first-class container bindings work well with a package that explicitly supports Laravel 10.x. Prefer framework-native integration points over custom bootstrapping.

Gotchas and Tips

• Laravel 10 compatibility is the headline change in v1.0.6. If you are still on Laravel 9 or lower, verify the package’s illuminate/* constraint before upgrading. Use:

  composer why-not vendor/package 1.0.6
  

  to diagnose version conflicts.
• PHP 8.1+ is mandatory for Laravel 10. The most common installation failure is a platform mismatch, especially in CI or Docker images still pinned to PHP 8.0.
• Auto-discovery can be disabled. If the package’s classes are not found, check extra.laravel.dont-discover in the root composer.json and confirm the provider is registered manually in config/app.php if needed.
• Config caching hides changes. After editing package config, run php artisan config:clear locally and php artisan config:cache in production. A stale cached config is a frequent source of “why is this option ignored?” debugging.
• Singletons and long-lived workers. If the package binds a singleton that accumulates state, it can leak across requests under Octane or across jobs in a queue worker. Prefer scoped() bindings or reset the instance in a listener.
• Debug container resolution early. Use app()->bound(...), php artisan tinker, and the exception page to confirm which implementation is being resolved. Check storage/logs/laravel.log for package-emitted errors.
• Prefer extension points over vendor edits. Use published config, bound interfaces, events/listeners, and macros where available. Never edit files under vendor/; changes will be lost on the next composer update.
• Treat v1.0.x as early-stage. Pin to ^1.0, read the changelog before each minor release, and keep a smoke test around the package’s primary operation so regressions are caught quickly.