With Join Laravel Package

Getting Started

• Confirm requirements first. Version 2.0.0 targets Laravel 5.5, which means PHP 7.0+ and the 5.5 package-discovery mechanism. Check composer.json for the exact illuminate/* constraints before upgrading an existing app.
• Install with Composer: composer require vendor/package:^2.0. On Laravel 5.5 the service provider and facade should be auto-discovered via the package’s extra.laravel block — no manual edits to config/app.php are required.
• Publish configuration: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Prefer the package’s tag if one is documented (e.g. --tag=package-config) to avoid publishing unrelated assets.
• Where to look first: the package README, the published config/package.php, and the service provider’s register()/boot() methods. These tell you which bindings, facades, and extension points are available.
• First use case: put credentials or environment-specific settings in .env, reference them from the published config file, then resolve the package’s main service from the container (constructor injection) or call its facade in php artisan tinker. That gives you a fast feedback loop before wiring it into application code.

Implementation Patterns

• Prefer container resolution over facades in application code. Inject the package’s contract/class into controllers, jobs, and services. This keeps your code testable and makes it trivial to swap the binding in tests.
• Use the facade for throwaway/scripting work. Facades are convenient in Tinker, Artisan commands, and quick prototypes, but constructor injection is the better default for long-lived code.
• Keep config in version control, secrets in .env. Publish the config once, commit it, and drive environment differences through env() calls inside the config file. Never call env() outside config if you plan to run config:cache.
• Queue-safe usage. If you pass the package’s service into a queued job, don’t serialize the resolved object. Inject the contract and let the container resolve it in handle(), or re-resolve explicitly.
• Testing pattern. In feature/unit tests, bind a fake implementation into the container ($this->app->instance(Contract::class, $fake)) or use Facade::shouldReceive(...). Reset facade mocks between tests.
• Integration tips. If the package dispatches events or exposes hooks, prefer listening to those over subclassing internals. For multi-tenant or multi-connection apps, confirm whether the package reads config at boot or per-call — per-call is safer when config changes at runtime.
• Upgrade workflow for 2.0.0. Bump the constraint, run composer update vendor/package, then:
  1. Remove any manually registered provider/alias entries in config/app.php that are now auto-discovered (duplicate registration causes confusing double-boot behaviour).
  2. Republish the config and diff it against your existing version; merge new keys rather than overwriting wholesale.
  3. Run php artisan config:clear and php artisan package:discover before testing.

Gotchas and Tips

• Breaking change: Laravel <5.5 is no longer supported. The 2.0 major bump reflects a raised framework floor. If you’re on 5.4 or earlier, stay on the 1.x line; don’t force the constraint.
• Auto-discovery can surprise you. If you previously registered the provider manually, 5.5 will now discover it as well. Check bootstrap/cache/packages.php (or run php artisan package:discover) to confirm what’s registered, and remove duplicates.
• Config caching quirks. After publishing or editing the config, run php artisan config:cache in production. Any env() call outside config/ returns null once cached — a common source of “works locally, breaks in prod”.
• Publishing overwrites. vendor:publish can clobber customised config/views. Use --force deliberately, and keep your changes in a diff or separate override file where the package supports it.
• Debugging checklist: verify the provider is discovered (package:discover), confirm the config file exists under config/, check for stale caches (config:clear, cache:clear), and inspect the container binding with app()->bound(...) in Tinker.
• Extension points: bind your own implementation to the package’s contract in a service provider rather than editing vendor files; use the facade’s extend/swap where provided. Publishable migrations/views should be published and customised locally.
• Pin the major version. Use ^2.0 in composer.json and review the changelog before minor upgrades — packages that bump majors for framework support often bundle behavioural changes alongside.