Doctrine Types Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel Compatibility: While designed for Symfony, the package’s Doctrine DBAL types are framework-agnostic and can be leveraged in Laravel via doctrine/dbal or laravel-doctrine bridges. This avoids reinventing custom validation logic for types like IBAN, SpanishNif, or Money.
  • Regional Compliance: The addition of SpanishNifType directly addresses EU/Spain-specific compliance needs, reducing custom validation code for tax identifiers.
  • PHP 8.4+ Alignment: Syncs with Laravel 10+ (PHP 8.4+), ensuring long-term compatibility and access to modern PHP features (e.g., typed properties, enums).
  • Validation Centralization: Eliminates duplicate validation logic across entities by standardizing types (e.g., EmailType, CurrencyType) in a single bundle.
  • Future-Proofing: PHPUnit 10 and CI/CD upgrades signal maintainability, reducing technical debt for teams adopting newer Laravel versions.

• Cons:

  • Doctrine Dependency: Introduces Doctrine DBAL/ORM as a dependency, which may be overkill for projects not already using it (e.g., pure Eloquent apps).
  • Symfony Validator Lock-In: Laravel’s Illuminate\Validation is not natively supported; requires manual translation of Symfony constraints to Laravel rules or custom validators.
  • ORM Complexity: Integrating Doctrine ORM in Laravel (via laravel-doctrine/orm) adds complexity for teams unfamiliar with Doctrine’s entity mapping.
  • Type Proliferation: Adding locale-specific types (e.g., SpanishNifType) may encourage similar custom types, increasing maintenance overhead if not managed centrally.

Integration Feasibility

• DBAL Integration:

  • Feasibility: High. Replace raw column types in migrations (e.g., VARCHAR → SpanishNifType) using Doctrine’s Platform configuration.
  • Example:

    // config/doctrine.php
    'dbal' => [
        'types' => [
            'spanish_nif' => \AssoConnect\DoctrineTypesBundle\DBAL\Types\SpanishNifType::class,
        ],
    ];
    

  • Use Case: Ideal for repositories or raw query scenarios where Doctrine DBAL is already in use.

• ORM Integration:

  • Feasibility: Medium. Requires laravel-doctrine/orm or manual @Type annotations in entities.
  • Example:

    use Doctrine\ORM\Mapping as ORM;
    use AssoConnect\DoctrineTypesBundle\DBAL\Types\SpanishNifType;
    
    #[ORM\Entity]
    class Client {
        #[ORM\Column(type: SpanishNifType::NAME)]
        private string $taxId;
    }
    

  • Use Case: Suitable for teams already using Doctrine ORM or migrating from Symfony.

• Validation Integration:

  • Feasibility: Low-Medium. Symfony constraints must be translated to Laravel’s Validator or custom rules.
  • Example:

    // Replace Symfony constraint with Laravel rule
    use Illuminate\Validation\Rule;
    
    $validator->addRules([
        'tax_id' => ['required', Rule::custom(function ($attribute, $value) {
            return (new SpanishNifType())->convertToDatabaseValue($value) !== null;
        })],
    ]);
    

  • Use Case: Teams using Laravel’s built-in validation but needing Doctrine-type validation logic.

Technical Risk

• High:

  • Doctrine Adoption: Introducing Doctrine ORM/DBAL in a Laravel project requires buy-in and upskilling (e.g., entity mapping, DQL).
  • Validation Translation: Manual effort to map Symfony constraints to Laravel rules, risking inconsistencies.
  • PHP 8.4+ Requirement: Breaks compatibility with Laravel 9.x (PHP 8.1/8.2) unless manually patched.
  • Type-Specific Edge Cases: New types (e.g., SpanishNifType) may need additional business logic (e.g., locale-aware rules).

• Medium:

  • Performance Overhead: Custom types may add query parsing latency (benchmark critical paths with EXPLAIN ANALYZE).
  • Dependency Bloat: Adds Doctrine to the stack, increasing bundle size and potential attack surface.
  • Team Upskilling: Requires documentation and training for Doctrine-specific concepts (e.g., custom types, platform configurations).

• Low:

  • Bundle Maturity: Active maintenance (monthly releases), high test coverage (SonarCloud), and MIT license.
  • New Features: SpanishNifType is a low-risk addition (similar to existing types like IBAN or Siret).

Key Questions

1. Doctrine Strategy:
   • Will the project adopt Doctrine ORM (for entities) or stick to DBAL-only (for raw queries)? Does Laravel’s Eloquent suffice for current needs?
2. Validation Approach:
   • Will Symfony constraints be translated to Laravel rules or replaced with custom Validator extensions? What’s the effort estimate?
3. PHP Version Alignment:
   • Is upgrading to Laravel 10+ (PHP 8.4+) feasible, or will manual overrides be required for Laravel 9.x?
4. Locale-Specific Types:
   • Does SpanishNifType cover all edge cases (e.g., historical formats, validation rules)? Are similar types needed for other locales (e.g., ItalianCodiceFiscale)?
5. Performance Impact:
   • Have custom types been benchmarked in production-like queries? What’s the overhead compared to native Laravel validation?
6. Long-Term Maintenance:
   • How will custom types be documented for onboarding? Will internal wrappers abstract Doctrine-specific details?
7. Migration Path:
   • What’s the sequencing for integrating DBAL types (Phase 1), ORM mapping (Phase 2), and validation (Phase 3)?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: DBAL Integration (Low Risk)

   • Goal: Replace raw column types in migrations with custom Doctrine types.
   • Steps:
     1. Install dependencies:

        composer require doctrine/dbal assoconnect/doctrine-types-bundle
        

     2. Configure DBAL types in config/doctrine.php:

        'types' => [
            'spanish_nif' => \AssoConnect\DoctrineTypesBundle\DBAL\Types\SpanishNifType::class,
            'iban' => \AssoConnect\DoctrineTypesBundle\DBAL\Types\IbanType::class,
        ],
        

     3. Update migrations to use custom types:

        $table->column('tax_id', 'spanish_nif')->nullable();
        

   • Validation: Use Laravel’s Validator with custom rules (see below).

2. Phase 2: ORM Integration (Medium Risk)

   • Goal: Map custom types to Eloquent models via Doctrine ORM (optional).
   • Steps:
     1. Install laravel-doctrine/orm:

        composer require laravel-doctrine/orm
        

     2. Configure Doctrine ORM in config/doctrine.php.
     3. Annotate entities with custom types:

        #[ORM\Column(type: SpanishNifType::NAME)]
        private string $taxId;
        

   • Use Case: Only if Doctrine ORM is already in use or needed for complex queries.

3. Phase 3: Validation Layer (High Risk)

   • Goal: Translate Symfony constraints to Laravel validation rules.
   • Steps:
     1. Create custom validation