Wixet Recaptcha Bundle Laravel Package

Getting Started

This is the package's first stable release (v1.1) — there is no prior assessment, no migration path, no deprecations, and no known bugs. That is the whole of the release signal, so treat v1.1 as a reasonable starting point rather than a battle-tested dependency.

Minimal steps:

1. composer require the package and pin it ("^1.1") rather than tracking dev-main.
2. Read, in this order: the package's composer.json (for extra.laravel.providers / auto-discovery), its service provider (what it binds, registers, publishes, and schedules), and its config file defaults.
3. Publish anything it ships (vendor:publish --provider=... or --tag=...) and read the published config top to bottom — that is usually the most accurate documentation a young package has.
4. Clear caches after install: php artisan config:clear && php artisan cache:clear (and package:discover if the provider doesn't appear).

First use case: wire it into one code path — a single controller action, artisan command, or queued job — in a local environment with APP_DEBUG=true, and verify the happy path plus one failure path before touching anything else in the app.

Implementation Patterns

• Resolve from the container, don't new it. Constructor-inject the package's entry point (or app() it) so config, test doubles, and container overrides actually apply. Instantiating directly bypasses everything the service provider set up.
• Wrap it in a thin adapter. Put the package behind your own small service class or interface (App\Contracts\...). Day-to-day you call your adapter; if the package's API shifts during the 1.x series, one file changes instead of every call site.
• Incremental rollout. Integrate one feature path, run it in staging for a release cycle, then broaden. Feature-flag or config-gate the integration so it can be switched off without a deploy.
• Config over code. All environment-specifics (drivers, credentials, endpoints, timeouts) belong in config/*.php reading from .env. Never hardcode values the package lets you configure.
• Testing. Bind a fake/mock of the package's interface in your test case's setUp() (or use the package's own fake() helper if it ships one). Assert your adapter's behaviour, not the vendor's internals — that keeps your suite green across package patch releases.
• Queues and console. Auto-discovery covers HTTP requests, but check whether the provider registers console commands, schedules, or queue listeners conditionally. If you use the package inside a job, confirm it works under queue:work, not just in a request.
• Upgrades. Keep a short changelog watch for the 1.x line: composer outdated in CI, then read the diff before bumping. With no known bugs reported so far, the risk in 1.x is newly introduced regressions, not existing ones.

Gotchas and Tips

• "First stable" is not "settled." A 1.0/1.1 with little field history has had far less production exposure than a mature package. Pin exactly, and have a rollback path (lockfile revert + composer install) ready.
• "No known bugs" ≠ "no bugs." It means nobody has reported them yet. Add logging around the integration point and watch your log channel for the first week after rollout.
• Config cache traps. After editing published config, run php artisan config:clear. Note that once you've published a config file, upgrades will not update it — diff the package's config against yours on each minor bump, or you'll silently miss new options with safe defaults.
• Auto-discovery failures. If the package's bindings aren't resolving, check bootstrap/cache/packages.php exists and lists it; if not, php artisan package:discover, and confirm the provider is in composer.json extra.laravel.providers or config/app.php.
• Published assets drift. Views, migrations, and config you publish are yours forever. Prefer overriding via the package's documented extension points (events, interfaces, config keys) over editing published files, which makes future upgrades a merge problem.
• Debugging. Start with dd()/dump() at the boundary between your code and the package, then drop to Telescope or a dedicated log channel. If the package swallows exceptions internally, temporarily raise its log level in config rather than patching vendor code.
• Extension points to look for first: container bindings for interfaces (swap implementations), events fired by the package (hook without forking), and Macroable traits (extend without subclassing). Use these before reaching for a fork — you'll want to keep taking upstream patches.