A collection of reusable value objects written in PHP and targeting versions 5.6 and above.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
doctrine/mapping
src
tests
.gitignore
.scrutinizer.yml
.travis.yml
CONTRIBUTING.md
LICENSE.md
README.md
composer.json
composer.lock
phpunit.xml

README.md

DDD Embeddables


Build Status Scrutinizer Code Quality Code Coverage

A collection of reusable value objects written in PHP and targeting versions 5.6 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 5.1.6 by Sebastian Bergmann and contributors.

...........                 11 / 11 (100%)

Time: 269 ms, Memory: 7.25Mb

OK (39 tests, 71 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.