DEV Community: Andrea Sprega

Entity repositories for humans: part 1

Andrea Sprega — Sun, 18 Feb 2024 18:34:35 +0000

TL;DR: this article describes a pattern for creating entity repositories that we use at Slope, but first it explains other strategies that we previously explored and discarded. If you're only interested in the outcome, you can look directly at the GitHub repository.

Fetching entities from a database is a necessity that pretty much every web application has. In case of fairly structured applications, this often happens through the use of repositories (if you have never heard of the repository pattern this is a pretty good introduction).

If you use Doctrine ORM, most likely you have already used its repositories. In case you're not familiar with them, you can get an idea by looking at the examples in the documentation.

NOTE: as Slope is built using Symfony, the approach described here is based on Doctrine. If you use Laravel, however, it should be possible to use the same approach also with Eloquent, with a few adaptations, by building some abstraction around its query builders.

The starting point

As the business domain becomes more complicated, properties and relationships between entities increase. With them, the queries that you need to fulfill the use cases of your application become increasingly more complex.
With necessities increasing over time, you will probably need to switch from default Doctrine repositories to custom ones. The moment you cross that line, a world of different possibilities/implementations opens up.

At Slope we constantly strive for the best possible developer experience. This case made no exception: we wanted an approach that was elegant, easy to use but at the same time flexible and that left room for optimizations when our DBMS (PostgreSQL) needed them.

Let's go step by step: before presenting our current solution, it makes sense to mention the various approaches that we have tried previously.

Approach #1: standard Doctrine repositories with magic methods

This is most likely the first approach that you discover once you start working with Doctrine.
By default, Doctrine provides repository classes in which you don't have to implement any method. You can just use their dynamic interfaces that define several findBy*, findOneBy*, countBy* methods based on entity metadata, i.e. it "adds" one method for each property and one for each association defined on its entity. Note that these methods are not statically defined, but implemented dynamically by Doctrine via a __call method. The official documentation describes them here.

You can find this approach implemented in branch approach-1.

Pros:

You can use them out of the box.

Cons:

It is only possible to filter by the properties defined by the entity, so it only works with rather simple models.
Combining more than one filter is very cumbersome.
The fact that repositories use magic methods with associative arrays as parameters makes this approach quite "obscure"; the resulting DX is pretty bad, as you don't have autocompletion: discovering and debugging these methods is not exactly a breeze.

Magic is nice. Just not in your repositories.

Approach #2: standard Doctrine repositories using Criteria

The same repositories described above can also be queried via Criteria objects. These objects represent specific filters (and/or combinations of them) and can be passed to the repository in order to extract matching entities. You can find more information about them here.

This approach is demonstrated in branch approach-2.

Pros:

Criteria objects can be used interchangeably with repositories and entity collections for filtering.
Criteria are highly composable and use much less "magic" than the previous approach.
Client classes that use this approach are forced to know the internal details of the entity about how attributes and relationships are defined (because they work directly with the attribute and association names). Any optimizations, workarounds to Doctrine limitations or denormalizations can no longer be kept “secret”, and it will be necessary to modify all clients if, for example, the name of an attribute or an association changes.

Cons:

The approach is super verbose and impractical. The more filters you need, the worse the situation becomes.
Criteria objects are very cumbersome to mock in unit tests.

Approach #3: standard Doctrine repositories with custom `findBy*` methods

At some point we decided that complexity was too much, and we started implementing our findBy*/countBy* methods, one for each combination of filters we needed to fulfill our use cases.
Each of these methods constructs its own query builder, applies its filtering logic and produces a specific result. These methods can be parametrizable as for the relationship that have to be joined in advance, plus all the various possible orderings.

branch approach-3 shows this last intermediate approach.

Pros:

Very simple to use for client classes, because they just need a simple method call with just a few parameters (often just one).
Mocking these methods in unit tests is very simple, a one-liner in most cases.

Cons:

Every method is extremely specific and does not scale well when complexity increases. We often ended up with dozens of findBy* methods per repository, due to the combinatorial explosion of needed filters.
As every method composes its own query builder, this pattern inevitably causes code duplication in repositories, especially if you are not diligent enough to factor common filtering logic across multiple methods.
During development, when you have to add a new use case, you are often in doubt when deciding whether to complicate an existing method maybe with additional parameters, or to write a new method from scratch.

There must be a better way!

None of the approaches described above felt "good": the cons were always prevailing on the pros. We wanted something better, ideally based on this wishlist:

Repositories should be classes with "clean" interfaces (i.e. no Doctrine specific public methods)
They should be dead simple to use (and to mock), ideally with just a single method call (no chaining allowed!) and a single parameter.
They should guarantee complete shielding of storage/implementation details of entities: the query builder must never leave the repositories, and Doctrine Criteria are not accepted. This way, when changing internal details of an entity, you just need to change code inside its repository and not in other classe.
You should not need to implement a new method every time you add a new filter to an existing entity. Adding parameters to existing methods is not acceptable either, because it complicates the interfaces and scales poorly as the filter combinations grow.
There should be a handy way of prefetching relationships (to avoid the infamous N+1 problem).
Possibility of paginating results without changing how client classes query the repository.
Support for composition via subqueries.

Over time and after various contributions by many team members, we got to define a pretty good pattern that checked all the items in the checklist above.

We are happy to share the results, hoping that it can be useful for others as well. For this purpose, we created a GitHub repository with a living example of it, that will evolve when we publish more article on this series.

Before you ask: the example in our repository is based on a simple domain for managing a video rental shop. You know, we're just a bunch of nostalgic millennials.

Disclaimer: Running a movie rental shop in 2024 may not be the best business idea.

Introducing the “entity query”

The fundamental idea behind this solution is that each repository has a "companion" class, which we will call entity query.
Entity queries are in fact simple DTOs that must be instantiated providing filters by classes that need to fetch entities from repositories.

They are convenient to create because every filter has its named parameter in the query constructor. All of them are nullable: this means that regardless of the combination of filters you want to apply, you can always build an entity query inline and specify only the filters that you are interested in, in any order you want.

Conceptually speaking, all the filters are applied in logical AND with each other to produce the result set. This is a pretty strong simplification, but it works well for us because we still manage to cover most of our typical use cases with it.

I like to say that a few lines of code are better than a thousand words, so here are excerpts of the Rental entity and its entity query present in the master branch of the GitHub repository:

#[ORM\Entity]
class Rental
{
    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'NONE')]
    #[ORM\Column('id', type: 'guid')]
    public readonly string $id;

    #[ORM\ManyToOne(targetEntity: Movie::class)]
    #[ORM\JoinColumn('movie_id')]
    public readonly Movie $movie;

    #[ORM\ManyToOne(targetEntity: Customer::class)]
    #[ORM\JoinColumn('customer_id')]
    public readonly Customer $customer;

    #[ORM\Column('rent_date', type: 'datetimetz_immutable')]
    public readonly \DateTimeImmutable $rentDate;

    #[ORM\Column('return_date', type: 'datetimetz_immutable', nullable: true)]
    private ?\DateTimeImmutable $returnDate = null;

    // ...
}

class RentalQuery extends AbstractEntityQuery
{
    public const ORDER_BY_RENT_DATE_DESC = 'RENT_DATE_DESC';

    public function __construct(
        public ?Movie $movie = null,
        public ?Customer $customer = null,
        public ?\DateTimeImmutable $rentDateGreaterThan = null,
        public ?\DateTimeImmutable $rentDateLessThanOrEqualTo = null,
        public ?bool $returned = null,
        array $orderBy = [],
    ) {
        parent::__construct($orderBy);
    }
}

And here are a few examples of how this entity query can be used:

$repository->executeForCount(
    new RentalQuery(customer: $aCustomer)
);

$repository->executeForManyResults(
    new RentalQuery(
        rentDateGreaterThan: new \DateTimeImmutable('8 days ago'),
        returned: false,
    )
);

$repository->executeForFirstOrNullResult(
    new RentalQuery(
        movie: $aMovie,
        orderBy: [RentalQuery::ORDER_BY_RENT_DATE_DESC]
    )
);

The public interface of an entity repository

Repositories feature a set of method that work with entity queries plus some other methods that perform unfiltered counts and fetches, as well as fetches by id.
Note that the same entity query can be used both to get the results hydrated as entities and to get their counts. Here is an excerpt from the public interface:

/**
 * Base class for entity repositories.
 * @template E of object
 * @template Q of AbstractEntityQuery
 */
abstract class AbstractEntityRepository
{
    /**
     * Returns a count of all entities.
     */
    public function countAll(): int;

    /**
     * Executes the entity query returning the count of matching results.
     *
     * @param Q $entityQuery
     */
    public function executeForCount(AbstractEntityQuery $query): int;

    /**
     * Executes the entity query returning only the first result (or null if no results found).
     *
     * @param Q $entityQuery
     * @return ?E
     */
    public function executeForFirstOrNullResult(AbstractEntityQuery $entityQuery): ?object;

    /**
     * Executes the entity query returning many results (optionally limited using $limit parameter).
     *
     * @param Q $entityQuery
     * @return E[]
     */
    public function executeForManyResults(AbstractEntityQuery $entityQuery, ?int $limit = null): array;

    /**
     * Executes the entity query expecting zero or one result.
     *
     * @param Q $entityQuery
     * @return ?E
     * @throws NonUniqueResultException If more than one entity matches the query.
     */
    public function executeForOneOrNullResult(AbstractEntityQuery $entityQuery): ?object;

    /**
     * Executes the entity query expecting exactly one result.
     *
     * @param Q $entityQuery
     * @return E
     * @throws NonUniqueResultException If more than one entity matches the query.
     * @throws NoResultException If no entity matching the query is found.
     */
    public function executeForSingleResult(AbstractEntityQuery $entityQuery): object;

    /**
     * Returns all entities.
     *
     * @return E[]
     */
    public function findAll(): array;

    /**
     * Returns a single entity by ID.
     *
     * @return E
     * @throws \Doctrine\ORM\NoResultException
     * @throws \Doctrine\ORM\NonUniqueResultException
     */
    public function findByID(string $id): object;

    /**
     * Returns multiple entities by their IDs.
     *
     * @param string[] $ids
     * @return E[]
     */
    public function findByIDs(array $ids): array;
}

It is important to note that concrete repositories do not need to define new public methods to fetch entities: they just need to implement their own logic to configure the Doctrine query builder based on the provided entity query. Here's the code fragment that does this for RentalRepository:

/**
 * @extends AbstractEntityRepository<Rental, RentalQuery>
 */
class RentalRepository extends AbstractEntityRepository
{
    // ...

    protected function configureBuilderFromEntityQuery(QueryBuilder $builder, AbstractEntityQuery $query): QueryBuilder
    {
        /* Validation */

        if ($query->rentDateLessThanOrEqualTo !== null) {
            Assertion::lessThan(
                $query->rentDateGreaterThan,
                $query->rentDateLessThanOrEqualTo,
                'rentDateGreaterThan cannot be greater than rentDateLessThanOrEqualTo.'
            );
        }

        /* Filtering */

        if ($query->movie !== null) {
            $builder->andWhere('e.movie = :movie')->setParameter('movie', $query->movie);
        }

        if ($query->customer !== null) {
            $builder->andWhere('e.customer = :customer')->setParameter('customer', $query->customer);
        }

        if ($query->rentDateLessThanOrEqualTo !== null) {
            $builder->andWhere('e.rentDate <= :rentDateLessThanOrEqualTo')
                ->setParameter('rentDateLessThanOrEqualTo', $query->rentDateLessThanOrEqualTo);
        }

        if ($query->rentDateGreaterThan !== null) {
            $builder->andWhere('e.rentDate > :rentDateGreaterThan')
                ->setParameter('rentDateGreaterThan', $query->rentDateGreaterThan);
        }

        if ($query->returned === true) {
            $builder->andWhere('e.returnDate IS NOT NULL');
        } elseif ($query->returned === false) {
            $builder->andWhere('e.returnDate IS NULL');
        }

        /* Ordering */

        foreach ($query->orderBy as $orderBy) {
            switch ($orderBy) {
                case RentalQuery::ORDER_BY_RENT_DATE_DESC:
                    $builder->addOrderBy('e.rentDate', 'DESC');
                    break;
                default:
                    throw new \Exception("Unknown order by: $orderBy");
            }
        }


        return $builder;
    }
}

Limitations

The greatest limitation of this approach is that, as already mentioned, all filters work with each other only in an AND fashion. So, if you set two properties on an entity query, only entities that match both filters will be returned.

However, it is always possible to overcome this limitation by defining "virtual" properties that correspond to more complex filters to be implemented in the repository (for example, two properties in OR). We will discuss this in detail in a future post.

Another limitation is that if you need to filter on a property using N different operators, you must define N different filters on the same property.
Looking at the code above, $rentDateGreaterThan and $rentDateLessOrEqualTo are an example of this limitation.
We believe that this is a reasonable price to pay for not having to complicate the construction of the query too much. In case this is a problem, though, it is still possible to implement "operator" classes to use in entity queries. We are not currently doing this, but as this is a possible evolution we might talk about this in a future post.

There’s more to come!

The approach just described here is just a simplified version of the one we actually use in production at Slope.

There are still many interesting missing pieces, which we planned to add and describe in future articles. In the next episodes we will talk about:

Filters with virtual properties
Filters based on associated entities
Support for multi-tenancy
Prefetching associations
Pagination of results
Subqueries

Make sure to star the GitHub repository to not miss the updates we will make as new articles in this series get published.

We are eager to hear your opinions. Feel free to contact us (engineering <at> slope.it), via Github or by leaving comments below!

A library-less approach to fixtures in PHP tests

Andrea Sprega — Sat, 08 Jan 2022 12:30:09 +0000

At Slope, writing tests is a relevant part of our day to day work. Having to maintain many integrations and end to end (functional) tests, we are continuously required to create and manage fixtures.

For those who are not familiar with fixtures: quite simply, they are stable, pre-defined sets of data that you persist to a database and then use to run a specific test.

State of the art (and why we questioned it)

There are several great open source libraries that can help you doing this job. We tried out some of them, including:

They all work well for a lot of use cases, but we found ourselves always having to write too much code for preparing fixtures. Moreover, most of these libraries have their own unique ways to share, compose and reuse fixtures. In most cases it's reference-based (i.e. based on arbitrary string keys), and this makes reusing and composing these fixtures harder than it has to be.

We often had the impression there was too much over-engineering over this task, which instead could be simpler.
That's why we came up with our own (almost) vanilla approach, based on a few design goals. We will see actual code in a few minutes, but before let's see what that "design wishlist" looked like.

Design goals for our ideal fixture system

In the next few lines, I'm going to enumerate and briefly explain the design goals that we kept in consideration while building our fixture system. Note that these are only based on our experience -- your mileage may vary.

Fixtures should have stable defaults

Fixtures are not seeds! As long as you want stable, reproducible tests, you should rely on static defaults for your fixtures. You don't want your default user name to change pseudo-randomly across your tests.

Simple fixtures should require little code

If you just need some placeholder entities and you don't care what their properties are, creating them should require very little coding effort -- ideally, one line per fixture.

It should be clear which defaults you are overriding

Just by looking at the fixture code, it should be obvious which entity property defaults you are overriding. In other words, if your user email needs to be giuseppeverdi@gmail.com instead of the default mariorossi@gmail.com, you should be able to do that without having to re-define all the other properties for the User fixture, like for example first or last name.
While being convenient, this is also great because it highlights that specific property and value as the sole pre-condition of your test. If you had to also define a bunch of other properties just to "make the fixture work", then you would lose this kind of clarity.

Every test should have its own fixture

Even though most libraries suggest to create fixtures as a reusable, pre-defined group of related entities, in most cases we did not actually want that.
We found out that by avoiding shared fixtures between tests, our test suite became simpler, more stable and more maintainable.

Fixture code should be inline with test case

A natural consequence of the previous principle is that code for creating a fixture is written directly in the body of the test case. This is great because you can clearly see the connection between your fixtures, the test actions and the assertions. This means that, at a glance, you can understand what's going on without looking anywhere else in your codebase.

Fixtures should be easily composable

As we don't want to reuse pre-defined group fixtures, we need a way to compose single entity fixtures that is not cumbersome and can be done "on-the-fly", directly in the test case where we need that.
We figured out we could achieve that simply by using objects returned by the fixture class itself. The price to pay for this is that a fixture class can only create one object at a time (and that's perfectly reasonable in our case, as we don't need a ton of data for our tests).

Fixtures should be able to reuse business logic when needed

In case creating a specific entity involves some business logic that lives outside of the entity class itself, it should be possible to leverage your services while creating a fixture, so that you can enforce your logic without having to duplicate it.

Our approach to fixtures

Enough talking, let's jump right into some code that shows an example of what we came up with.

We use Symfony and Doctrine, so you will see there are dependencies on these two projects. The important thing, though, is the approach: you can adapt the provided samples to your ORM (and framework) of choice.

The FixtureManager

The starting point of all of this is a FixtureManager: basically a convenience class with a bunch of static methods that provides persistence capabilities and an accessible service container to fixture classes.

I know what you're thinking: we're not fans of hardcoded dependencies via static methods either. However, since this is just testing code, we think it's best to favor convenience over everything else. After all, this is not code we have to test.

Fixture classes

Then, we create a class for every entity we need fixtures for. Here I'm showing just one of them (others are similar). Actual entity classes are not shown because they are pretty simple and not relevant to this example -- it's just constructor and basic setters and getters.

The important part of it is the create method signature: it should be different for each fixture class, and should get as parameters:

1) All the required ones first: we try to avoid them as much as possible, but sometimes they are needed. For example, a User always requires to specify a Tenant as it's not convenient to just create one if not provided. Reason is we almost always reuse the same tenant for a number of entities in the same test (in this example, User and UserGroup).
2) A $fields parameter, which is just an associative array which shape differs fixture from fixture, and can be used to override the default fixture values.

Most of the convenience of this approach is based on Symfony's OptionsResolver. If you don't know it, I suggest to take a look at the documentation but assuming you don't want to switch right now, let me summarize it for you: OptionsResolver is array_replace on steroids, that allows you to produce an array by using a set of defaults as a basis plus the ones you specify either statically or dynamically (i.e. by executing a closure). It also performs validation of the provided keys, throwing exceptions in case an unknown key is provided.

This is super useful because you'll get an immediate failure when attempting to use, in the $fields array, a key that is not defined in the fixture class. This way, you don't have to curse when trying to override a firstName default by passing it in a firstname key 🤯.

It is also super easy to create dynamic defaults. In case of UserFixture's 'group' property, a UserGroup will be created only in case it's not provided from the outside. This because OptionsResolver only executes the closure if the corresponding value is not already provided.

If you want to take it to the next level, you can also tell OptionResolver to validate types of the provided values. In this case I don't think it's worth the extra code as, if you have strongly typed entities (I hope you do!) you will quickly get TypeErrors anyway.

NOTE: you can install OptionsResolver even if you don't use Symfony as full stack framework.

An example TestCase class

Note: I'm using three fixtures here just to show how we compose them. I chose not to show snippets of TenantFixture and UserGroupFixture as they wouldn't add anything new to the example.

Wrapping up

As you could see from the examples, this is not a library but just a set of classes and conventions that can be applied without many pre-requisites.
This approach is battle-tested: we use it in our codebase for hundreds of test cases and it helped us a lot in keeping the fixtures complexity at a minimum.

Feel free to copy-paste and tailor these snippets to your codebase.

What do you think? Any feedback would be greatly appreciated!

ClockMock: a library to mock date and time in PHP

Andrea Sprega — Thu, 09 Dec 2021 15:30:16 +0000

If you write tests for your code (I hope you do), at some point you likely needed something to execute them with the system clock “frozen” to a specific date and time. Whoever had this need at least once knows that the matter is anything but trivial.

With this article, I want to tell the story of how we dealt with this problem at Slope. For doing this, I will use the following “codebase” (i.e. a pompous way to describe 2 classes — an entity and a service).

Our example codebase, using just vanilla PHP.

I will describe 3 testing scenarios (a, b. and c.) that pretty much cover 100% of our cases/needs. Your mileage may vary, but the same concepts should apply.

Our journey starts from a situation in which we simply accepted to test the following scenarios in a sub-optimal way — or to not test them at all.

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Our “basic” go-to solution here was reflection, used to artificially modify the date (stored in a private instance property) right after calling the entity constructor. Example:

Scenario a. at the beginning of our story

Scenario b: test services that behave differently based on periods of the day/month/year

In such situations, we usually avoided to test these services altogether. In some other cases, we modified code to allow passing the current date as a parameter. We did not like making this kind of changes, because at that point you don’t know anymore whether the current date is effectively a parameter even in “production” usage, or it was made that way only for testing.

I’m not embedding any code for this scenario, because as the beginning it was simply untestable.

Scenario c: test services that set a specific date to an object with state, e.g. an entity

In the past, we worked around this by testing that the date set by the service was “close enough” to the current date (e.g. within 500 milliseconds), with the assumption that the assertion was made shortly after SUT code execution.

Scenario c. at the beginning of our story

It’s obvious that this kind of checks makes tests less precise, flaky and subject to failures in slow machines or environments with fluctuating computational resources (like in most CI environments).

As you are probably thinking, these solutions are pretty far from being ideal. Let’s be honest: they just suck. So, one day we decided we needed to make our codebase a better place and we started looking for alternatives.

Our first try: Carbon

As with every refactoring, we started with the lowest hanging fruit (in terms of complexity). We tried Carbon, a great library for handling dates that also allows mocking the current date used when you create Carbon|CarbonImmutable objects. In simple words, you can just do a Carbon::setTestNow($now) to freeze the current time (or use the stateless counterpart Carbon::withTestNow($now, $closure)).

As you would expect, our codebase needed some changes, and here they are:

Our example codebase, modified to use Carbon.

NOTE: I did not modify the use of DateTimeImmutable in Service::doSomething method, because I wanted to simulate use of 3rd party code outside of our control that thus cannot be changed to use Carbon.

After the codebase refactoring, we are immediately able to improve some of our scenarios:

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Fixture preparation for scenario a. using Carbon

Scenario b: test services that behave differently based on periods of the day/month/year

Because we decided we could not use Carbon in Service::doSomething, we still cannot test that scenario.

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Test for scenario c. using Carbon

Except the refactoring (that takes time, even though Carbon should pretty much be a drop-in replacement of DateTime), it was very easy to configure as it’s just a library you install with Composer.

There are a couple of drawbacks with this approach, though:

Any system function or class/method (e.g. date(), time(), DateTime, …) will still use the actual system clock, so it’s impossible to force code outside of your control to use your mocked date and time.
Your “business” code (entities and services) will have a hard dependency against Carbon (instead of sticking with the standard DateTime). This is not necessarily an issue, but it becomes relevant if you, like us, strive to keep exposure of your business logic to 3rd party libraries to the minimum.

ext/timecop to the (temporary) rescue

Due to the above limitations, at some point we decided we wanted to improve our situation and we came across ext/timecop. This is basically a fork of its most famous Ruby counterpart, and thus is based on the same concept: mock the system clock via a PHP runtime extension, so that all running code uses it transparently (regardless of the library).

It’s simple: you invoke \timecop_freeze($date) in your test code to bring the system clock to that specific moment. You then use \timecop_return() (still in your test code) when you want to go back to the actual system clock.

NOTE: from here on, we go back to referring to the initial codebase, the one without Carbon.

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Fixture preparation for scenario a. using timecop

Scenario b: test services that behave differently based on periods of the day/month/year

Test for scenario b. using timecop

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Test for scenario c. using timecop

Great! We can go back to using stdlib, uninstall Carbon, and still test everything.

The price you have to pay, is that you need to be able to compile and install a php extension yourself. This might not be possible when you don’t have full control on your environment, like in shared hosting spaces -even though I hope you’re not running production applications there!

Anyway, we were happy and life was good. At least, until the day to update to PHP 8.0 came. That day, we found out that ext/timecop would NOT compile anymore.

The day got even worse when, after going to the GitHub repo and looking at the issue tracker, we realized that the project was abandoned.

Timecop is dead. Long live ClockMock!

We really liked the concept behind timecop, but we were forced to move on if we didn’t want to be stuck with PHP 7.4 forever. As writing and maintaining a PHP extension was outside of our possibilities, we had to find a different solution.

One day, I stumbled on a not-so-popular PHP extension: ext/uopz. It allows to modify, at runtime, implementations of methods and functions, including the ones of the standard library. Kudos to its author Joe Watkins and contributors for the amazing job!

The idea of building a time-mocking library on top of it came pretty naturally -- I immediately hacked together a proof of concept that only dealt with mocking \DateTime instances. The POC was working, and so we gave it a name and we expanded it to cover all the time-related code that PHP provided (with the help of other contributors). ClockMock was born!

ClockMock does mainly 2 things whenever mocks are activated by the developer:

Overwrites implementation of many date and time-related functions with ones that the current time can be manipulated.
Overwrites implementation of \DateTime and \DateTimeImmutable with the ones of mock classes that consider the aforementioned mockable clock.

These implementations are reverted to their original versions whenever mocks are deactivated, so that there are no unintended side effects after using it.

DISCLAIMER: due to its “experimental” nature, we recommend to never use ClockMock in production.

You can use ClockMock with two different APIs:

a stateful one, in which you need to balance inline calls to activate and reset mocks (like timecop)
a stateless one, that will execute a closure at a specific point in time. It does not have side effects, as the original clock is always automatically restored.

Let’s see how the 3 scenarios can be rewritten with ClockMock:

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Fixture preparation for scenario a. using ClockMock

Scenario b: test services that behave differently based on periods of the day/month/year

Test for scenario b. using ClockMock

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Test for scenario c. using ClockMock

Possible alternative: inject a ClockInterface service

You might be thinking that a more “standard” way of solving this problem would be to inject a ClockInterface service that provides a way to obtain the current time (I also learned there’s a proposed standard for it). This way, the current time would be mockable like any other service.

This is definitely a valid approach. Problem is, in rather complex projects (not necessarily legacy) the current time is going to be needed in a wide range of places/classes. Furthermore, sometimes you may even need to get a \DateTime or a timestamp from a 3rd party library and that would “escape” your ClockInterface service (in case it’s impossible to make it interoperate with said library).

While it’s definitely doable to inject a Clock service in anything you manage using a DI container, it’s a lot less pragmatic to do the same for your value objects and/or entities.

When you need to create \DateTime objects right inside entities (in constructor or mutator methods) it would be cumbersome having to pass a Clock from the outside every time. Sometimes, use of dates could even be a private implementation detail — having to pass a clock service from the outside would leak this detail unnecessarily and make the public interface more complex.

In other words, the reason why we built this library is that we think it’s a good tradeoff to consider the current system time as a “global state”, and we prefer to avoid injecting a service to access it.

For this reason, I think that this injection-based approach only makes sense when you have valid reasons for doing it besides testing (e.g. very time-sensitive applications for which you need control over subtle details, like monotonic wall time, leap second smearing, etc…).

Our application is not time sensitive, we only needed a way to mock the system clock in tests. If your needs are the same and you can afford to use ClockMock, you can start using it with zero changes to production code.

Conclusions

As you can see from the examples above, using ClockMock feels pretty much the same as using timecop (with a bonus: the syntactic sugar of executeAtFrozenDateTime). It works with PHP 8 already, and the good thing is that the uopz extension is well maintained, so ClockMock is here to stay. We encourage you to use it and report any issues or feedback you may have.

The library is still incomplete, as mocks for some functions are missing. Just let us know if you want to help, contributions are welcome!

You can find the library on GitHub.

DEV Community: Andrea Sprega

Entity repositories for humans: part 1

The starting point

Approach #1: standard Doctrine repositories with magic methods

Approach #2: standard Doctrine repositories using Criteria

Approach #3: standard Doctrine repositories with custom findBy* methods

There must be a better way!

Introducing the “entity query”

The public interface of an entity repository

Limitations

There’s more to come!

A library-less approach to fixtures in PHP tests

State of the art (and why we questioned it)

Design goals for our ideal fixture system

Fixtures should have stable defaults

Simple fixtures should require little code

It should be clear which defaults you are overriding

Every test should have its own fixture

Fixture code should be inline with test case

Fixtures should be easily composable

Fixtures should be able to reuse business logic when needed

Our approach to fixtures

The FixtureManager

Fixture classes

An example TestCase class

Wrapping up

ClockMock: a library to mock date and time in PHP

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Scenario b: test services that behave differently based on periods of the day/month/year

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Our first try: Carbon

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Scenario b: test services that behave differently based on periods of the day/month/year

Scenario c: test services that set a specific date to an object with state, e.g. an entity

ext/timecop to the (temporary) rescue

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Scenario b: test services that behave differently based on periods of the day/month/year

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Timecop is dead. Long live ClockMock!

Scenario a: alter the creation date of an entity when preparing fixtures for integration tests

Scenario b: test services that behave differently based on periods of the day/month/year

Scenario c: test services that set a specific date to an object with state, e.g. an entity

Possible alternative: inject a ClockInterface service

Conclusions

Approach #3: standard Doctrine repositories with custom `findBy*` methods