Polish Extensions Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require taveo/polish-extensions-bundle:dev-master
   

   Note: The package is in dev-master; pin a specific commit if stability is critical.

2. Enable the Bundle in app/AppKernel.php:

   public function registerBundles()
   {
       return [
           // ...
           new Taveo\PolishExtensionsBundle\TaveoPolishExtensionsBundle(),
       ];
   }
   

3. First Use Case: Validate a PESEL Annotate a property in your entity:

   use Taveo\PolishExtensionsBundle\Validator\Constraints as TaveoAssert;
   
   class User
   {
       /**
        * @TaveoAssert\PESEL
        */
       private $pesel;
   }
   

   Symfony’s validator will now automatically validate PESEL format (11 digits, checksum, date plausibility).

Implementation Patterns

Common Workflows

1. Form Validation Bind constraints to form fields (Symfony 2.x style):

   $builder->add('nip', 'text', [
       'constraints' => [
           new TaveoAssert\NIP(),
       ],
   ]);
   

2. Programmatic Validation Use the validator directly in services/controllers:

   $validator = $this->get('validator');
   $errors = $validator->validate($entity, [
       new TaveoAssert\REGON(),
   ]);
   

3. Custom Error Messages Override translations in config/validator/validation.yml:

   Taveo\PolishExtensionsBundle\Validator\Constraints\PESEL:
       message: "Invalid PESEL. Must be 11 digits with valid checksum."
   

4. Dynamic Validation Combine with Symfony’s Callback constraint for runtime checks:

   use Symfony\Component\Validator\Constraints\Callback;
   
   $constraint = new Callback([
       'callback' => [$this, 'validateDynamicPesel'],
   ]);
   

Integration Tips

• Doctrine ORM: Works seamlessly with @Assert\Valid on entity relationships.
• API Platform: Add constraints to DTOs for automatic validation.
• Legacy Code: Use ValidatorBuilder to inject constraints into existing validators.

Gotchas and Tips

Pitfalls

1. Bundle Compatibility

   • Targets Symfony 2.1+. Avoid with Symfony 3+ (use symfony/validator directly if needed).
   • No Symfony 4/5 support; fork or rewrite constraints for newer versions.

2. Validation Logic Quirks

   • PESEL: Rejects dates outside 1900–2099 by default (adjust with minYear/maxYear options if needed).
   • NIP: Strict format (e.g., 1234567890 fails; must include - or space, e.g., 123-456-78-90).
   • REGON: No built-in length flexibility; hardcoded to 9 digits.

3. Translation Overrides

   • Default translations are in Resources/translations/validators.pl.yml. Override all languages (pl/en/de) to avoid missing keys.

Debugging

• Enable Validator Debugging:

  # config.yml
  framework:
      validation:
          cache: false  # Disable cache to see raw errors
  

• Check Constraint Names: Use getName() on constraints to match translations:

  $constraint = new TaveoAssert\NIP();
  echo $constraint->getName(); // "Taveo\PolishExtensionsBundle\Validator\Constraints\NIP"
  

Extension Points

1. Custom Constraints Extend AbstractPolishConstraint to add new validators (e.g., KRS):

   class KRS extends AbstractPolishConstraint
   {
       protected function validateRegex($value) {
           return preg_match('/^[0-9]{10}$/', $value);
       }
   }
   

2. Event Listeners Hook into validator.build_constraint to modify constraints dynamically:

   // src/AcmeBundle/EventListener/ValidatorListener.php
   public function onBuildValidator(FilterValidatorEvent $event) {
       $constraints = $event->getConstraintMap();
       $constraints['Acme\Entity'][] = new TaveoAssert\REGON(['strict' => true]);
       $event->setConstraintMap($constraints);
   }
   

3. Testing Mock constraints in PHPUnit:

   $validator = $this->getMockBuilder('Taveo\PolishExtensionsBundle\Validator\Constraints\PESEL')
       ->disableOriginalConstructor()
       ->getMock();