Goaop Laravel Bridge Laravel Package

Getting Started

• Install with composer require at ^1.1.1 if you are on Laravel 8.0. Earlier 1.x releases do not include the Laravel 8 compatibility work from PR #16, so pinning below 1.1.1 on an L8 app is the first trap to avoid.
• Run php artisan package:discover (or composer dump-autoload) after install so any auto-discovered service provider and facade aliases are registered. If the package is not auto-discovered, add the provider to config/app.php.
• Look first at the package README and composer show <vendor/package> for the supported Laravel/PHP matrix, then at any publishable config or migrations (php artisan vendor:publish --provider=...). Publish before you start wiring it into application code so you are working against the real defaults rather than guessing.
• First use case: take the smallest documented call the package exposes, invoke it from a single controller action or artisan command, and assert the result in a feature test. That confirms the provider is booted, config is loaded, and credentials/connections are correct before you spread usage across the codebase.

Implementation Patterns

• Constructor injection over facades. Resolve the package's client/manager through the container in constructors or via method injection. This keeps it swappable in tests and avoids static coupling to facade aliases that may change between versions.
• Wrap it in a thin application service. Put the package calls behind one or two of your own classes (App\Services\...) and let the rest of the app depend on those. When the package changes API or you need to swap it, you edit one file instead of every controller and job.
• Config-driven setup. Keep keys, endpoints, credentials, and timeouts in config/ and .env, never inline. Use config('package.key') with a sensible fallback, and cache config in production only after verifying the values resolve correctly.
• Queue anything slow or remote. If the package makes network calls or does heavy processing, dispatch a job rather than calling it in the request cycle. This also gives you retries and backoff for free, which matters more than the package's own error handling.
• Test with fakes/mocks at the boundary. Bind a fake implementation of your wrapper service in the test container, or use the package's own fake if it ships one. Keep one small integration test that hits the real client so you notice breaking changes on upgrade.
• Use events/listeners for side effects. If the package emits events, hook your own listeners rather than editing vendor code or subclassing internals. If it does not, fire your own event from the wrapper service after a successful call.
• Upgrade workflow. Bump the constraint, run composer update <vendor/package>, then php artisan config:clear && php artisan cache:clear, run the test suite, and check the changelog for the intermediate versions you skipped — 1.1.1 is a compatibility release, so treat 1.1.0 → 1.1.1 as low risk but still re-run tests on L8.

Gotchas and Tips

• Laravel 8 support starts at 1.1.1. If composer.json allows ^1.0, a fresh install on an L8 app may resolve to a version without PR #16. Constrain to ^1.1.1 explicitly and commit the lockfile.
• Stale caches after upgrade. config:cache and route:cache will hold old values. Always php artisan optimize:clear after a version bump, and remember package:discover needs to re-run if the provider list changed.
• Publish tags are version-sensitive. Re-publish config with --force only after diffing; a new minor version may add keys that your old published config does not have, and missing keys often fail silently with null rather than throwing.
• PHP version is the usual hidden constraint. Laravel 8 support does not imply PHP 8 support. Check the package's composer.json require block against your runtime before upgrading the framework.
• Facade aliases and auto-discovery. If you see "class not found" on a facade, it is almost always a missing package:discover or a manually registered provider in a legacy app. Check bootstrap/cache/packages.php.
• Debugging order: confirm the provider is registered (php artisan about), confirm config resolves (php artisan tinker → config(...)), then confirm the call works in isolation before blaming your integration. Log the package's exceptions at the wrapper boundary so failures are attributable.
• Extension points: prefer the package's published config and events over subclassing. If you must extend, bind your subclass in a service provider rather than editing vendor files, and note it in the upgrade checklist so the override is re-verified each release.
• Watch the issue tracker for the L8 compatibility PR follow-ups. Compatibility releases frequently surface edge cases (serialization, container resolution, deprecated helpers) in the weeks after publication.