Ai Inflector Laravel Package

Getting Started

frank-l93/ai-inflector is a pre-1.0 Laravel package that wraps word inflection (singular/plural, casing, humanising, slugs) behind an AI-backed driver so that terms Laravel's built-in Str helpers get wrong — brand names, product SKUs, acronyms, non-English loanwords — resolve correctly.

Minimal setup:

composer require frank-l93/ai-inflector

The service provider is auto-discovered. Publish the config and set a driver/credentials before first use:

php artisan vendor:publish --tag="ai-inflector-config"

// config/ai-inflector.php (shape as of v0.1.0)
return [
    'driver' => env('AI_INFLECTOR_DRIVER', 'openai'),
    'cache'  => env('AI_INFLECTOR_CACHE', true),
    // driver-specific credentials/timeouts
];

Where to look first:

1. The package README and src/ for the exact facade alias and method names — v0.1.0 shipped with an empty changelog, so there is no documented API contract yet. Confirm the public surface in vendor/frank-l93/ai-inflector/src rather than trusting the tag name.
2. config/ai-inflector.php after publishing — this is the only stable entry point at 0.1.0.
3. The tests/ directory, which usually doubles as the best usage documentation for a first release.

First use case: user-generated content labels. A marketplace listing titled "Nike Air Max 97s" or "2x Nintendo Switch Joy-Con" breaks Str::plural()/Str::slug() in predictable ways. Route the display label and slug through the inflector once at write time, store the result, and never call it again on read.

Implementation Patterns

Resolve once at write time, persist the result. Treat the inflector as a build step, not a runtime helper. Call it in a form request, action, or observer and store the normalised value in a column:

$product->slug = AiInflector::slug($request->input('title'));
$product->save();

Cache aggressively, key on input + locale. AI-backed inflection is non-deterministic and billed per call. Wrap the facade in a thin repository so the cache layer is yours, not the package's:

final class InflectorRepository
{
    public function plural(string $word, string $locale = 'en'): string
    {
        return Cache::remember(
            "inflect:plural:{$locale}:".md5($word),
            now()->addMonth(),
            fn () => AiInflector::pluralize($word, $locale)
        );
    }
}

Always keep a local fallback. If the driver times out or the key is missing, degrade to Laravel's own helpers so a queue worker never dies on a slug:

try {
    return $this->inflector->pluralize($word);
} catch (Throwable $e) {
    report($e);
    return Str::plural($word);
}

Batch and queue for backfills. When you add the package to an existing app, do not loop over 50k rows synchronously. Use a chunked job with Bus::batch() so throttle/retry semantics come from your queue, not the package:

Bus::batch(
    Product::query()->pluck('id')->chunk(500)
        ->map(fn ($ids) => new RefreshProductSlug($ids))
)->dispatch();

Test with a fake driver. Any test suite that touches models will otherwise make outbound HTTP calls. Bind a deterministic stub in TestCase::setUp() (or the config entry for the fake driver) that returns Str::plural()/Str::slug() results, and assert on your cache keys instead of the AI output.

Prefer constructor injection over the facade in services and jobs — it makes the swap to a fake or to a self-hosted driver trivial and keeps the package out of your domain layer's static surface.

Gotchas and Tips

• Nothing in the v0.1.0 release notes. The tag has an auto-generated changelog with no entries, so there is no advertised BC policy or feature list. Pin the exact version ("frank-l93/ai-inflector": "0.1.0") and expect breaking changes on 0.2.0. Read the diff before upgrading.
• Non-determinism is the core hazard. The same input can yield "Joy-Cons" today and "Joy Cons" tomorrow. Never use the output as a cache key, unique constraint, or anything you compare across requests without persisting it first.
• Don't call it in migrations, model accessors, or Blade. A getSlugAttribute() accessor that hits a driver will turn every foreach into an API round-trip. This is the single most common way to blow up a bill on a package like this.
• Config caching traps. php artisan config:cache freezes the config array; if the driver resolves credentials lazily via env() inside the package (common in early releases), those calls return null in production. Read credentials from config() in your own code and verify with php artisan config:cache && php artisan tinker.
• Locale is easy to forget. Pass it explicitly for non-English content — an inflection library defaulting to en will silently mangle German compounds or Spanish plurals. Check whether the v0.1.0 signature even accepts a locale before designing around it.
• Timeouts and retries belong to you. Set a short HTTP timeout in the config and wrap calls in your own single retry with backoff. A queue worker blocked for 60s on a hung driver is worse than a wrong plural.
• Debugging: log the driver name, locale, input, and output at debug level in your repository wrapper. When a slug looks wrong, php artisan tinker against the facade directly — if it's right there but wrong in the app, the problem is your cache key, not the package.
• Extension points to watch: a custom driver contract (so you can point at a local model or a cheaper provider) and any macroable facade. At 0.1.0 neither may be documented; check src/ before assuming. If there's no driver interface yet, wrapping the package behind your own InflectorRepository is the safest hedge against a rewrite in 0.2.