Value objects represent meaningful values with validation and value-based semantics rather than mutable identities.
The examples below begin with the core behavior, then move to an application-oriented use.
How Implementing Value Objects Works
Value objects represent meaningful values with validation and value-based semantics rather than mutable identities.
Example 1: Basic Usage
This example uses a small input to make the main behavior visible.
<?php
final readonly class Quantity { public function __construct(public int $count) { if ($count < 1) { throw new InvalidArgumentException("Quantity must be positive"); } } }
echo (new Quantity(3))->count;Output:
3Value objects represent meaningful values with validation and value-based semantics rather than mutable identities.
Example 2: A Different Input
A different set of values shows the same operation in another situation.
<?php
final readonly class Percentage { public function __construct(public float $value) { if ($value < 0 || $value > 100) { throw new RangeException("Out of range"); } } }
echo (new Percentage(25))->value;Output:
25Enforce invariants in the constructor and prefer immutable properties so invalid states cannot be introduced later.
Practical Example: Applying the Feature
This example shows an application-style use of the feature, with its surrounding setup visible.
<?php
final readonly class EmailAddress { public function __construct(public string $value) { if (!filter_var($value, FILTER_VALIDATE_EMAIL)) { throw new InvalidArgumentException("Invalid address"); } } }
$email = new EmailAddress("[email protected]");
echo $email->value;Output:
[email protected]The code is shown for learning. Adjust the class names, inputs and error handling to suit your application.
Important Behavior and Edge Cases
- Enforce invariants in the constructor and prefer immutable properties so invalid states cannot be introduced later.
- Value objects represent meaningful values with validation and value-based semantics rather than mutable identities.
- Observe differences in empty inputs, invalid states and optional extension availability where relevant.
Comparison With Related Approaches
| Approach | Important Difference |
|---|---|
Implementing Value Objects | Value objects represent meaningful values with validation and value-based semantics rather than mutable identities. |
| Alternative approach | Primitive strings are flexible but do not encode constraints like valid email addresses or positive quantities. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
Ignoring the documented state or precondition of Implementing Value Objects | Enforce invariants in the constructor and prefer immutable properties so invalid states cannot be introduced later. |
| Expecting a different type of result | Read the declared return type and distinguish returned values from changes to the source object. |
| Assuming a related API works identically | Primitive strings are flexible but do not encode constraints like valid email addresses or positive quantities. |
Key Takeaways
- Value objects represent meaningful values with validation and value-based semantics rather than mutable identities.
- Enforce invariants in the constructor and prefer immutable properties so invalid states cannot be introduced later.
- Use the example that matches the values, runtime version and dependencies in your application.
Implementing Value Objects is useful when its behavior matches the data structure and lifecycle of your PHP application. Choose it with a clear understanding of its preconditions and returned values.