Jérémy DECOOL (@jdecool), Ingénieur Etudes et Développement à Lyon

Profile your PHPUnit tests using OpenTelemetry

Mon, 01 Jun 2026 00:00:00 +0200

When your project grows, the codebase grows and your test suite too. The more the test you write, the longer the execution is. And then, the Allowed memory size exhausted error occurred in your CI. To solve this issue quickly, you bump PHP allocated memory. But it doesn’t fix the problem, and this cycle goes on for a while. Until you hit critical thresholds.

Fixing memory issues is really difficult, and there are not many tools to help. We need to retrieve information about our test executions. Monitoring a production application is a known good practice. So why this is not applied to our test code?

The OpenTelemetry emerged those years. It could be useful to use it in our context to produce traces and metrics about our test suite.

I’ve recently discovered the flow-php/phpunit-telemetry-bridge library. It brings observability to our PHPUnit tests using OpenTelemetry. The library consists of a PHPUnit extension that collects some data and sends them to any OTLP-compatible backend.

Start using it by installing the component using Composer:

composer require --dev flow-php/phpunit-telemetry-bridge

Then add the telemetry configuration into PHPUnit:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit>
    <!-- ... -->
    <extensions>
        <bootstrap class="Flow\Bridge\PHPUnit\Telemetry\TelemetryExtension">
            <parameter name="service_name" value="phpunit-opentelemetry"/>
            <parameter name="transport" value="curl"/>
            <parameter name="endpoint" value="http://localhost:4318"/>
            <parameter name="emit_traces" value="true"/>
            <parameter name="emit_metrics" value="true"/>
            <parameter name="emit_test_spans" value="true"/>
            <parameter name="emit_test_case_spans" value="true"/>
            <parameter name="curl_connect_timeout_ms" value="1000"/>
            <parameter name="curl_timeout_ms" value="2000"/>
        </bootstrap>
    </extensions>
</phpunit>

After that, every time your tests are run, the library will send the telemetry backend. Then you can create some dashboards to visualize the data:

Data contains execution details like duration, memory consumption, executed tests, etc.

When using observability in your stack, don’t forget that instrumenting every test can be expensive. Use it when you really need it.

Want to get more information? Check out the PHPUnit Telemetry bridge documentation.

Execute CTE queries using Doctrine ORM

Sat, 09 May 2026 00:00:00 +0200

There are a lot of developers who manipulate databases using an ORM and don’t know more SQL than the “classic” SELECT ... FROM ... WHERE ... queries. But databases have various unknown features that can avoid programing data processing. One of them is CTE (for Common Table Expressions).

This article describes how to use this feature with PHP Doctrine ORM.

First, let me explain what a CTE is. A Common Table Expression (CTE) is a named temporary result set that you define at the beginning of a SQL query using the WITH clause. It exists only for the duration of that query and can be referenced like a table within it.

To illustrate how it works, imagine a blog where articles can be stored and attached to one category. Categories are organized in a tree structure. Now, we want to retrieve a specific category with all its parents. The naïve PHP implementation can be something like:

// src/Repository/CategoryRepository.php
class CategoryRepository extends ServiceEntityRepository
{
    // ...

    /**
     * @return list<Category>
     */
    function getCatagoriesWithParents(int $categoryId): array
    {
        $category = $this->categoryRepository->find($categoryId);

        $categories = [
            $category,
        ];

        while ($parent = $category->getParent()) {
            $categories[] = $parent;
        }

        return $categories;
    }
}

With the previous version, Doctrine will execute one query per loop: it’s the common N+1 problem. To resolve this issue through an SQL query, we can’t use a basic query. We need a recursive CTE. This SQL query can look like:

WITH RECURSIVE cte_category AS (
    -- starting point
    SELECT id, label, parent_id, 0 AS depth
    FROM category
    WHERE id = :id

    UNION ALL

    -- recursivity
    SELECT c.id, c.label, c.parent_id, cp.depth + 1
    FROM category c
    INNER JOIN cte_category cp ON c.id = cp.parent_id
)
SELECT id, label, parent_id FROM cte_category
ORDER BY depth DESC

First, the previous query retrieves the :id category. Then, recursively, it retrieves all the parents. The depth column is used to order the final result.

The problem with this kind of SQL query is that Doctrine is not able to execute them natively. We can’t use the QueryBuilder or a DQL (Doctrine Query Language) query. We need to execute a native query and map the result on an object.

// src/Repository/CategoryRepository.php
class CategoryRepository extends ServiceEntityRepository
{
    // ...

    public function findAllWithParents(int $categoryId)
    {
        $rsm = new ResultSetMappingBuilder($this->getEntityManager());
        $rsm->addRootEntityFromClassMetadata(Category::class, 'c');

        $sql = <<<SQL
            WITH RECURSIVE with_categories AS (
                SELECT id, label, parent_id, 0 AS depth
                FROM category
                WHERE id = :id

                UNION ALL

                SELECT c.id, c.label, c.parent_id, cp.depth + 1
                FROM category c
                INNER JOIN with_categories cp ON c.id = cp.parent_id
            )
            SELECT id, label, parent_id FROM with_categories
            ORDER BY depth DESC
        SQL;

        return $this->getEntityManager()
            ->createNativeQuery($sql, $rsm)
            ->setParameter('id', $categoryId)
            ->getResult();
    }
}

In the previous code, the ResultSetMappingBuilder maps the query results to the Category entity object properties. The output will be a list of Category ordered by ancestors.

This kind of query allows a lot of things. For example, we can retrieve every post of a specific category, including the category parents:

WITH RECURSIVE category_path AS (
    SELECT id, label, parent_id
    FROM category
    WHERE id = :id

    UNION ALL

    SELECT c.id, c.label, c.parent_id
    FROM category c
    INNER JOIN category_path cp ON c.id = cp.parent_id
)
SELECT a.id, a.title, a.category_id
FROM article a
INNER JOIN category_path cp ON a.category_id = cp.id
ORDER BY a.published_date DESC

With only one query, every post is retrieved. Without a recursive CTE, multiple successive queries will be necessary. The drawback is it depends on the database engine and could not be available in some databases.

Moreover, using the ResultSetMappingBuilder requires all columns needed to hydrate the entity should be included in the SELECT. Otherwise, the entity will be partially hydrated without any explicit notice or error.

Named constructors as multiple constructors alternative

Tue, 28 Jan 2025 00:00:00 +0100

Unlike other programming languages, PHP does not allow for multiple constructors in a class. However, defining multiple constructors can be beneficial in various scenarios, such as creating an object from different data types. If this functionality is not available in PHP, named constructors can be used as an alternative solution.

What is a named constructor? It is a static method that we can use to create an object instance. These methods have the advantage of being more explicit than the basic constructor, as they can add meaning to the object’s construction.

Consider the following example:

readonly class Color
{
    public function __construct(
        public int $red,
        public int $blue,
        public int $green,
    ) {}
}

The previous code defines an object that stores a color. This color consists of three levels: red, green and blue. The main constructor fills in these corresponding values. However, sometimes it may be useful to create a color from its hexadecimal value. In this case, we could introduce a constructor called fromHexCode to do this task:

readonly class Color
{
    public static function fromHexCode(string $code): self
    {
        $code = ltrim($code, '#');

        $red = hexdec(substr($code, 0, 2));
        $blue = hexdec(substr($code, 2, 2));
        $green = hexdec(substr($code, 4, 2));

        return new self($red, $blue, $green);
    }

    public function __construct(
        public int $red,
        public int $blue,
        public int $green,
    ) {}
}

Named constructors can simplify object creation by providing default values based on the context. They also encapsulate the complex creation logic, making the code easier to read and understand.

This technique is also popular in Domain Driven Design. It can help clarify the business process that led to the data creation. For example, consider user registration in an application:

class User
{
    public static function fromRegistration(string $name, string $email, string $password): self
    {
        $user = new self($name, $email, $password);

        // additionnal business logic related to registration

        return $user;
    }

    public static function fromSocialLogin(string $name, string $email): self
    {
        $user = new self($name, $email);

        // additionnal business logic related to social login

        return $user;
    }

    private function __construct(
        public string $name,
        public string $email,
        public ?string $password = null,
    ) {}
}

This last example introduces a User class with a private constructor. To create an object instance, a named constructor must be used. The constructor choice will depend on the business context. This approach allows us to see user creation requirements depends on a specific use case.

When a user registers via the application, it should provide a name, an email and a password. However if the same user is logged through a social login, we only need the name and the email. The password is not necessary when using an external login system.

In summary, using named constructors can significantly improve the code base and enhance code readability. I highly recommend that you explore this technique as it under-exploited.

How to use PHPUnit 10 with Symfony

Tue, 10 Oct 2023 00:00:00 +0200

PHPUnit has been release 8 months ago (the 3rd of February 2023). But if we try to use it in a Symfony project using the symfony/phpunit-bridge component, a PHP Fatal error: Uncaught Error: Class "PHPUnit\TextUI\Command occurred.

PHP Fatal error:  Uncaught Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit:11
Stack trace:
#0 {main}
  thrown in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Fatal error: Uncaught Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Error: Class "PHPUnit\TextUI\Command" not found in /home/jdecool/Workspace/sandbox/test/bin/phpunit on line 11

Call Stack:
    0.0001     396248   1. {main}() /home/jdecool/Workspace/sandbox/test/bin/phpunit:0

The Symfony script tries to use a deleted PHPUnit class. While there are several PRs to fix the problem, but none are currently merged.

If you want to solve this issue, you can simply update the bin/phpunit file using this patch:

-    PHPUnit\TextUI\Command::main();
+    exit((new PHPUnit\TextUI\Application)->run($_SERVER['argv']));

How to use Chrome Headless with Behat

Mon, 08 May 2017 00:00:00 +0200

Headless Chrome is shipping in Chrome 59 (currently in beta), it seems that we can use the browser without UI. It is very interesting for testing and automated purpose. In this post, we are going to configure Behat (a PHP framework for autotesting your business expectations) to use Chrome in headless mode.

This new Chrome feature interest a large part of the Web community. So much, that the maintainer of PhantomJS, a headless browser which is also based on Webkit, announced the end of the project. So, if you used this in your Behat scenarios, you should change the browser you used.

This is an sample of the Behat configuration I use for PhantomJS :

# behat.yml
default:
    extensions:
        # ...
        Behat\MinkExtension:
            base_url: http://project.dev
            sessions:
                default:
                    selenium2:
                        wd_host: http://localhost:4444/wd/hub

Now we have to make some change to be able to use Chrome browser. First, we have to add the ChromeDriver. Next, we need to add some configuration directory in our behat.yml file :

# behat.yml
default:
    extensions:
        # ...
        Behat\MinkExtension:
            base_url: http://project.dev
            sessions:
                default:
                    selenium2:
                        browser: chrome
                        wd_host: http://localhost:4444/wd/hub
                        capabilities:
                            chrome:
                                switches:
                                    - "--headless"
                                    - "--disable-gpu"

There are some little changes if the configuration file. We begin by defining the browser we want to use. Then we set up some capabilities (options that can add to customize and configure our Chrome session). We add the --headless argument to use the headless mode in combination to --disable-gpu which is temporarily needed for now.

Et voilà ! By adding 5 lines of configuration we have replaced the PhantomJS browser usage by Google Chrome with “headless” mode.

The full configuration file is available on Gist