Ad Search Bundle Laravel Package

Getting Started

• Install the current patch release: composer require vendor/package:^6.0. v6.0.1 is the latest 6.x patch and is the version to target for new work.
• Confirm framework compatibility. “Symfony 7 support” means Laravel 11+ is fully supported. Laravel 10 apps (Symfony 6.4 components) should still resolve if the package keeps a multi-version constraint, but verify with composer why-not vendor/package 6.0.1 if Composer reports conflicts.
• Publish any package config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag="config". Read config/package.php first — it usually reveals drivers, encoding options, credentials, and defaults.
• First use case: resolve the package’s main service from the container in a controller, artisan command, or queued job, pass a representative payload, and call its primary method. Assert the result in a feature test before wiring it into production code.
• Where to look first: the README “Quick Start”, the package service provider (bindings, aliases, singleton/scoped registration), and composer show vendor/package to confirm the installed version and Symfony component versions.

Implementation Patterns

• Prefer constructor injection over facades in application code. Type-hint the package contract or client in your own service classes so tests can swap implementations through the container.
• Wrap package calls in a thin application service (e.g. App\Services\PackageGateway). Normalize inputs, handle encoding, and map package exceptions to your domain exceptions there instead of scattering package-specific code across controllers.
• For I/O-heavy work (HTTP calls, file generation, exports), call the package inside a queued job. Set $timeout, $tries, and $backoff based on the package’s own retry behavior, and use ShouldBeUnique or rate limiting when the package talks to external services.
• Keep environment-specific settings in .env and map them through config/package.php. Cache config in production with php artisan config:cache, but clear it after changing package-related environment variables.
• In tests, fake the surrounding Laravel services (Http::fake(), Storage::fake(), Queue::fake()) and assert on the package’s public result objects rather than internal state. Freeze time with Carbon::setTestNow() when output depends on timestamps.
• In Laravel Octane, register the package client as scoped rather than singleton unless you have confirmed it is stateless. Stateful clients can leak request data between workers.

Gotchas and Tips

• Symfony 7 compatibility: v6.0.1 adds Symfony 7 support, which aligns with Laravel 11. If you are still on Laravel 10, check whether the package’s constraint allows Symfony 6.4 before upgrading. Run composer why-not vendor/package 6.0.1 to diagnose lock-file conflicts.
• utf8_encode removal: The package no longer calls the deprecated utf8_encode. If you previously relied on the package to transcode ISO-8859-1 input to UTF-8, that implicit conversion may no longer happen. Convert explicitly before passing data in: mb_convert_encoding($value, 'UTF-8', 'ISO-8859-1'). This is the most likely behavior change in this patch release.
• Deprecation warnings: Upgrading should remove utf8_encode deprecation notices originating from this package on PHP 8.2+. If warnings persist, another dependency is calling it; use composer why or a static-analysis pass to locate the caller.
• Config cache quirks: After php artisan config:cache, .env changes are ignored until php artisan config:clear. Services that call env() at runtime instead of reading from config files will behave inconsistently between local and cached production environments.
• Debugging: Resolve the package service in php artisan tinker and inspect the returned object. Wrap calls in try/catch and log the package exception with context. For encoding issues, mb_check_encoding() and bin2hex() are faster than visually inspecting strings.
• Extension points: Look for manager/driver patterns, container bindings in the service provider, and config 'driver' keys. Prefer extending through published config and container bindings over editing vendor code. If the package dispatches events, listen to them for logging and metrics instead of forking.
• Version pinning: v6.0.1 is a patch release and should be safe for most 6.x users, but pin ^6.0 in composer.json and review future 6.x changelogs. Run your test suite and a staging smoke test after upgrading, especially if you process non-UTF-8 input.