320 lines
10 KiB
Plaintext
320 lines
10 KiB
Plaintext
# Aggregate Fields
|
|
|
|
You will is often the requirement to display aggregate values of data that
|
|
can be computed by using the MIN, MAX, COUNT or SUM SQL functions. Doctrine 2
|
|
offers several ways to get access to these values and this article will
|
|
describe all of them from different perspectives.
|
|
|
|
You will see that aggregate fields can become very explicit
|
|
features in your domain model and how this potentially complex business rules
|
|
can be easily tested.
|
|
|
|
## An example model
|
|
|
|
Say you want to model a bank account and all their entries. Entries
|
|
into the account can either be of positive or negative money values.
|
|
Each account has a credit limit and the account is never allowed
|
|
to have a balance below that value.
|
|
|
|
For simplicity we live in a world were money is composed of integers
|
|
only. Also we omit the receiver/sender name, stated reason for transfer
|
|
and the execution date. These all would have to be added on the `Entry`
|
|
object.
|
|
|
|
Our entities look like:
|
|
|
|
[php]
|
|
namespace Bank\Entities;
|
|
|
|
/**
|
|
* @Entity
|
|
*/
|
|
class Account
|
|
{
|
|
/** @Id @GeneratedValue @Column(type="integer") */
|
|
private $id;
|
|
|
|
/** @Column(type="string", unique=true)
|
|
private $no;
|
|
|
|
/**
|
|
* @OneToMany(targetEntity="Entry", mappedBy="entries", cascade={"persist"})
|
|
*/
|
|
private $entries;
|
|
|
|
/**
|
|
* @Column(type="integer")
|
|
*/
|
|
private $maxCredit = 0;
|
|
|
|
public function __construct($no, $maxCredit = 0)
|
|
{
|
|
$this->no = $no;
|
|
$this->maxCredit = $maxCredit;
|
|
$this->entries = new \Doctrine\Common\Collections\ArrayCollection();
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @Entity
|
|
*/
|
|
class Entry
|
|
{
|
|
/** @Id @GeneratedValue @Column(type="integer") */
|
|
private $id;
|
|
|
|
/**
|
|
* @ManyToOne(targetEntity="Account", inversedBy="entries")
|
|
*/
|
|
private $account;
|
|
|
|
/**
|
|
* @Column(type="integer")
|
|
*/
|
|
private $amount;
|
|
|
|
public function __construct($account, $amount)
|
|
{
|
|
$this->account = $account;
|
|
$this->amount = $amount;
|
|
// more stuff here, from/to whom, stated reason, execution date and such
|
|
}
|
|
|
|
public function getAmount()
|
|
{
|
|
return $this->amount;
|
|
}
|
|
}
|
|
|
|
## Using DQL
|
|
|
|
The Doctrine Query Language allows you to select for aggregate values computed from
|
|
fields of your Domain Model. You can select the current balance of your account by
|
|
calling:
|
|
|
|
[php]
|
|
$dql = "SELECT SUM(e.amount) AS balance FROM Bank\Entities\Entry e " .
|
|
"WHERE e.account = ?1";
|
|
$balance = $em->createQuery($dql)
|
|
->setParameter(1, $myAccountId)
|
|
->getSingleScalarResult();
|
|
|
|
The `$em` variable in this (and forthcoming) example holds the Doctrine `EntityManager`.
|
|
We create a query for the SUM of all amounts (negative amounts are withdraws) and
|
|
retrieve them as a single scalar result, essentially return only the first column
|
|
of the first row.
|
|
|
|
This approach is simple and powerful, however it has a serious drawback. We have
|
|
to execute a specific query for the balance whenever we need it.
|
|
|
|
To implement a powerful domain model we would rather have access to the balance from
|
|
our `Account` entity during all times (even if the Account was not persisted
|
|
in the database before!).
|
|
|
|
Also an additional requirement is the max credit per `Account` rule.
|
|
|
|
We cannot reliably enforce this rule in our `Account` entity with the DQL retrieval
|
|
of the balance. There are many different ways to retrieve accounts. We cannot
|
|
guarantee that we can execute the aggregation query for all these use-cases,
|
|
let alone that a userland programmer checks this balance against newly added
|
|
entries.
|
|
|
|
## Using your Domain Model
|
|
|
|
`Account` and all the `Entry` instances are connected through a collection,
|
|
which means we can compute this value at runtime:
|
|
|
|
[php]
|
|
class Account
|
|
{
|
|
// .. previous code
|
|
public function getBalance()
|
|
{
|
|
$balance = 0;
|
|
foreach ($this->entries AS $entry) {
|
|
$balance += $entry->getAmount();
|
|
}
|
|
return $balance;
|
|
}
|
|
}
|
|
|
|
Now we can always call `Account::getBalance()` to access the current account balance.
|
|
|
|
To enforce the max credit rule we have to implement the "Aggregate Root" pattern as
|
|
described in Eric Evans book on Domain Driven Design. Described with one sentence,
|
|
an aggregate root controls the instance creation, access and manipulation of its children.
|
|
|
|
In our case we want to enforce that new entries can only added to the `Account` by
|
|
using a designated method. The `Account` is the aggregate root of this relation.
|
|
We can also enforce the correctness of the bi-directional `Account` <-> `Entry`
|
|
relation with this method:
|
|
|
|
[php]
|
|
class Account
|
|
{
|
|
public function addEntry($amount)
|
|
{
|
|
$this->assertAcceptEntryAllowed($amount);
|
|
|
|
$e = new Entry($e, $amount);
|
|
$this->entries[] = $e;
|
|
return $e;
|
|
}
|
|
}
|
|
|
|
Now look at the following test-code for our entities:
|
|
|
|
[php]
|
|
class AccountTest extends \PHPUnit_Framework_TestCase
|
|
{
|
|
public function testAddEntry()
|
|
{
|
|
$account = new Account("123456", $maxCredit = 200);
|
|
$this->assertEquals(0, $account->getBalance());
|
|
|
|
$account->addEntry(500);
|
|
$this->assertEquals(500, $account->getBalance());
|
|
|
|
$account->addEntry(-700);
|
|
$this->assertEquals(-200, $account->getBalance());
|
|
}
|
|
|
|
public function testExceedMaxLimit()
|
|
{
|
|
$account = new Account("123456", $maxCredit = 200);
|
|
|
|
$this->setExpectedException("Exception");
|
|
$account->addEntriy(-1000);
|
|
}
|
|
}
|
|
|
|
To enforce our rule we can now implement the assertion in `Account::addEntry`:
|
|
|
|
[php]
|
|
class Account
|
|
{
|
|
private function assertAcceptEntryAllowed($amount)
|
|
{
|
|
$futureBalance = $this->getBalance() + $amount;
|
|
$allowedMinimalBalance = ($this->maxCredit * -1);
|
|
if ($futureBalance < $allowedMinimalBalance) {
|
|
throw new Exception("Credit Limit exceeded, entry is not allowed!");
|
|
}
|
|
}
|
|
}
|
|
|
|
We haven't talked to the entity manager for persistence of our account example before.
|
|
You can call `EntityManager::persist($account)` and then `EntityManager::flush()`
|
|
at any point to save the account to the database. All the nested `Entry` objects
|
|
are automatically flushed to the database also.
|
|
|
|
[php]
|
|
$account = new Account("123456", 200);
|
|
$account->addEntry(500);
|
|
$account->addEntry(-200);
|
|
$em->persist($account);
|
|
$em->flush();
|
|
|
|
The current implementation has a considerable drawback. To get the balance, we
|
|
have to initialize the complete `Account::$entries` collection, possibly a very
|
|
large one. This can considerably hurt the performance of your application.
|
|
|
|
## Using an Aggregate Field
|
|
|
|
To overcome the previously mentioned issue (initializing the whole entries collection)
|
|
we want to add an aggregate field called "balance" on the Account and adjust the
|
|
code in `Account::getBalance()` and `Account:addEntry()`:
|
|
|
|
[php]
|
|
class Account
|
|
{
|
|
/**
|
|
* @Column(type="integer")
|
|
*/
|
|
private $balance = 0;
|
|
|
|
public function getBalance()
|
|
{
|
|
return $this->balance;
|
|
}
|
|
|
|
public function addEntry($amount)
|
|
{
|
|
$this->assertAcceptEntryAllowed($amount);
|
|
|
|
$e = new Entry($e, $amount);
|
|
$this->entries[] = $e;
|
|
$this->balance += $amount;
|
|
return $e;
|
|
}
|
|
}
|
|
|
|
This is a very simple change, but all the tests still pass. Our account entities return
|
|
the correct balance. Now calling the `Account::getBalance()` method will not occour the
|
|
overhead of loading all entries anymore. Adding a new Entry to the `Account::$entities`
|
|
will also not initialize the collection internally.
|
|
|
|
Adding a new entry is therefore very performant and explictly hooked into the domain model.
|
|
It will only update the account with the current balance and insert the new entry into the database.
|
|
|
|
## Tackling Race Conditions with Aggregate Fields
|
|
|
|
Whenever you denormalize your database schema race-conditions can potentially lead to
|
|
inconsistent state. See this example:
|
|
|
|
[php]
|
|
// The Account $accId has a balance of 0 and a max credit limit of 200:
|
|
// request 1 account
|
|
$account1 = $em->find('Bank\Entities\Account', $accId);
|
|
|
|
// request 2 account
|
|
$account2 = $em->find('Bank\Entities\Account', $accId);
|
|
|
|
$account1->addEntry(-200);
|
|
$account2->addEntry(-200);
|
|
|
|
// now request 1 and 2 both flush the changes.
|
|
|
|
The aggregate field `Account::$balance` is now -200, however the SUM over all
|
|
entries amounts yields -400. A violation of our max credit rule.
|
|
|
|
You can use both optimistic or pessimistic locking to save-guard
|
|
your aggregate fields against this kind of race-conditions. Reading Eric Evans
|
|
DDD carefully he mentions that the "Aggregate Root" (Account in our example)
|
|
needs a locking mechanism.
|
|
|
|
Optimistic locking is as easy as adding a version column:
|
|
|
|
[php]
|
|
class Amount
|
|
{
|
|
/** @Column(type="integer") @Version */
|
|
private $version;
|
|
}
|
|
|
|
The previous example would then throw an exception in the face of whatever request
|
|
saves the entity last (and would create the inconsistent state).
|
|
|
|
Pessimmistic locking requires an additional flag set on the `EntityManager::find()`
|
|
call, enabling write locking directly in the database using a FOR UPDATE.
|
|
|
|
[php]
|
|
use Doctrine\DBAL\LockMode;
|
|
|
|
$account = $em->find('Bank\Entities\Account', $accId, LockMode::PESSIMISTIC_READ);
|
|
|
|
## Keeping Updates and Deletes in Sync
|
|
|
|
The example shown in this article does not allow changes to the value in `Entry`,
|
|
which considerably simplifies the effort to keep `Account::$balance` in sync.
|
|
If your use-case allows fields to be updated or related entities to be removed
|
|
you have to encapsulate this logic in your "Aggregate Root" entity and adjust
|
|
the aggregate field accordingly.
|
|
|
|
## Conclusion
|
|
|
|
This article described how to obtain aggregate values using DQL or your domain model.
|
|
It showed how you can easily add an aggregate field that offers serious performance
|
|
benefits over iterating all the related objects that make up an aggregate value.
|
|
Finally I showed how you can ensure that your aggregate fields do not get out
|
|
of sync due to race-conditions and concurrent access. |