Laravel Genderize Api Client Laravel Package

Getting Started

• Check the version floor first. v13 requires PHP 8.3+ and Laravel 12.61.1+ or 13.x. The framework constraint is ^12.61.1|^13.0, so older Laravel 12 patch releases are excluded for security reasons. If you are on Laravel 10/11 or PHP 8.1/8.2, stay on v12.0.0—but treat that as frozen and deprecated.
• Upgrade the constraint to ^13.0. The package major now tracks the highest supported Laravel major, so ^13.0 is correct for both Laravel 12.x and 13.x applications. Do not assume you need a ^12.x constraint just because your app is on Laravel 12.
• Look at the facade and config first. The auto-discovered alias is now Genderize (previously the package incorrectly registered Woocommerce). Start with the README, then inspect the published config/genderize.php for endpoint, timeout, API key, and locale/country options. If you previously added a manual alias for Woocommerce, remove it.
• First use case: enrich a profile or pick a salutation. Call the facade with a first name and map the genderize.io response fields—gender, probability, and count—into your domain. Guard for gender === null or low count/probability; treat those as “unknown” rather than guessing.
• Run discovery after upgrading. php artisan package:discover and php artisan optimize:clear will refresh the cached manifest so the Genderize alias is picked up.

Implementation Patterns

• Wrap the facade in your own service. Keep Genderize:: calls inside a small GenderResolver/action class rather than sprinkling them through controllers and models. This gives you one place to add caching, retries, and fallbacks, and makes it trivial to swap in a fake for tests.
• Cache aggressively by normalized name. Genderize results are effectively stable for a given name/locale combination, and the public API is rate-limited. Cache on a key like genderize:{lowercased-name}:{country}:{language} with a long TTL, and store the raw probability/count alongside the result.
• Queue bulk enrichment. For imports or backfills, dispatch a job per chunk of names and put a RateLimiter::for('genderize', ...) in front of the API call. Avoid synchronous calls inside loops, model accessors, or Blade templates.
• Store the evidence, not just the label. Persist gender, probability, count, the locale parameters you sent, and a timestamp. This lets you audit decisions and re-evaluate low-confidence results later without re-calling the API.
• Design for “unknown”. Make the gender field nullable and give callers a clear fallback—neutral salutation, no personalization, or a manual-review flag. Do not let an API timeout or a count: 0 response break a registration or checkout flow.
• Test with Http::fake(). Assert your mapping of the genderize.io JSON payload, including the null-gender and low-probability branches. If you inject your own resolver interface, bind a fake implementation in tests instead of hitting the facade.
• Use locale/country parameters where the package exposes them. Names like “Andrea”, “Sasha”, or “Michel” are ambiguous across countries; passing the country/language context materially improves accuracy.

Gotchas and Tips

• Breaking changes in v13 are mostly platform-level. Laravel 10/11 and PHP 8.1/8.2 are removed. Composer may refuse to install older framework versions anyway because of published security advisories, so plan the PHP/Laravel upgrade before bumping this package.
• The facade alias rename is the upgrade step most likely to bite. Woocommerce → Genderize. If your app manually registered the old alias because discovery was broken, delete that registration. If any code still references Woocommerce:: for gender lookups, it will break—and worse, it may have been colliding with a real WooCommerce package alias.
• Clear discovery caches if the alias “doesn’t exist”. After upgrading, stale bootstrap/cache/packages.php or services.php can leave the old alias in place. Run php artisan package:discover and php artisan optimize:clear.
• Don’t infer gender in security- or eligibility-sensitive paths. Genderize returns a binary gender estimate with a probability; it is not suitable for identity verification, legal gender records, or anything with a compliance dimension. Keep it to soft personalization and always allow a neutral fallback.
• Handle 429s and timeouts explicitly. The package is an HTTP client wrapper; network failures will surface as exceptions or nulls depending on your configuration. Set a short timeout, catch failures, log them, and degrade gracefully rather than retrying synchronously.
• Low count is common for non-Western names. A result with count: 1 or probability: 0.52 is not a reliable signal. Set a threshold in your resolver and route everything below it to manual review or “unknown”.
• Contributor-facing tooling moved. Tests now use PHPUnit ^12.5.8 with the 12.5 schema, and PHPStan runs on PHP 8.3. If you fork the package or run its test suite in CI, update phpunit.xml and your CI matrix accordingly; this does not affect normal application usage.
• Versioning is now non-obvious. Because ^13.0 supports both Laravel 12 and 13, a future Laravel 14 release will presumably become ^14.0 and drop Laravel 12. Pin the package major deliberately and watch the release notes rather than assuming the package major matches your app’s Laravel major.