faker-realistic-ptbr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Faker Realistic pt_BR

## Consistency First

Esta skill é opt-in. O locale do Faker já vem fixado por `translation` (`APP_FAKER_LOCALE=pt_BR` no `.env`). Use `fake()` sem argumento em todas as factories: o locale resolve automaticamente. Antes de criar provider custom, valide que o Faker `pt_BR` nativo não cobre o caso (CPF, CNPJ, celular, CEP, rua, cidade, nome, email seguro são nativos).

## Quick Reference

- `fake()` sem argumento. Locale vem do `.env` (`APP_FAKER_LOCALE=pt_BR`).
- Não instalar pacote externo de Faker BR. `fakerphp/faker` cobre tudo nativo.
- Nativos pt_BR cobertos: `cpf()`, `cnpj()`, `cellphoneNumber()`, `postcode()`, `streetName()`, `city()`, `name()`, `safeEmail()`, `companyEmail()`, `jobTitle()`.
- Provider custom só para domínio específico: códigos internos, fixtures JSON, valores de catálogo.
- Provider estende `\Faker\Provider\Base`, registrado em `AppServiceProvider::boot()`.
- Factories chamam métodos do provider; nunca leem JSON diretamente.
- Fixtures JSON ficam em `resources/json/`, versionadas, sem dados pessoais reais.

## Workflow

- [ ] Confirmar que o locale do Faker está fixado:

```bash
vendor/bin/sail artisan tinker --execute 'echo config("app.faker_locale");'
# Esperado: pt_BR
```

- [ ] Validar que o Faker nativo não resolve o caso antes de criar provider:

```bash
vendor/bin/sail artisan tinker --execute 'echo fake()->cpf();'
vendor/bin/sail artisan tinker --execute 'echo fake()->cnpj();'
vendor/bin/sail artisan tinker --execute 'echo fake()->cellphoneNumber();'
vendor/bin/sail artisan tinker --execute 'echo fake()->safeEmail();'
```

- [ ] Se precisar de provider custom, criar diretório e classe:

```bash
mkdir -p app/Providers/Faker
```

```php
<?php

namespace App\Providers\Faker;

use Faker\Provider\Base;
use Illuminate\Support\Arr;
use RuntimeException;

final class FakerProvider extends Base
{
    /**
     * @var list<array{code: string, name: string}>
     */
    private array $cachedItems = [];

    public function internalCode(): string
    {
        return (string) static::numberBetween(100000, 999999);
    }

    public function catalogName(): string
    {
        $item = Arr::random($this->items());

        return $item['name'];
    }

    /**
     * @return list<array{code: string, name: string}>
     */
    private function items(): array
    {
        if ($this->cachedItems !== []) {
            return $this->cachedItems;
        }

        $path = resource_path('json/catalog.json');

        if (! file_exists($path)) {
            throw new RuntimeException('Fixture resources/json/catalog.json não encontrada.');
        }

        $items = json_decode((string) file_get_contents($path), true, flags: JSON_THROW_ON_ERROR);

        if (! is_array($items) || $items === []) {
            throw new RuntimeException('Fixture catalog.json deve ser lista não vazia.');
        }

        /** @var list<array{code: string, name: string}> $items */
        return $this->cachedItems = $items;
    }
}
```

- [ ] Registrar o provider em `App\Providers\AppServiceProvider::boot()`. Locale único — sem laço por idioma:

```php
use App\Providers\Faker\FakerProvider;

public function boot(): void
{
    $faker = fake();
    $faker->addProvider(new FakerProvider($faker));
}
```

- [ ] Usar nas factories sem repassar locale:

```php
public function definition(): array
{
    return [
        'document_number' => fake()->cpf(),
        'phone' => fake()->cellphoneNumber(),
        'internal_code' => fake()->internalCode(),
        'catalog_name' => fake()->catalogName(),
    ];
}

From CoringaWc/ai-first-kit, MIT.

More from CoringaWc/ai-first-kit