Getting Started

Minimal Steps

Installation
```
composer require brazilianfriendsofsymfony/brasil-bundle
```
Ensure jQuery and RequireJS are included in your project (e.g., via webpack or CDN).

Configure Twig Add the bundle’s form layout to your config/packages/twig.yaml:

twig:
    form:
        resources:
            - 'BFOSBrasilBundle:Form:form_div_layout.html.twig'

Load Fixtures (for City/State Form Type) Run the Doctrine fixtures loader to populate cities/states:
```
php bin/console doctrine:fixtures:load
```

First Use Case: Validate a CPF Use the CPF constraint in an entity:

use BFOSBrasil\Validator\Constraints as BrasilAssert;

class User
{
    #[BrasilAssert\CPF]
    private $cpf;
}

Implementation Patterns

1. Form Types (City/State)

Usage:

use BFOSBrasil\Form\Type\CidadeType;

$builder->add('city', CidadeType::class);

Workflow:
- The bundle auto-loads states (UF) via a dropdown.
- Cities are fetched via AJAX when a state is selected.
- Requires DoctrineFixturesBundle for initial data seeding.
Integration Tips:
- Ensure your Twig templates extend form_div_layout.html.twig for AJAX to work.
- Customize the city list via doctrine:fixtures:load or override the fixture loader.

2. Validation Constraints

Usage:

use BFOSBrasil\Validator\Constraints as BrasilAssert;

class Client
{
    #[BrasilAssert\CPF]
    private $document;

    #[BrasilAssert\CNPJ]
    private $companyDocument;

    #[BrasilAssert\Telefone]
    private $phone;

    #[BrasilAssert\DDD]
    private $ddd;
}

Workflow:
- Validations trigger automatically in Symfony’s validation pipeline.
- Customize error messages in config/validator/validation.yaml:
```
BFOSBrasil\Validator\Constraints\CPF:
    message: 'CPF inválido.'
```
Integration Tips:
- Combine with Symfony’s ValidatorInterface for dynamic validation (e.g., in forms).
- Extend constraints by implementing ConstraintValidatorInterface.

3. Routing

Usage: Import routes in config/routes.yaml:

bfos_brasil:
    resource: '@BFOSBrasilBundle/Resources/config/routing.yml'

Workflow:
- Provides endpoints for city/state data (e.g., /_brasil/cidades).
- Useful for custom AJAX calls if the form type’s default behavior is insufficient.

Gotchas and Tips

Pitfalls

Missing Fixtures:
- Forgetting to run doctrine:fixtures:load will break the CidadeType.
- Fix: Manually seed the cidades table or override the fixture loader.
jQuery/RequireJS Dependency:
- The bundle relies on these libraries for AJAX. If missing, the city dropdown fails silently.
- Fix: Verify inclusion in your assets/ pipeline or <head>.
Validation Overrides:
- Custom constraints may conflict with existing validators.
- Fix: Use priority in constraint annotations or implement ConstraintValidatorInterface.
Twig Template Conflicts:
- Overriding form_div_layout.html.twig may break AJAX functionality.
- Fix: Extend the template instead of replacing it.

Debugging Tips

Check Fixtures:

php bin/console doctrine:query:sql "SELECT * FROM cidades LIMIT 5"

Validate Constraints Manually:

$validator = $this->get('validator');
$errors = $validator->validate($entity);

Inspect AJAX Calls: Use browser dev tools to verify /_brasil/cidades endpoints return data.

Extension Points

Custom City Data: Override the fixture loader or create a custom CidadeRepository.

New Validation Rules: Extend BrasilAssert namespace or create a custom validator:

class CEPValidator extends ConstraintValidator
{
    public function validate($value, Constraint $constraint)
    {
        // Custom logic
    }
}

Form Type Customization: Extend CidadeType to modify behavior (e.g., add placeholders):

class CustomCidadeType extends CidadeType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->addModelTransformer(...);
    }
}

Brasil Bundle Laravel Package