Routmoute Sirene Bundle Laravel Package

Getting Started

• Install with composer require routmoute/sirene-bundle. Note the name: this is a Symfony bundle, not a native Laravel package — there is no config/app.php service provider or config/sirene.php publish step you can rely on. Expect to instantiate the underlying client yourself.
• First place to look: the bundle's DependencyInjection/ and Resources/config/services.* files to see which services (HTTP client, authenticator, Sirene client) it wires up, and SireneClient (or similarly named) for the public API surface. Those are the classes you will call from Laravel.
• Get credentials from the INSEE portal (portail-api.insee.fr): a client_id / client_secret pair and the OAuth token endpoint. The Sirene API is OAuth2-protected, so the bundle typically exchanges these for a bearer token internally.
• Minimal first use case: look up a company by SIREN. Wire the client with your credentials and base URL, call the SIREN lookup method, and dump the hydrated result. That verifies auth, the base URL, and the response mapping in one step.
• Pin ^1.1.1. The API_URL change in this release matters — if you build against 1.1.0's URL or hardcode an endpoint yourself, you will hit the retired INSEE hostname.

Implementation Patterns

• Bind the client in a Laravel service provider. Create a small SireneServiceProvider that builds the client (credentials from config/services.php, HTTP client from Laravel's or Symfony's) and registers it as a singleton. Expose a thin Sirene facade if you want ergonomics closer to Laravel conventions.
• Wrap it behind a repository. Keep the bundle's response objects out of your domain. Map the SIREN/SIRET/NAF data into your own DTOs or Eloquent models so a future swap (or a Symfony-major bump) doesn't ripple through controllers.
• Cache aggressively. INSEE rate limits are tight. Cache successful lookups by SIREN/SIRET in Redis with a TTL measured in days, and cache 404s briefly too so you don't hammer the API on known-missing records. A remember() around the lookup is usually the whole pattern.
• Push lookups into queued jobs. Registration forms and imports should not block on a third-party call. Dispatch a job, store the eventual company data, and let the UI show pending state.
• Bulk import pattern: loop SIRENs, check cache first, batch the misses through a rate-limited queue (Laravel's RateLimited job middleware is a natural fit), and write results back. Track failures separately so one bad SIREN doesn't poison the batch.
• Handle the auth token lifecycle. The bearer token expires; make sure the same client instance is reused (singleton binding) so token refresh happens inside it rather than on every call.

Gotchas and Tips

• v1.1.1 only changes API_URL — but that's not cosmetic. It aligns the package with the current INSEE endpoint. Upgrade promptly; if you pinned 1.1.0 or copied the URL into your own config, you'll see connection errors or 404s against the old host.
• It's a Symfony bundle. Do not expect package discovery or artisan commands. If you try to "just install and use," you'll get a "class not found" or container error. Budget a short wiring step.
• Rate limiting is the #1 debugging surprise. Symptom: sporadic 429s under load that look like flaky auth. Check your request volume before assuming credentials are wrong; add caching and rate limiting before you scale up.
• Token expiry masks as auth failures. A 401 after an hour of success is almost always the token, not the credentials. Verify the authenticator refreshes.
• Non-diffusible companies return partial/redacted data by design (privacy rules). Don't treat missing fields as a bug; handle them explicitly in your mapping.
• SIREN vs SIRET confusion. SIREN = 9-digit legal unit; SIRET = the 14-digit establishment (SIREN + NIC). Pick the right lookup method or you'll get empty results and chase ghosts.
• Extension points: the HTTP client and authenticator are typically injectable. Override them (custom Guzzle/Symfony HttpClient with logging, retries, or a mock) rather than editing the package. For tests, bind a fake client that returns recorded responses — don't hit INSEE in CI.
• Never log credentials or bearer tokens. If you add HTTP logging for debugging, redact the Authorization header.
• Version your base URL, not just the host. INSEE's API is versioned in the path; the 1.1.1 change reflects that. Keep the URL in config so future bumps are a one-line change.