- How do I install the BatteryIncluded PHP SDK in a Laravel project?
- Run `composer require batteryincluded/batteryincluded-php-sdk` in your project directory. Ensure your Laravel app uses PHP 8.2+ (Laravel 10+). The SDK will be autoloaded via Composer’s PSR-4 standard.
- Can I use this SDK with Laravel’s HTTP client instead of CurlHttpClient?
- Yes. Replace the `CurlHttpClient` with Laravel’s built-in GuzzleHttp or Symfony HTTP Client by binding a custom adapter in your service provider. The SDK’s `ApiClient` is designed to accept any PSR-18 compliant client.
- What Laravel versions are compatible with this SDK?
- The SDK requires PHP 8.2+, which aligns with Laravel 10+. For Laravel 9.x, you’ll need to manually upgrade PHP or use a polyfill, though some features (like enums) may require adjustments.
- How do I extend ProductBaseDto to add custom fields like ‘keywords’ or ‘material’?
- Create a subclass of `ProductBaseDto`, add your custom properties, and override `jsonSerialize()` to merge them into the parent payload. Use `array_merge_recursive` to preserve base fields and `array_filter` to exclude null values.
- Does the SDK support real-time syncs via webhooks, or should I use Laravel queues?
- BatteryIncluded’s API does not natively support webhooks, so Laravel’s queue system (`syncFullElements()` or `syncElement()`) is recommended. Trigger syncs via model events (e.g., `ModelSaved`) or cron jobs for periodic updates.
- How should I handle API authentication in Laravel?
- Store your API key in `.env` (e.g., `BATTERYINCLUDED_API_KEY`) and bind it in `config/services.php`. The SDK’s `ApiClient` will automatically inject it. Avoid hardcoding credentials in your service provider.
- What’s the best way to test this SDK in Laravel?
- Use Laravel’s Mockery to mock `ApiClient` in unit tests. For integration tests, stub HTTP responses with `Http::fake()` and verify DTO serialization. The SDK lacks built-in tests, so focus on edge cases like null fields or API errors.
- How do I handle rate limits or failed syncs in production?
- Implement exponential backoff using `spatie/laravel-queue-backend-retries` for retries. Log errors via Laravel’s Monolog and monitor queue jobs. Check BatteryIncluded’s API docs for rate limits (e.g., requests/minute).
- Can I sync multiple document types (e.g., PRODUCT and BLOG) in one collection?
- Yes. The SDK supports mixed-index collections. Use `BrowseService` to query across types. In Laravel, structure your sync logic to batch operations by type (e.g., `syncProducts()` and `syncBlogs()` separately).
- Are there alternatives if I need to switch search providers later?
- The SDK is tightly coupled to BatteryIncluded’s schema (e.g., `_PRODUCT` prefix). To migrate, refactor DTOs and sync logic to match a new provider’s API. Consider abstracting the `ApiClient` interface for easier swaps in Laravel’s service container.