- How do I install batteryincluded/batteryincluded-php-sdk in a Laravel project?
- Install it with Composer by running composer require batteryincluded/batteryincluded-php-sdk. The package requires PHP 8.2 or higher, so confirm your server and local environment meet that before installing. There is no Laravel auto-discovery or bundled service provider, so you register the SDK's ApiClient and SyncService yourself in a service provider. Example usage for each implemented API action is included in the package's examples directory.
- Which Laravel and PHP versions are supported by the BatteryIncluded PHP SDK?
- The SDK requires PHP 8.2 or higher, which Composer enforces at install time. Laravel 10 and Laravel 11 both run on PHP 8.2, so they work out of the box, and because the SDK is framework-agnostic it can be used in any Laravel version running on a supported PHP release. Projects still on PHP 8.1 or older need to upgrade PHP before adding the package.
- How do I sync custom shop-specific product fields like keywords or material?
- Extend BatteryIncludedSdk\Dto\ProductBaseDto in your own class, add the extra properties, and override jsonSerialize(). Inside jsonSerialize(), build an array of your custom fields, strip nulls with array_filter, and merge it into the parent payload under the key '_' . $this->getType() (for products that means the _PRODUCT key). Use array_merge_recursive so the base fields such as name, ordernumber, price, and instock are preserved. Fields left as null are not sent, so only populated values reach the API.
- How do I configure API credentials and the collection for the SDK in Laravel?
- The SDK does not ship a Laravel config file, so the common approach is to add a batteryincluded entry to config/services.php with your API URL, collection name, and API key read from environment variables. The SDK README points to the official Postman API documentation for the exact authentication scheme and available endpoints. Keep the credentials out of version control and resolve them through config() when binding the client in your service provider.
- Can I sync products and blog posts into the same BatteryIncluded collection?
- Yes. The SDK is built around mixed-index collections, so you can push different document types such as PRODUCT and BLOG into a single collection, each typed and prefixed accordingly (for example the _PRODUCT key on product payloads). This is useful when a Laravel app combines an e-commerce catalog with CMS content and you want one unified search across both. The BrowseService then queries across those document types in the same collection.
- How do I bind ApiClient and SyncService in Laravel's service container?
- Create a service provider and bind SyncService (and the underlying ApiClient) in the register method using a closure that instantiates CurlHttpClient with your configured API URL and credentials. Because the bindings are resolved through the container, controllers, jobs, and console commands can type-hint SyncService and receive a configured instance automatically. Pull all settings from config/services.php rather than calling env() directly outside config files.
- How should I run product syncs asynchronously to avoid API rate limits?
- Dispatch a queued job from Eloquent model events such as created and updated so syncing never blocks the request. Inside the job, use the SDK's batch method (syncFullElements) to send multiple documents per request instead of one call per record, and keep batches modest on lower pricing tiers. Run the worker with queue:work and add retry and backoff settings so transient rate-limit or network errors are retried rather than lost.
- Does the SDK ship tests, and how do I mock it in PHPUnit?
- The README documents example scripts rather than a bundled test suite, so treat the SDK as a third-party dependency in your own tests. Wrap SyncService and ApiClient behind your own interface and bind a fake implementation in the container for feature tests. For unit tests, Mockery can mock ApiClient directly, and because HTTP traffic goes through CurlHttpClient you can substitute a stub client that records requests without hitting the BatteryIncluded API.
- Can I replace CurlHttpClient with Laravel's Guzzle HTTP client?
- Yes. The SDK abstracts HTTP behind a client contract, so you can write an adapter around Laravel's HTTP client (Guzzle) or Symfony HttpClient and inject it instead of the default CurlHttpClient. This gives you Laravel-native features such as retries, timeouts, middleware, and HTTP fakes in tests. The refactor is small because the DTO and sync layers do not depend on cURL directly.
- What are the vendor lock-in risks of using the BatteryIncluded SDK?
- The DTOs and payload structure are tightly coupled to BatteryIncluded's schema, including typed document prefixes such as _PRODUCT, so moving to another search backend means rewriting your serialization and sync logic. To limit that risk, keep your Eloquent-to-DTO mapping in a dedicated class rather than scattering it through controllers and jobs. That way you can swap the sync implementation for an alternative like Meilisearch, Algolia, or Typesense without touching your application code.