Codice Fiscale Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (unchanged):

   composer require davidepastore/codice-fiscale
   

   No additional configuration is required—it remains a self-contained library.

2. First Use Case (Updated for PHP 8.4 compatibility) Generate a tax code (codice fiscale) for a given name, surname, and birthdate:

   use DavidePastore\CodiceFiscale\CodiceFiscale;
   
   // PHP 8.4+ compatible (DateTime constructor changes handled internally)
   $cf = new CodiceFiscale('Mario', 'Rossi', '1980-05-15', 'M', 'Roma');
   echo $cf->getCodiceFiscale(); // Output: RSSMRR80E15A453X
   

3. Where to Look First (Updated with CI/CD and Docker context)

   • Documentation: GitHub README (now includes Docker setup).
   • Core Class: DavidePastore\CodiceFiscale\CodiceFiscale (handles generation/validation with PHP 8.4+ fixes).
   • Test Suite: tests/ directory (now includes PHP 8.3/8.4 test configurations).
   • Docker Environment: New .docker/ setup for local development (see PR #73).

Implementation Patterns

Core Workflows (Updated for PHP 8.x compatibility)

1. Generating a Codice Fiscale (No changes, but now fully PHP 8.4-compatible)

   $cf = new CodiceFiscale('Anna', 'Bianchi', '1995-11-20', 'F', 'Milano');
   $code = $cf->getCodiceFiscale(); // Returns validated string.
   

2. Validating an Existing Codice Fiscale (No changes)

   use DavidePastore\CodiceFiscale\Validator;
   $validator = new Validator();
   $isValid = $validator->validate('RSSMRR80E15A453X'); // Returns bool.
   

3. Parsing a Codice Fiscale (No changes)

   $parser = new \DavidePastore\CodiceFiscale\Parser();
   $data = $parser->parse('RSSMRR80E15A453X');
   

Integration Tips (Updated for Docker/Laravel Sail)

• Laravel Blade Integration (No changes, but now tested on PHP 8.4)

  // app/Helpers/CodiceFiscale.php
  function generateCodiceFiscale($name, $surname, $birthdate, $gender, $city) {
      return (new \DavidePastore\CodiceFiscale\CodiceFiscale($name, $surname, $birthdate, $gender, $city))->getCodiceFiscale();
  }
  

• Docker/Laravel Sail Integration (New) Use the package in a Dockerized Laravel environment:

  # Start Sail with PHP 8.4
  sail up -d
  sail composer require davidepastore/codice-fiscale
  
  # Run tests in container
  sail artisan test
  

• Form Request Validation (No changes, but now CI-tested on PHP 8.4)

  public function rules() {
      return [
          'codice_fiscale' => ['required', function ($attribute, $value, $fail) {
              if (!Validator::validate($value)) {
                  $fail('Codice fiscale non valido.');
              }
          }]
      ];
  }
  

Gotchas and Tips

Pitfalls (Updated for PHP 8.x and Docker)

1. Municipality Code Requirement (Unchanged, but now CI-tested on PHP 8.4)

   • Fix: Maintain a mapping (e.g., config/cities.php) or use an external API.

2. Foreign Names/Surnames (Unchanged, but now tested on PHP 8.4)

   • Fix: Normalize names before passing:

     $normalizedName = strtoupper(preg_replace('/[^A-Za-z]/', '', $name));
     

3. PHP 8.1+ DateTime Deprecation (Resolved in v0.10.0)

   • No action needed: The library now handles DateTime constructor changes internally (see PR #81).

4. Docker Setup Quirks (New)

   • Issue: If using the new Docker environment, ensure .env files are copied:

     cp .env.example .env
     

   • Debugging: Run tests in the container to verify PHP 8.4 compatibility:

     sail artisan test
     

Debugging Tips (Updated for PHP 8.4)

• Validation Errors:

  $validator = new Validator();
  $errors = $validator->getErrors('INVALID123'); // Works on PHP 8.4.
  

• Logging Parsed Data:

  $parser = new \DavidePastore\CodiceFiscale\Parser();
  $data = $parser->parse('RSSMRR80E15A453X');
  \Log::info('Parsed data:', $data);
  

Extension Points (Updated for PHP 8.4 compatibility)

1. Custom Municipality Mapping (No changes, but now tested on PHP 8.4)

   class CustomCodiceFiscale extends \DavidePastore\CodiceFiscale\CodiceFiscale {
       protected function getMunicipalityCode($city) {
           return $this->customMapping[$city] ?? parent::getMunicipalityCode($city);
       }
   }
   

2. Docker-Based Development (New) Extend the Docker setup for local testing:

   # Add to docker-compose.yml
   services:
       laravel.test:
           build:
               context: .
               dockerfile: Dockerfile
           environment:
               - COMPOSER_ALLOW_SUPERUSER=1
   

3. PHP 8.4-Specific Optimizations (New) Leverage PHP 8.4 features in custom extensions:

   // Example: Use read-only properties (PHP 8.4)
   class StrictCodiceFiscale extends \DavidePastore\CodiceFiscale\CodiceFiscale {
       public function __construct(
           public readonly string $name,
           public readonly string $surname,
           // ...
       ) {
           parent::__construct($name, $surname, ...);
       }
   }
   

Performance Notes (Updated for PHP 8.4)

• Caching: Now tested on PHP 8.4’s OPcache improvements.

• Batch Validation: Use Laravel’s parallel with PHP 8.4’s JIT compiler:

  $codes = collect($codes)->parallel()->each(fn($code) => Validator::validate($code));
  

• Docker Performance: Enable PHP 8.4’s ZTS mode in Docker for better multi-threading:

  RUN docker-php-ext-configure zts && docker-php-ext-install pdo pdo_mysql