Czech Bank Account Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require czechphp/czech-bank-account
   

   The package is auto-discoverable in Laravel 5.5+ (no manual service provider registration required).

2. Basic Usage Validate a Czech bank account (IBAN) in a controller:

   use CzechBankAccount\IBAN;
   
   public function validateAccount(Request $request)
   {
       $iban = $request->input('iban');
       $validator = new IBAN($iban);
   
       if ($validator->isValid()) {
           return response()->json([
               'valid' => true,
               'bank' => $validator->getBank(),
               'bic' => $validator->getBIC()
           ]);
       }
       return response()->json([
           'valid' => false,
           'errors' => $validator->getErrors()
       ], 400);
   }
   

3. First Use Case

   • Form Validation with Laravel's Validator:

     $request->validate([
         'iban' => ['required', function ($attribute, $value, $fail) {
             $validator = new IBAN($value);
             if (!$validator->isValid()) {
                 $fail('Invalid Czech IBAN. ' . implode(', ', $validator->getErrors()));
             }
         }],
     ]);
     

Implementation Patterns

Core Workflows

1. Validation & Metadata Extraction

   • Use the IBAN class for validation and structured data access:

     $iban = new IBAN('CZ1234567890123456789012');
     $iban->isValid(); // bool
     $iban->getBank(); // string (e.g., "ČSOB")
     $iban->getAccountNumber(); // string
     $iban->getBIC(); // string (Bank Identifier Code)
     

2. Batch Processing

   • Validate multiple IBANs efficiently using Laravel collections:

     $ibans = ['CZ123...', 'CZ456...'];
     $results = collect($ibans)->map(function ($iban) {
         $validator = new IBAN($iban);
         return [
             'iban' => $iban,
             'valid' => $validator->isValid(),
             'bank' => $validator->isValid() ? $validator->getBank() : null,
         ];
     });
     

3. API Integration

   • Return structured responses with metadata:

     return response()->json([
         'iban' => $request->iban,
         'valid' => $validator->isValid(),
         'bank' => $validator->getBank(),
         'bic' => $validator->getBIC(),
         'account_number' => $validator->getAccountNumber(),
     ]);
     

Integration Tips

• Laravel Form Requests Extend FormRequest for reusable validation logic:

  use CzechBankAccount\IBAN;
  
  public function rules()
  {
      return [
          'iban' => ['required', function ($attribute, $value) {
              return (new IBAN($value))->isValid();
          }],
      ];
  }
  

• Database Storage Store parsed IBAN data in migrations with additional fields:

  $table->string('iban')->unique();
  $table->string('bank')->nullable();
  $table->string('bic')->nullable();
  $table->string('account_number')->nullable();
  

• Caching Cache bank metadata for performance optimization:

  $bank = Cache::remember("iban_bank_{$iban}", now()->addHours(1), function() use ($iban) {
      return (new IBAN($iban))->getBank();
  });
  

Gotchas and Tips

Common Pitfalls

1. Deprecated Classes Removed

   • Breaking Change: The v2.0.0 release removes deprecated constant symbol database classes. Ensure your code does not rely on these deprecated classes (e.g., CzechBankAccount\Constants\BankSymbols).

2. Case Sensitivity

   • IBANs are case-insensitive, but the package normalizes to uppercase. Ensure consistency in storage and validation.

3. Bank Data Updates

   • The package uses static bank data. Verify the dataset's last update (check the package's documentation or source) and consider forking if you need to maintain custom bank data.

4. Country-Specific Validation

   • isValid() returns false for non-Czech IBANs. Use isCzech() to check the country first:

     if ((new IBAN($iban))->isCzech()) {
         // Proceed with Czech-specific validation
     }
     

5. Error Handling

   • getErrors() returns an array of validation messages. Handle edge cases like empty input:

     $validator = new IBAN($iban ?? '');
     if (empty($iban)) {
         return back()->withErrors(['iban' => 'IBAN is required']);
     }
     

Debugging Tips

• Log Raw Data For debugging, log the parsed components:

  $validator = new IBAN($iban);
  \Log::debug('IBAN Parsed:', [
      'valid' => $validator->isValid(),
      'components' => [
          'bank' => $validator->getBank(),
          'bic' => $validator->getBIC(),
          'account_number' => $validator->getAccountNumber(),
      ],
      'errors' => $validator->getErrors(),
  ]);
  

• Test Edge Cases Test with:

  • Valid Czech IBANs (e.g., CZ6508000000192000141399).
  • Invalid formats (e.g., CZ123, CZ123456789012345678901234).
  • Non-Czech IBANs (e.g., DE89370400440532013000).

Extension Points

1. Custom Bank Data Override the bank dataset by publishing and modifying the config:

   php artisan vendor:publish --provider="CzechBankAccount\CzechBankAccountServiceProvider" --tag="config"
   

   Edit config/czech-bank-account.php to add or modify bank entries.

2. Event Listeners Trigger events on validation (e.g., log valid/invalid IBANs):

   // In EventServiceProvider
   protected $listen = [
       'czech-bank-account.validated' => [IBANValidatedListener::class],
       'czech-bank-account.invalid' => [IBANInvalidListener::class],
   ];
   

3. API Wrappers Extend the IBAN class for additional logic:

   class EnhancedIBAN extends IBAN {
       public function isBusinessAccount(): bool {
           return str_starts_with($this->getAccountNumber(), '1');
       }
   
       public function getBankSwift(): string {
           return $this->getBIC() ?: 'UNKNOWN';
       }
   }
   

4. Custom Validation Rules Create a custom Laravel validation rule:

   php artisan make:rule ValidCzechIBAN
   

   // app/Rules/ValidCzechIBAN.php
   use CzechBankAccount\IBAN;
   
   public function passes($attribute, $value)
   {
       return (new IBAN($value))->isValid();
   }
   
   public function message()
   {
       return 'The :attribute must be a valid Czech IBAN.';
   }
   

   Usage:

   $request->validate([
       'iban' => ['required', new ValidCzechIBAN],
   ]);