Cz Bank Account Validator Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require ebrana/cz-bank-account-validator-bundle

Publish the bundle configuration (if needed for custom bank codes):

php artisan vendor:publish --provider="Ebrana\CzBankAccountValidatorBundle\CzBankAccountValidatorBundle"

First Use Case: Validate a Czech bank account number in a Symfony Form or DTO.

use Ebrana\CzBankAccountValidatorBundle\Validator\AccountNumberValid;

class PaymentRequest {
    #[AccountNumberValid]
    public string $accountNumber; // Format: "123-45678901/2010"
}

Implementation Patterns

1. Direct Property Validation

Use the attribute on properties containing full account numbers (e.g., 123-45678901/2010):

class Invoice {
    #[AccountNumberValid]
    public string $payerAccount;

    #[AccountNumberValid]
    public ?string $recipientAccount = null;
}

2. Composite Account Validation

For split account components (prefix, IBAN, bank code), use the method-based approach:

class Payment {
    public string $prefix;       // e.g., "123"
    public string $accountNumber; // e.g., "45678901"
    public string $bankCode;     // e.g., "2010"

    #[AccountNumberValid(
        bankCodePath: 'bankCode',
        prefixPath: 'prefix'
    )]
    public function getFullAccountNumber(): string {
        return $this->prefix . '-' . $this->accountNumber . '/' . $this->bankCode;
    }
}

3. Form Integration

Bind the validator to Symfony Forms:

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

class PaymentFormType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder
            ->add('accountNumber', TextType::class, [
                'constraints' => [new AccountNumberValid()]
            ]);
    }
}

4. API Request Validation

Use in Laravel API resources or DTOs:

use Ebrana\CzBankAccountValidatorBundle\Validator\AccountNumberValid;

class CreatePaymentRequest {
    #[AccountNumberValid]
    public string $accountNumber;
}

5. Custom Error Messages

Override default validation messages:

#[AccountNumberValid(
    message: 'Invalid Czech bank account format. Expected: XXX-XXXXXXXX/XXXX.'
)]
public string $accountNumber;

Gotchas and Tips

1. Format Strictness

• Gotcha: The validator expects strict Czech format (XXX-XXXXXXXX/XXXX).
  • ❌ Fails: 123456789012345678 (no separators)
  • ✅ Passes: 123-45678901/2010
• Fix: Normalize input before validation:

  $normalized = preg_replace('/[^\d\/-]/', '', $rawInput);
  

2. Bank Code Validation

• Gotcha: The bundle uses a static list of bank codes (from CNB).
  • If a new bank code appears, validation fails unless updated.
• Fix: Extend the bank code provider via service decoration:

  // config/services.php
  'decorated.cz_bank_account_validator.bank_code_provider' => [
      'class' => App\Services\CustomBankCodeProvider::class,
      'decorates' => 'cz_bank_account_validator.bank_code_provider',
  ],
  

3. Null Handling

• Gotcha: The validator does not accept null by default.
  • ❌ Fails: #[AccountNumberValid] on a nullable property with null value.
• Fix: Use nullable: true:

  #[AccountNumberValid(nullable: true)]
  public ?string $optionalAccount;
  

4. Debugging Failures

• Tip: Check the exact validation error:

  $validator = new AccountNumberValid();
  $errors = $validator->validate('invalid-account', new ConstraintValidator());
  dd($errors); // Array of error messages
  

5. Performance Note

• Tip: The bank code list is loaded once per request (lazy-loaded). For high-throughput systems, cache the list:

  // app/Providers/AppServiceProvider.php
  public function boot() {
      Cache::remember('cz_bank_codes', now()->addHours(1), function () {
          return (new BankCodeProvider())->getCodes();
      });
  }
  

6. Testing

• Tip: Mock the bank code provider in tests:

  $this->app->instance(
      'cz_bank_account_validator.bank_code_provider',
      new class implements BankCodeProviderInterface {
          public function getCodes(): array { return ['2010' => 'ČSOB']; }
      }
  );
  

7. Laravel-Specific Integration

• Tip: Use with Laravel’s built-in validation:

  $request->validate([
      'account_number' => ['required', new AccountNumberValid()]
  ]);
  

• Gotcha: The Symfony ConstraintValidator interface may conflict with Laravel’s Validator. Fix: Ensure the bundle’s validator is registered in Laravel’s container:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->bind(
          ConstraintValidatorInterface::class,
          Ebrana\CzBankAccountValidatorBundle\Validator\AccountNumberValidator::class
      );
  }
  

8. Upgrade Notes

• v2.0.1: Removed default paths for bankCodePath/prefixPath. Action Required: Update all method-based usages to explicitly define paths.

  // Before (v1.x)
  #[AccountNumberValid] // ❌ Fails in v2.0.1
  public function getAccountNumber() { ... }
  
  // After (v2.0.1+)
  #[AccountNumberValid(bankCodePath: 'bankCode', prefixPath: 'prefix')]
  public function getAccountNumber() { ... }