Value Object Contracts Laravel Package

Product Decisions This Supports

• Domain-Driven Design (DDD) Adoption: Enables strict typing and validation for business entities (e.g., User, Order, Payment) via value objects (immutable, self-validating objects like Email, Money, DateRange). Aligns with DDD’s focus on modeling core domain logic.
• API Contracts & Schema Evolution: Reduces ambiguity in API payloads by enforcing validation rules at the object level (e.g., Email must be RFC-compliant). Supports backward-compatible schema changes without breaking clients.
• Build vs. Buy: Avoids reinventing validation logic (e.g., custom EmailValidator classes) or relying on third-party libraries like Symfony Validator for domain-specific rules. Lightweight alternative to Laravel Nova or Filament for internal tooling.
• Use Cases:
  • E-commerce: Validate ProductPrice, InventoryQuantity, or ShippingAddress as value objects.
  • Finance: Enforce Currency + Amount rules (e.g., no negative values, valid ISO codes).
  • SaaS: Standardize user input (e.g., SubscriptionPlan, ApiKey) across microservices.
  • Legacy Modernization: Gradually introduce DDD patterns to monolithic PHP apps.

When to Consider This Package

• Avoid If:
  • Your team lacks DDD experience or needs quick prototyping (overhead of defining contracts may not justify benefits).
  • You’re using Laravel’s built-in validation (e.g., Validator facade) for simple forms—this package is not a replacement for request validation.
  • Your stack is non-PHP (e.g., Node.js, Python) or uses frameworks with native DDD support (e.g., Ruby’s ActiveModel::Validations).
  • You need database persistence—this is for in-memory objects; pair with Eloquent or Doctrine ORM separately.
• Consider If:
  • You’re building domain-rich applications (e.g., fintech, healthcare) where data integrity is critical.
  • Your team values explicit contracts over dynamic validation (e.g., "an Email must always validate before use").
  • You want to decouple validation logic from frameworks (e.g., reuse Money objects in CLI tools, queues, or APIs).
  • You’re adopting Laravel 10+ and want to leverage enhanced PHP 8.2+ features (e.g., array_key_first, str_contains).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us write once, validate everywhere—think of it like ‘TypeScript for PHP business logic.’ For example, instead of trusting a frontend form to send a valid email, we enforce Email::fromString() at the code level. This reduces bugs in critical flows (e.g., payments, user onboarding) and makes our APIs more predictable for partners. The MIT license means no vendor lock-in, and the lightweight design avoids adding bloat to our stack."

ROI:

• Fewer production bugs from invalid data.
• Faster onboarding for new devs (clear contracts > magic strings).
• Future-proofing for microservices or multi-team collaboration.

For Engineering:

*"This is a minimalist DDD toolkit for PHP/Laravel. Key benefits:

• No ORM dependency: Works with raw arrays, Eloquent, or custom storage.
• Composability: Chain value objects (e.g., Order → Money → Currency).
• Performance: Zero runtime overhead for valid objects (validation happens once on creation).
• Laravel-friendly: Integrates with Form Requests, API resources, and tests.

Example Use Case:

// Instead of:
$email = $_POST['email']; // Risky!
// Do:
$email = Email::fromString($_POST['email']); // Throws \InvalidArgumentException if invalid.

Trade-offs:

• Requires discipline to adopt (e.g., replacing string with Email everywhere).
• Not a silver bullet—pair with Laravel Policies for authorization and Pest/PHPUnit for testing.

Next Steps:

1. Pilot: Use for 1–2 high-risk domain objects (e.g., PaymentAmount).
2. Document: Add a CONTRIBUTING.md section for new devs.
3. Extend: Build custom value objects (e.g., Slug, Hashtag)."*