Czech Bank Account Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require czechphp/czech-bank-account-bundle
   

   Register the bundle in config/bundles.php:

   Czechphp\CzechBankAccountBundle\CzechBankAccountBundle::class => ['all' => true],
   

2. First Use Case: Validate a Czech bank account number in a Symfony form:

   use Czechphp\CzechBankAccountBundle\Validator\Constraints\CzechBankAccount;
   
   // In your entity or DTO
   #[Assert\Constraint(
       new CzechBankAccount()
   )]
   private string $accountNumber;
   

3. Quick Validation: Use the standalone validator in a controller:

   use Czechphp\CzechBankAccountBundle\Validator\CzechBankAccountValidator;
   
   $validator = new CzechBankAccountValidator();
   $isValid = $validator->validate('1234567890/0100'); // Returns true/false
   

Implementation Patterns

Form Integration

1. Form Type: Use the provided form type for seamless integration:

   use Czechphp\CzechBankAccountBundle\Form\Type\CzechBankAccountType;
   
   $builder->add('accountNumber', CzechBankAccountType::class);
   

   • Automatically validates format (e.g., 1234567890/0100).
   • Supports custom messages via options['error_bubbling'] and error_mapping.

2. Component-Based UI: Render a pre-styled input with the czech_bank_account Twig component:

   {{ form_row(form.accountNumber) }}
   {{ czech_bank_account(form.accountNumber) }} {# Adds hints/tooltips #}
   

Validation Workflows

1. API/DTO Validation: Attach the constraint to a DTO or request object:

   #[Assert\All({
       new CzechBankAccount(groups: ['api']),
   })]
   private array $accountNumbers;
   

   • Use groups to control validation contexts (e.g., api, web).

2. Batch Processing: Validate multiple accounts in bulk:

   $validator = $this->container->get(CzechBankAccountValidator::class);
   $results = $validator->validateBatch([
       '1234567890/0100',
       'invalid/format',
   ]);
   // Returns array of validation results
   

Common Use Cases

1. User Registration: Validate account numbers during user signup:

   $user->setAccountNumber($request->get('account_number'));
   $errors = $validator->validate($user);
   

2. Payment Processing: Parse account details for IBAN generation:

   use Czechphp\CzechBankAccountBundle\Parser\CzechBankAccountParser;
   
   $parser = new CzechBankAccountParser();
   $account = $parser->parse('1234567890/0100');
   $iban = $account->toIban(); // Generates IBAN
   

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • Bundle requires Symfony 6/7 (PHP ≥8.1). Older versions (3/4) are unsupported.
   • Debug ClassNotFoundException if using Symfony 5.x (upgrade or check bundles.php).

2. False Positives:

   • The validator rejects non-Czech accounts (e.g., DE89370400440532013000). Handle gracefully:

     try {
         $validator->validate($accountNumber);
     } catch (\InvalidArgumentException $e) {
         // Log or notify user
     }
     

3. Form Error Handling:

   • Customize error messages in the form type:

     $builder->add('accountNumber', CzechBankAccountType::class, [
         'error_mapping' => [
             CzechBankAccount::INVALID_FORMAT => 'custom.invalid_format',
         ],
     ]);
     

Debugging Tips

1. Validator Output: Enable debug mode to see raw validation messages:

   $validator->setTranslationDomain('validators'); // For Symfony translation
   $errors = $validator->validate('invalid');
   dump($errors); // Shows detailed error codes (e.g., `INVALID_FORMAT`)
   

2. Parser Quirks:

   • The parser strips whitespace but is case-sensitive for bank codes (e.g., 0100 ≠ 0100 ).
   • Test edge cases:

     $parser->parse(' 1234567890 /0100 '); // Works
     $parser->parse('1234567890/0100X'); // Fails (trailing chars)
     

Extension Points

1. Custom Constraints: Extend the base constraint for project-specific rules:

   use Czechphp\CzechBankAccountBundle\Validator\Constraints\CzechBankAccount as BaseConstraint;
   
   #[Assert\Constraint]
   class CustomCzechBankAccount extends BaseConstraint {
       public string $message = 'Account must be from a specific bank.';
       public string $bankCode = '0100'; // Only allow ČSOB
   
       public function validatedBy(): string {
           return static::class.'Validator';
       }
   }
   

2. Twig Component Overrides: Override the default Twig component in your theme:

   {# templates/components/czech_bank_account.html.twig #}
   <div class="custom-account-input">
       {{ form_widget(form) }}
       <small>Format: 1234567890/0100</small>
   </div>
   

3. IBAN Generation: Combine with league/iban for extended functionality:

   use Czechphp\CzechBankAccountBundle\Parser\CzechBankAccountParser;
   use League\Iban\Iban;
   
   $account = (new CzechBankAccountParser())->parse('1234567890/0100');
   $iban = Iban::fromAccountNumber($account->toAccountNumber());
   

Performance Notes

• Caching: The validator is stateless; no caching needed for single calls.
• Batch Validation: For large datasets, use validateBatch() to avoid per-item overhead.

```markdown
### Config Quirks
1. **No Bundle Configuration**:
   The bundle has **zero required config**. All features are opt-in via constraints/form types.

2. **Translation**:
   Default messages are in English. Override in `translations/validators.xlf`:
   ```xml
   <trans-unit id="czech_bank_account.invalid_format">
       <source>Invalid Czech bank account format.</source>
       <target>Neplatný formát českého účtu.</target>
   </trans-unit>

3. Dependency Conflicts:
   • Avoid version conflicts with czechphp/czech-bank-account (v2.x required).
   • Use composer why-not czechphp/czech-bank-account:^2.0 to debug.