- How do I create a custom value object for my domain (e.g., a `Percentage` type)?
- Extend the base `ValueObject` class and define your invariants in the constructor or a static factory method. For example, enforce that percentages must be between 0 and 100. Use the `assert` method to validate inputs during instantiation. The package provides helpers for type safety and immutability out of the box.
- Can I use this package with Laravel Eloquent models? If so, how?
- Yes. Use Eloquent casts to convert between database storage (e.g., JSON or strings) and your value objects. For Laravel 8+, leverage attribute casting for cleaner syntax. Example: `protected $casts = ['email' => Email::class];`. The package includes built-in support for JSON serialization/deserialization for complex types.
- What Laravel versions does this package support, and are there breaking changes?
- The package supports Laravel 7, 8, and 9+. Laravel 9+ users benefit from native attribute casting, reducing boilerplate. Breaking changes are minimal; most updates focus on PHP 8+ features (e.g., named arguments). Always check the changelog for version-specific notes before upgrading.
- How do I validate value objects in Laravel Form Requests or API requests?
- Use static factory methods like `Email::from($request->input('email'))` in your validation logic. The package includes custom validation rules (e.g., `validatesAsEmail`) to integrate with Laravel’s validation pipeline. For APIs, serialize value objects via `JsonSerializable` or Laravel’s `Resource` classes.
- Does this package work with database migrations? How do I store value objects like `Money` or `UUID`?
- Store value objects in JSON columns or as strings, depending on complexity. For `Money`, use a JSON column to preserve `amount` and `currency`. For `UUID`, store as a string. The package provides Eloquent casts to automatically convert between storage formats and value objects during model hydration.
- Is there a performance overhead for using value objects instead of primitives?
- Minimal overhead for most use cases. Value objects add validation and immutability checks during instantiation, but comparisons and serialization are optimized. Benchmark critical paths (e.g., API responses) if latency is a concern. The package avoids deep cloning or unnecessary copies to keep performance predictable.
- How do I test value objects in Laravel? Can I mock them in unit tests?
- Use PHPUnit’s mocking or data providers to test edge cases (e.g., invalid `Email` formats). Immutable objects simplify testing by eliminating side effects. For integration tests, hydrate value objects from fixtures or database records. The package’s strict validation makes it easy to catch invalid states early in tests.
- What’s the difference between a value object and an entity in DDD, and when should I use this package?
- Value objects describe *what* (e.g., `Email`, `Money`) without identity, while entities have identity (e.g., `User`, `Order`). Use this package for domain types with invariants (e.g., `Percentage`, `Url`) where primitives like strings or integers are insufficient. Avoid it for entities or complex behaviors requiring lifecycle methods.
- Are there alternatives to this package for Laravel value objects? How does it compare?
- Alternatives include `spatie/value-object` (more generic) or `moneyphp/money` (for financial types). This package is Laravel-specific, with built-in Eloquent, validation, and API serialization support. It’s lighter than Spatie’s but offers deeper Laravel integration. Choose based on whether you need framework-agnostic flexibility or Laravel-native features.
- How do I migrate an existing Laravel app to use value objects without breaking production?
- Start with new features, then refactor incrementally. Use accessors/mutators as temporary bridges (e.g., `getEmailAttribute()`). For databases, update migrations to support JSON or string storage. Test thoroughly in staging, and use feature flags to roll out changes gradually. The package’s immutability reduces risk of state corruption during migration.