biberlabs / ddd-embeddables
A collection of re-usable value objects ready to use as Embeddable in Doctrine entities
Installs: 237
Dependents: 0
Suggesters: 0
Security: 0
Stars: 66
Watchers: 8
Forks: 10
Open Issues: 3
Requires
- php: ^8.0
- composer-runtime-api: ^2
- doctrine/orm: ^2.11
Requires (Dev)
- phpunit/phpunit: ^9.5
Suggests
- ext-gmp: Calculate without integer limits
- ext-intl: Format Money objects with intl
This package is not auto-updated.
Last update: 2024-11-15 22:29:59 UTC
README
A collection of reusable value objects written in PHP and targeting versions 8.0 and above. Value objects are essential building blocks of Domain Driven Design approach and described by Martin Fowler in P of EAA page 486 as below:
"Value object is a small simple object, like money or a date range, whose equality isn't based on identity."
– Martin Fowler
All classes in this library annotated as ORM\Embeddable
with appropriately adjusted column attributes. This makes them ready to use in any project with Doctrine ORM as Embeddables.
Installation & Usage
Install the library using composer.
$ composer require biberlabs/ddd-embeddables
and use it in your entities:
<?php namespace MyApp\Entity; use Doctrine\ORM\Mapping as ORM; use DDD\Embeddable\EmailAddress; /** * @ORM\Entity */ class User { /** * @ORM\Embedded(class="DDD\Embeddable\EmailAddress") */ private $email; // Returns an EmailAddress instance, not a string public function getEmail(); // Use type-hinting if you need a setter public function setEmail(EmailAddress $email); }
Afterwards, you can write custom DQL queries based on your requirements while accessing properties of the value objects such as:
SELECT u FROM User u WHERE u.email = :email -- OR SELECT p FROM Payments p WHERE p.total.currency = :currency SELECT p FROM Payments p WHERE p.total.amount > 1000 -- OR SELECT u FROM User u WHERE u.name.surname = :surname SELECT u FROM User u WHERE u.name.title = :title
Value objects enables us to write much more cleaner and readable rules when dealing with the domain rules, application-wide. For example:
$username = $user->getEmail()->getLocalpart();
or
$blacklist = ['spam4me.io', 'foo.com']; if(in_array($user->getEmail()->getDomain(), $blacklist)) { // ... }
even
if($company->hasMap()) { $latLng = $company->getAddress()->getGeoPoint()->toArray(); //.. } class Company { // ... /** * Returns a boolean TRUE if the geolocation of the company is known, * FALSE otherwise. * * @return bool */ public function hasMap() { return $this->getAddress()->getGeoPoint() !== null; } }
Running Tests
You can run unit tests locally via issuing the command below:
$ composer test
Please make sure that all test are green before creating a PR.
PHPUnit 9.5.25 #StandWithUkraine
................................................................. 65 / 75 ( 86%)
.......... 75 / 75 (100%)
Time: 00:00.037, Memory: 6.00 MB
OK (75 tests, 124 assertions)
Contributing
If you want to contribute to ddd-embeddables and make it better, your help is very welcome.
Please take a look our CONTRIBUTING.md before creating a pull request.
Further Reading
Are you interested in Domain Driven Design? Here is a list of good resources to dig in-depth.
- Value Objects - Martin Fowler
- Separating Concerns using Embeddables - Doctrine ORM documentation
- Domain-Driven Design in PHP - Leanpub 380 pages e-book.
- Agregate Componenet Pattern In Action - Another good article from 2009
- Domain Driven Design Concepts in ZF2 - An article written by Oleg Krivtsov in 2014
- Domain Driven Design Quickly - A quickly-readable minibook and introduction to the fundamentals of DDD by InfoQ.