Dothiv Valueobject Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require dothiv/dothiv-valueobject-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Dothiv\ValueObjectBundle\DothivValueObjectBundle::class => ['all' => true],
   ];
   

2. First Use Case Import and use a built-in value object (e.g., Email):

   use Dothiv\ValueObjectBundle\ValueObject\Email;
   
   $email = new Email('user@example.com');
   // Automatically validates format on instantiation
   

3. Where to Look First

   • Documentation: Check src/ValueObject/ for available value objects (e.g., Email, Money, PhoneNumber).
   • Tests: Browse tests/ for usage examples and edge cases.
   • Symfony Docs: Reference Symfony’s Value Object pattern for context.

Implementation Patterns

Core Workflows

1. Validation on Instantiation Use built-in value objects to enforce invariants:

   $phone = new PhoneNumber('+1234567890'); // Throws \InvalidArgumentException if invalid
   

2. Immutable Data Handling Treat value objects as immutable:

   $money = new Money(100, 'USD');
   // $money->amount = 200; // Fails (no setter)
   

3. Integration with Doctrine Use ValueObjectType for database storage (if extended):

   // Example: Custom Doctrine mapping (if supported)
   $builder->add('email', ValueObjectType::class, [
       'valueObjectClass' => Email::class,
   ]);
   

4. Custom Value Objects Extend the base AbstractValueObject:

   use Dothiv\ValueObjectBundle\ValueObject\AbstractValueObject;
   
   class Username extends AbstractValueObject
   {
       public function __construct(string $value)
       {
           $this->assertValid($value, function($v) {
               return strlen($v) >= 3 && preg_match('/^[a-zA-Z0-9_]+$/', $v);
           });
           $this->value = $value;
       }
   }
   

5. Serialization Use __toString() or jsonSerialize() for interoperability:

   $email = new Email('test@example.com');
   echo $email; // "test@example.com"
   

Common Use Cases

• Domain Modeling: Represent business entities (e.g., OrderId, UserId).
• API Requests/Responses: Validate incoming data (e.g., ApiToken).
• Configuration: Store immutable settings (e.g., CacheTTL).

Gotchas and Tips

Pitfalls

1. No Built-in Doctrine Support

   • The bundle does not include Doctrine types out of the box. Use a third-party library like Gedmo/DoctrineExtensions or create custom mappings.

2. Limited Documentation

   • The README and tests are sparse. Reverse-engineer from src/ or tests (e.g., EmailTest.php).

3. Archived Status

   • The package is archived (no active maintenance). Fork or extend locally if critical.

4. Validation Logic

   • Custom value objects require manual validation in __construct(). Use assertValid() helper:

     $this->assertValid($value, fn($v) => $v > 0, 'Value must be positive');
     

Debugging Tips

• Validation Errors: Catch \InvalidArgumentException for invalid inputs.
• Type Safety: Use instanceof checks when accepting value objects:

  if ($arg instanceof Email) { ... }
  

Extension Points

1. Add New Value Objects Place custom classes in src/ValueObject/ (or a sub-namespace) and autoload them.

2. Override Defaults Extend AbstractValueObject to modify behavior (e.g., serialization):

   class CustomEmail extends Email {
       public function __toString() { return strtoupper($this->value); }
   }
   

3. Integration with Symfony Forms Use ValueObjectType (if available) or create a custom form type:

   use Symfony\Component\Form\Extension\Core\Type\TextType;
   
   $builder->add('email', TextType::class, [
       'constraints' => [new EmailConstraint()],
   ]);
   

Performance Notes

• Immutable Objects: Avoid cloning or deep copies unless necessary (value objects are lightweight).
• Validation Overhead: Heavy validation in __construct() may impact performance. Cache results if reused (e.g., in DTOs).