- How do I install apie/common-value-objects in a Laravel project?
- Run `composer require apie/common-value-objects` in your project root. Ensure your Laravel version (9+/10+) supports PHP 8.1+ for full enum and named argument features. Resolve any dependency conflicts (e.g., with `ramsey/uuid`) using Composer overrides if needed.
- Can I use these value objects with Laravel Eloquent models?
- Yes, but with discipline. Replace raw database columns (e.g., `uuid` VARCHAR) with immutable value objects like `UuidV4` or `Slug`, then update migrations to store/serialize them. For Eloquent models, bind interfaces to implementations in a service provider or use auto-discovery.
- What Laravel versions are supported by apie/common-value-objects?
- The package requires PHP 8.1+, which aligns with Laravel 9/10+. Older Laravel versions (e.g., 8.x) may need polyfills for enums or named arguments, but full compatibility isn’t guaranteed. Test thoroughly in your environment.
- How do I create custom value objects (e.g., for a User’s email)?
- Extend the base classes (e.g., `Stringable` for emails) or create new ones. For identifiers, implement `IdentifierInterface` and specify the referenced entity class. Example: `class UserEmail extends Stringable {}`—then use it in your domain logic.
- Will these value objects work with Laravel’s validation system?
- Not natively, but you can extend Laravel’s validator or create custom rules. For example, validate `DateTimeRange` by checking `start < end` in a `Validator::extend()` rule. Form Requests may need manual handling unless you build adapters.
- Are there performance concerns with serializing value objects in APIs?
- Yes, serialization/deserialization (e.g., UUIDs, enums) adds overhead. Optimize by implementing `__toString()`/`fromString()` methods or caching frequently used objects. Benchmark in your Laravel API to identify bottlenecks.
- How do I migrate existing data to use these value objects (e.g., converting string UUIDs to UuidV4)?
- Use a migration to backfill data: `User::query()->update(['uuid' => UuidV4::fromString($row->uuid)])`. For complex cases, write a data seeder or console command. Ensure your database schema matches the value object’s storage format (e.g., `Stringable` traits).
- What alternatives exist for Laravel value objects?
- Consider `spatie/uuid` for UUID handling, `moneyphp/money` for monetary values, or `symfony/uid` for generic identifiers. For DDD, `ddd-php/value-object` offers a more generic approach. Choose based on your need for Apie ecosystem integration.
- How do I enforce immutability in Laravel controllers when using these value objects?
- Leverage PHP’s immutability (e.g., `readonly` properties in PHP 8.1+) and avoid setters. Use constructor injection for value objects and validate inputs early (e.g., in Form Requests). Document the pattern in your team’s coding standards.
- Can I use these enums (e.g., Gender) directly in Laravel Blade templates or API responses?
- Yes, enums render as strings by default (e.g., `Gender::MALE->value`). For Blade, use `@php echo $gender->value @endphp` or cast to string. In APIs, ensure JSON serialization works via `__toString()` or custom JSON encoders.