Andreas Möller

Adopting a reasonable PHP version support policy

2023-09-12T07:00:00+02:00

Adopting a reasonable PHP version support policy

The fourth Thursday in November of every year is a special day for people working on and with PHP.

On that day, the release managers of PHP release a new major or minor PHP version. On that day, two years after its initial release, another PHP version reaches the end of active support. And on that day, three years after its initial release, another PHP version reaches the end of security support, and thus, its end of life.

If you work with PHP, whether you like it or not, you are subject to the lifecycle of a PHP version. If you work with PHP, the question for you is how you align yourself with the lifecycle of a PHP version.

A PHP version policy can help you with that.

PHP version support policy for PHP applications

If you build, maintain, and run a PHP application in production, you have control over the environment in which that PHP application runs. You decide which PHP version that application uses and whether and when you update to a new PHP version.

Typically, a PHP application runs on one PHP version only. If your PHP application supports more than one PHP version and you have control over the environment in which that PHP application runs, you would always prefer to run the PHP application on the newest PHP version, or would you not? Supporting more than one PHP version does not make sense for a PHP application unless you are not running it yourself.

A PHP version support policy for a PHP application states how you commit to updating that PHP application to a new PHP version in alignment with the lifecycle of a PHP version.

A PHP version support policy for a PHP application could state the following:

The maintainers of this application will update to a new major or minor PHP version within three months after its release.

Whether you find such a PHP version support policy reasonable depends on whether you and your team can update that PHP application to a new PHP version within three months. You can start with a more relaxed PHP version support policy and tighten it as you become better at maintaining your PHP application.

Updating to a new PHP version may require development work. If your PHP application currently uses a PHP version that has reached its end of active or security support, then that PHP application is already one or more major or minor PHP versions behind. If you do not know how to update your PHP application to a new PHP version but also do not plan to sunset that application or go out of business soon, get help like everyone else. There is no shame in accepting and admitting that you have painted yourself into a corner.

By adopting a PHP version support policy for your PHP application, you manage expectations for when stakeholders can expect you to update a PHP application to a new PHP version.

By committing to a PHP version support policy for your PHP application, you will more frequently update to a new PHP version.

By updating your PHP application more frequently to a new PHP version, you benefit from the upside and mitigate the downside of updating to a new PHP version as early as you can.

By adopting and committing to a PHP version support policy, you will become better at maintaining your PHP application. PHP version support policy for PHP packages If you build, maintain, and distribute a PHP package, you have limited control over the environments in which others consume that PHP package, but you can decide which PHP versions that PHP package supports.

Typically, a PHP package supports more than one PHP version. If people use that PHP package in a PHP application, they will have a much easier time updating their PHP application from one PHP version to another when they do not simultaneously have to update that PHP package. Instead, they probably want to update their PHP packages first, then update to a new PHP version. By supporting more than one PHP version, you make it easier for people using that PHP package to update to a new PHP version.

A PHP version support policy for a PHP package states how you commit to add and drop support for PHP versions in alignment with the lifecycle of a PHP version.

A PHP version support policy for a PHP package supporting two major or minor PHP versions could state the following:

The maintainers of this package add support for a PHP version following its initial release and drop support for a PHP version when it has reached its end of active support.

A PHP version support policy for a PHP package supporting three major or minor PHP versions could state the following:

The maintainers of this package add support for a PHP version following its initial release and drop support for a PHP version when it has reached its end of security support.

A PHP version support policy for a PHP package supporting four major or minor PHP versions could state the following:

The maintainers of this package add support for a PHP version following its initial release and drop support for a PHP version one year after it has reached its end of security support.

Whether you find a progressive or a more conservative PHP version support policy reasonable depends on your goals and maintenance budget. You can always relax your PHP version policy and tighten it when your goals change.

Adding support for a new PHP version close to its initial release to a PHP package may demonstrate that the package is well-maintained. If you fail to add support for a new PHP version to your PHP package, users may conclude that you have abandoned it.

Adding support for a new PHP version to a PHP package may require development work. If your PHP package supports many PHP versions, one of these PHP versions may have already deprecated a PHP feature that you use and rely on in that PHP package. The new PHP version may remove that PHP feature. Before you can add support, you must work around the removal of that PHP feature, which may include dropping support for a PHP version.

Adding support for a new PHP version to a PHP package may come prematurely. If people use your PHP package in other PHP packages, they will often ask to add support for a new PHP version as soon as the release managers of PHP create the branch for that PHP version - which is months before its initial release. Note that allowing users to install your PHP package on a PHP version differs from explicitly adding support for a PHP version. Using proper version constraints helps.

Dropping support for a PHP version without active or security support from a PHP package may also demonstrate that the package is well-maintained.

Dropping support for a PHP version from a PHP package may require some development work but will reduce the maintenance efforts for that PHP package. If your PHP package supports many PHP versions, you may have to manage multiple execution paths depending on the PHP version. If you drop support for a PHP version, you may be able to remove one or more of these execution paths.

Dropping support for a PHP version from a PHP package may reduce the environmental impact of that PHP package. If you support many PHP versions, you will need to run automated tests on all of these PHP versions in a continuous integration environment. By reducing the number of PHP versions you support, you reduce the number of test runs and the environmental impact of your PHP package.

Dropping support for a PHP version from a PHP package may allow you to use features present in newer PHP versions. If you support many PHP versions, you are limited to using the PHP features that are present in the lowest PHP version. You could use so-called polyfills, PHP packages that may partially or fully implement newer PHP features for older PHP versions. If you require polyfills in your PHP packages, the users of your PHP packages who do not need them may have to install or replace these polyfills in their PHP applications.

Dropping support for a PHP version may reduce the number of people who can use the latest version of that PHP package. If the latest version of that PHP package requires a PHP version that these people are unable or unwilling to update to, they can and will continue to use an older version of that PHP package. That may or may not be a problem, depending on what your PHP package does.

Dropping support for a PHP version may require persuasion. If you are one of many maintainers of a PHP package, you need to convince other maintainers that it is worth dropping support for a PHP version.

By adopting a PHP version support policy for your PHP package, you manage expectations for when users, contributors, and maintainers can expect you to add and drop support for a PHP version from your PHP package.

By committing to a PHP version support policy for your PHP package, you will more frequently drop support for a PHP version with less resistance from users, contributors, and maintainers.

By dropping support for PHP versions from your PHP package more frequently, you reduce the maintenance effort and environmental impact, you can use features of new PHP versions earlier, and last but not least, you increase the pressure on users of your PHP package to update their PHP applications to a new PHP version.

By increasing the pressure on users of your PHP package to update their PHP applications to a new PHP version, you become part of the tribe that moves the PHP ecosystem forward.

Have you adopted and committed to a PHP version support policy yet?

Understanding the lifecycle of a PHP version

2023-07-16T12:30:00+02:00

Understanding the lifecycle of a PHP version

You build, maintain, run, and distribute PHP applications and packages - but are you aware of the lifecycle of a PHP version?

Initial release

The initial release marks the beginning of the lifecycle of a PHP version.

Active support

Active support for a PHP version begins with the initial release and ends two years after the initial release.

During active support, maintainers fix bugs and security issues and release new patch versions.

The following PHP versions currently have active support:

PHP 8.3
- initial release on November 23, 2023
- active support ends on November 23, 2025
PHP 8.2
- initial release on December 8, 2022
- active support ends on December 8, 2024

💡 Also see the official list of supported PHP versions.

Security support

Security support for a PHP version begins with the end of active support and ends one year after the beginning of security support.

During security support, maintainers fix critical security issues and release new patch versions.

The following PHP versions currently have security support:

PHP 8.1
- initial release on November 25, 2021
- active support ended on November 25, 2023
- security support ends on November 25, 2024

End of life

The end of security support marks the end of the lifecycle of a PHP version.

PHP 8.0
- initial release on November 26, 2020
- active support ended on November 26, 2022
- security support ended on November 26, 2023
PHP 7.4
- initial release on November 28, 2019
- active support ended on November 28, 2021
- security support ended on November 28, 2022
PHP 7.3
- initial release on December 6, 2018
- active support ended on December 6, 2020
- security support ended on December 6, 2021
PHP 7.2
- initial release on November 30, 2017
- active support ended on November 30, 2019
- security support ended on November 30, 2020
PHP 7.1
- initial release on December 1, 2016
- active support ended on December 1, 2018
- security support ended on December 1, 2019
PHP 7.0
- initial release on December 3, 2015
- active support ended on January 4, 2018
- security support ended on January 10, 2019
PHP 5.6
- initial release on August 28, 2014
- active support ended on January 19, 2017
- security support ended on December 31, 2018
PHP 5.5
- initial release on June 20, 2013
- active support ended on July 10, 2015
- security support ended on July 21, 2016
PHP 5.4
- initial release on March 1, 2012
- active support ended on September 14, 2014
- security support ended on September 3, 2015
PHP 5.3
- initial release on June 30, 2009
- active support ended on July 11, 2013
- security support ended on August 14, 2014
PHP 5.2
- initial release on November 2, 2006
- active support ended on November 2, 2008
- security support ended on January 6, 2011
PHP 5.1
- initial release on November 24, 2005
- active support ended on November 24, 2007
- security support ended on August 24, 2006
PHP 5.0
- initial release on July 13, 2004
- active support ended on July 13, 2006
- security support ended on September 5, 2005
PHP 4.4
- initial release on July 11, 2005
- active support ended on July 11, 2007
- security support ended on August 7, 2008
PHP 4.3
- initial release on December 27, 2002
- active support ended on December 27, 2004
- security support ended on March 31, 2005
PHP 4.2
- initial release on April 22, 2002
- active support ended on April 22, 2004
- security support ended on September 6, 2002
PHP 4.1
- initial release on December 10, 2001
- active support ended on December 10, 2003
- security support ended on March 12, 2002
PHP 4.0
- initial release on May 22, 2000
- active support ended on May 22, 2002
- security support ended on June 23, 2001

💡 Also see the official list of unsupported PHP branches.

Are you currently running PHP versions in production that have reached their end of life?

Avoiding empty() in PHP

2023-05-10T15:40:00+02:00

Avoiding empty() in PHP

The language construct empty() appears rather versatile. It's like a Swiss army knife with a thousand blades, ready to hurt you if you grab it by the wrong end. Or a jack of all trades, master of none. Most of all, empty() is a poor communicator.

I spot empty() in poorly-aged closed-source projects. I discover empty() in brand-new closed-source projects from last week. And I meet empty() again in open-source projects with millions of downloads.

So what is the problem with empty() when so many people use it?

Problem

If you refer to the documentation for empty(), you will find the following:

Determine whether a variable is considered to be empty. A variable is considered empty if it does not exist or if its value equals false. empty() does not generate a warning if the variable does not exist.

PHP manual: empty()

If you ignore the internal implementation and possible performance issues, using empty() is identical to using isset() and a loose comparison with false.

 <?php

 declare(strict_types=1);

-if (empty($value)) {
+if (!isset($value) || $value == false) {
     // ...
 }

When you already know that a variable, a property, a function or method parameter, and a function or method return value are defined, why would you use isset()?

When you already know that a variable, a property, a function or method parameter, and a function or method return value assume multiple types, why would you use loose comparison and not handle each acceptable type and value separately?

When you already know that a variable, a property, a function or method parameter, and a function or method return value assume a single type, why would you use loose instead of strict comparison?

Using empty(), isset(), or loose comparisons is a wishy-washy business. Is that how you want to work?

As mentioned, I often find empty() in legacy code bases. Some of these projects run on outdated versions of PHP and are entirely unaware of property, parameter, and return type declarations. In these projects, you often can not find DocBlocks for properties, function and method parameters, or function and method return types.

When you pick up maintenance of these projects and begin to fix bugs, update PHP versions and eventually modernize them, you have difficulty figuring out what the original authors intended to do when they used empty().

Were the original authors aware of the quirks of empty()? Did the authors intend a property, a function, or a method parameter to accept all types and values? Did the authors plan to return all types and values from a function or method? Did the authors, who have long disappeared and ghosted the project owners, really think the use of empty() through?

The original author could be you. The maintainer could also be you, picking up the project after years. Perhaps you had a stroke or an accident in the meantime that impaired your cognitive abilities. Now you have difficulty understanding what the original author intended. Perhaps the authors and maintainers are entirely different persons. Maybe you are in perfect health and still struggle to understand the original author's intent.

While you write the code for the computer to process, you - as the author - also write the code for the person maintaining it after. By more or less carefully selecting language features, you instruct the computer, but you also communicate your intent to the maintainer.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler, Refactoring

Let's look at all cases when empty() returns true, and explore alternatives that better communicate your situational awareness and intent!

Undefined variable

empty() returns true when the argument is an undefined variable.

<?php

declare(strict_types=1);

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify whether a variable is undefined?

I have a scenario!

Scenario: Expecting an included file to declare a variable

You include a file that you expect to declare a variable. The file may not exist or may not declare the variable.

Instead of using empty() to verify that an included file exists and declares a variable, set the variable to a suitable default value, include the file when it exists, and verify that the variable has an acceptable type and value.

 <?php

 declare(strict_types=1);

-include __DIR__ . '/file.php';
+$file = __DIR__ . '/file.php';

-if (empty($value)) {
-    // ....
-}
+
+$value = [];
+
+if (is_file($file)) {
+    include $file;
+
+    if (!is_array($value)) {
+        // ...
+    }
+}

Instead of using empty() to verify that an included file exists and declares a variable, set the variable to a suitable default value, expect the file to return a value, include the file when it exists, and verify that the returned value has an acceptable type and value.

 <?php

 declare(strict_types=1);

-include __DIR__ . '/file.php';
+$file = __DIR__ . '/file.php';

-if (empty($value)) {
-    // ....
-}
+
+$value = [];
+
+if (is_file($file)) {
+    $value = include $file;
+
+    if (!is_array($value)) {
+        // ...
+    }
+}

💡 Avoid writing code that relies on including files that declare variables or return values.

Undefined instance property

empty() returns true when the argument is an undefined instance property.

<?php

declare(strict_types=1);

$object = new stdClass();

var_dump(empty($object->value)); // (bool)true

As a side effect, empty() also invokes the magic method __isset() when you reference an undefined instance property of an object that declares an __isset() method.

<?php

declare(strict_types=1);

$object = new class() {
    public function __isset(string $name): bool
    {
        echo '👋';

        return true;
    }
};

var_dump(empty($object->value)); // 👋(bool)true

What are scenarios where you currently use empty() and deal with an undefined instance property?

I have a scenario!

Undefined static property

empty() returns true when the argument is an undefined static property.

<?php

declare(strict_types=1);

$object = new stdClass();

var_dump(empty($object::$value)); // (bool)true

What are scenarios where you currently use empty() and deal with an undefined static property?

I have a scenario!

Inaccessible instance property

empty() returns true when the argument is an inaccessible instance property.

As a side effect, empty() invokes the magic method __isset() when it exists.

<?php

declare(strict_types=1);

$object = new class() {
    private $value = 9000;
    protected $otherValue = 9001;

    public function __isset(string $name): bool
    {
        echo '👋';

        return true;
    }
};

var_dump(empty($object->value)); // 👋(bool)true
var_dump(empty($object->otherValue)); // 👋(bool)true

What are scenarios where you currently use empty() and deal with an inaccessible instance property?

I have a scenario!

Inaccessible static property

empty() returns true when the argument is an inaccessible static property.

<?php

declare(strict_types=1);

$object = new class() {
    private static $value = 9000;
    protected static $otherValue = 9000;
};

var_dump(empty($object::$value)); // (bool)true
var_dump(empty($object::$otherValue)); // (bool)true

What are scenarios where you currently use empty() and deal with an inaccessible static property?

I have a scenario!

Scenario: Declaring variables in files and including them

Null

empty() returns true when the argument is null.

<?php

declare(strict_types=1);

$value = null;

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify that a value is not null?

I have a scenario!

Scenario: Instance or static property could be null

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with null and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === null) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume null or a known type, add a nullable property declaration and compare the property value with null.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private ?string $value = null;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === null) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be null

You have a function or a method with a parameter that could be null.

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with null and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === null) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume null or a known type, add a nullable parameter type declaration and compare the parameter with null.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(?string $value)
     {
-        if (empty($value)) {
+        if ($value === null) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be null

You have a function or a method with a return value that could be null.

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with null and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === null) {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume null or a known type, add a nullable return type declaration and compare the return value with null.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): ?string
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === null) {
     // ...
 }

💡 Avoid writing functions or methods that return values of multiple types. Add return type declarations or DocBlocks to document function and method return types.

Array

empty() returns true when the value is an empty array.

<?php

declare(strict_types=1);

$value = [];

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify that a value is not an empty array?

I have a scenario!

Scenario: Instance or static property could be an empty array

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with an empty array and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === []) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume an array, add an array property declaration and compare the property value with an empty array.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private array $value = [];

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === []) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be an empty array

You have a function or a method with a parameter that could be an empty array.

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with an empty array and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === []) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume an array, add an array parameter type declaration and compare the parameter with an empty array.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(array $value)
     {
-        if (empty($value)) {
+        if ($value === []) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be an empty array

You have a function or a method with a return value that could be an empty array.

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with an empty array and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === []) {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume an empty array, add an array return type declaration and compare the return value with an empty array.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): array
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === []) {
     // ...
 }

💡 Avoid writing functions or methods that return values of multiple types. Add return type declarations or DocBlocks to document function and method return types.

Boolean

empty() returns true when the argument is a bool with the value false.

<?php

declare(strict_types=1);

$value = false;

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify that a value is not a bool with the value false?

I have a scenario!

Scenario: Instance or static property could be false

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with false and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === false) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume a bool, add a bool property declaration and use a logical expression.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private bool $value = false;

     public function bar()
     {
-        if (empty($this->value)) {
+        if (!$this->value) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be false

You have a function or a method with a parameter that could be an empty array.

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with false and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === false) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume a bool, add a bool parameter type declaration and use a logical expression.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(bool $value)
     {
-        if (empty($value)) {
+        if (!$value) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be false

You have a function or a method with a return value that could be a bool with the value false.

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with false and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === false) {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume a bool, add a bool return type declaration and use a logical expression.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): bool
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if (!$foo->bar()) {
     // ...
 }

💡 Avoid writing functions or methods that return values of multiple types. Add return type declarations or DocBlocks to document function and method return types.

Float

empty() returns true when a variable is a float with the value 0.0 or -0.0.

<?php

declare(strict_types=1);

$value = 0.0;

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify that a value is not a float with the value 0.0 or -0.0?

I have a scenario!

Scenario: Instance or static property could be 0.0

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with 0.0 or -0.0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === 0.0) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume a float, add a float property declaration and compare the instance or static property with 0.0 or -0.0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private float $value = 0;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === 0.0) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be 0.0

You have a function or a method with a parameter that could be a float with the value 0.0 or -0.0.

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with 0.0 or -0.0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === 0.0) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume a float, add a float parameter type declaration and compare the parameter with 0.0 or -0.0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(float $value)
     {
-        if (empty($value)) {
+        if ($value === 0.0) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be 0.0

You have a function or a method with a return value that could be a float with the value 0.0 or -0.0.

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with 0.0 or 0.0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === 0.0) {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume a float, add a float return type declaration and compare the return value with 0.0 or -0.0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): float
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === 0.0) {
     // ...
 }

Int

empty() returns true when the argument is an int with the value 0.

<?php

declare(strict_types=1);

$value = 0;

var_dump(empty($value)); // // (bool)true

What are scenarios where you currently use empty() to verify that a value is not an int with the value 0?

I have a scenario!

Scenario: Instance or static property could be 0

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with 0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === 0) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume an int, add an int property declaration and compare the instance or static property with 0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private int $value = 0;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === 0) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be 0

You have a function or a method with a parameter that could be an int with the value 0.

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with 0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === 0) {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume an int, add an int parameter type declaration and compare the parameter with 0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(int $value)
     {
-        if (empty($value)) {
+        if ($value === 0) {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be 0

You have a function or a method with a return value that could be an int with the value 0.

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with 0 and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === 0) {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume an int, add an int return type declaration and compare the return value with 0.

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): int
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === 0) {
     // ...
 }

String

empty() returns true when the argument is a string with the value ''.

<?php

declare(strict_types=1);

$value = '';

var_dump(empty($value)); // // (bool)true

empty() also returns true when the argument is a string with the value '0'.

<?php

declare(strict_types=1);

$value = '0';

var_dump(empty($value)); // // (bool)true

What are scenarios where you currently use empty() to verify that a value is not a string with the value '' (or '0')?

I have a scenario!

Scenario: Instance or static property could be an empty string

You have a class with an instance or a static property and currently use empty() to verify the property value.

Instead of using empty() to verify the property value when the property can assume multiple types, compare the instance or static property with '' (or '0') and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     private $value;

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === '') {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the property value when the property can assume a string, add a string property declaration and compare the instance or static property with '' (or '0').

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    private $value;
+    private string $value = '';

     public function bar()
     {
-        if (empty($this->value)) {
+        if ($this->value === '') {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing classes with instance or static properties that accept multiple types. Add property type declarations or DocBlocks to document property types.

Scenario: Function or method parameter could be an empty string

You have a function or a method with a parameter that could be a string with the value '' (or '0').

Instead of using empty() to verify the parameter value when the parameter can assume multiple types, compare the parameter with '' (or '0') and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar($value)
     {
-        if (empty($value)) {
+        if ($value === '') {
             // ...
         }

+        // handle other possible types and values
+
         // ...
     }
 }

Instead of using empty() to verify the parameter value when the parameter can assume a string, add a string parameter type declaration and compare the parameter with '' (or '0').

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar($value)
+    public function bar(string $value)
     {
-        if (empty($value)) {
+        if ($value === '') {
             // ...
         }

         // ...
     }
 }

💡 Avoid writing functions or methods with parameters that accept multiple types. Add parameter type declarations or DocBlocks to document function and method parameter types.

Scenario: Function or method return value could be an empty string

You have a function or a method with a return value that could be a string with the value '' (or '0').

Instead of using empty() to verify the return value at the call site when the return value can assume multiple types, compare the return value with '' (or '0') and handle each possible case separately.

 <?php

 declare(strict_types=1);

 final class Foo
 {
     public function bar()
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === '') {
     // ...
 }

+// handle other possible types and values

Instead of using empty() to verify the return value at the call site when the return value can assume a string, add a string return type declaration and compare the return value with '' (or '0').

 <?php

 declare(strict_types=1);

 final class Foo
 {
-    public function bar()
+    public function bar(): string
     {
         // ...

         return $value;
     }
 }

-if (empty($foo->bar()) {
+if ($foo->bar() === '') {
     // ...
 }

💡 Avoid writing functions or methods that return values of multiple types. Add return type declarations or DocBlocks to document function and method return types.

SimpleXMLElement

empty() returns true when the argument is an instance of SimpleXMLElement constructed from an XML string representing an element without attributes and children.

<?php

declare(strict_types=1);

$value = new SimpleXMLElement('<foo></foo>');

var_dump(empty($value)); // (bool)true

What are scenarios where you currently use empty() to verify whether a SimpleXMLElement is empty?

I have a scenario!

Conclusion

Do not use empty(). Do not write code that allows a variable, a property, a parameter, or a return value to assume multiple types. Use type-safe comparisons.

Introducing PHP-CS-Fixer into legacy projects

2023-04-10T16:50:00+02:00

Introducing PHP-CS-Fixer into legacy projects

You are working on a legacy PHP project and want to use friendsofphp/php-cs-fixer to enforce a consistent coding standard. But you are unsure how to do that without causing problems.

What could be a strategy for introducing PHP-CS-Fixer into your legacy PHP that reduces risk and invites other developers to collaborate?

Requirements

If you want the introduction of PHP-CS-Fixer into your legacy PHP project to be a success, you are going to have the following requirements:

You want to run PHP-CS-Fixer in your continuous integration system. When you commit and push code that does not follow your coding standards, you want the build in your continuous integration system to fail.
You want to run PHP-CS-Fixer in your development environment. When you change your PHP code and that code that does not follow your coding standards, you want PHP-CS-Fixer to fix coding standard violations. You do not need to report coding standard violations in a development environment; you want to go straight for the fixes. You also want a simple command for running PHP-CS-Fixer in a development environment so you can run it frequently.
You want PHP-CS-Fixer to apply fixes only that are compatible with the version of PHP that you use in production. If your project runs on PHP 5.3, you do not want PHP-CS-Fixer to apply fixes that require running on PHP 8.1.

Installing PHP-CS-Fixer

You can install PHP-CS-Fixer with composer, phive, or by downloading a PHAR from the releases page. But you can study the installation options and instructions for PHP-CS-Fixer in detail in the README.md of PHP-CS-Fixer; I will not repeat them here.

I recommend using composer to install PHP-CS-Fixer so that you benefit from automated dependency updates by Dependabot, Renovatebot, or similar services. If you install PHP-CS-Fixer with phive or download it from the releases page, you have to update PHP-CS-Fixer manually.

Your project does not yet use composer? Why not start using composer by making PHP-CS-Fixer your first development dependency?

You can not use composer because your project does not yet run on PHP 5.3 in production? Why not use a different version of PHP to run development tools?

I also recommend using the latest version of PHP-CS-Fixer so that you benefit from features and fixes that the maintainers and contributors consistently add to the tool.

You can not use the latest version of PHP-CS-Fixer because your project does not yet run PHP 7.4 or above in production? Again, why not use a different version of PHP to run development tools?

For example, in the last couple of weeks, I have been busy updating a project from PHP 5.6 to PHP 8.1. After setting up a local development environment running on PHP 5.6 in Docker, I have set up a GitHub Actions workflow that uses PHP 8.1 to install and run development tools - including PHP-CS-Fixer.

If I can use PHP 8.1 to run development tools for a project that runs on PHP 5.6 in production, you can, too.

Your key to success is a careful configuration of your development tools.

Adding a basic configuration for PHP-CS-Fixer

PHP-CS-Fixer requires two things to report and fix coding standard violations: a list of files it should inspect and a configuration of rules and rulesets it uses to create and configure corresponding fixers.

The configuration file .php-cs-fixer.php below configures a finder and empty array of rules.

<?php

$finder = PhpCsFixer\Finder::create()
    ->exclude([
        '.build/',
        '.docker/',
        '.github/',
    ])
    ->ignoreDotFiles(false)
    ->in(__DIR__)
    ->name('.php-cs-fixer.php');

$config = new PhpCsFixer\Config();

$config
    ->setFinder($finder);
    ->setRules([]);

return $config;

The finder allows you to configure a list of directories, exclusions, file names, and more and returns a list of files that PHP-CS-Fixer should inspect.

Depending on your project layout, your configuration of the finder may look different.

The empty array of rules will override the default rules configuration. PHP-CS-Fixer lints a PHP file before and after applying fixers to ensure that it neither attempts to fix a file that contains invalid PHP code nor leaves a file with invalid PHP code behind. When PHP-CS-Fixer finds a file that does not contain valid PHP code, it will skip fixing it and emit a warning.

Even with an empty array of rules, PHP-CS-Fixer is a valuable tool for you as it can help you find files that contain invalid PHP code.

Now that you have an initial configuration for PHP-CS-Fixer, it is time to get started running PHP-CS-Fixer.

Running PHP-CS-Fixer on GitHub Actions

As mentioned, you want to run PHP-CS-Fixer in two environments: your continuous integration system and your local development environment.

The following command will run PHP-CS-Fixer with the --dry-run option and report coding standard violations:

vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --diff --dry-run --show-progress=dots --verbose

Depending on how you installed PHP-CS-Fixer and named your configuration file, the command may look different.

But it is important to use the --dry-run option when running PHP-CS-Fixer in a continuous integration system: PHP-CS-Fixer will end its execution with a non-zero exit code when it has found coding standard violations and break the build.

I feel at home at GitHub and like to use GitHub Actions as a continuous integration system. The GitHub Actions workflow below will check out your repository, set up PHP, install dependencies with composer, and run PHP-CS-Fixer with the --dry-run option.

name: "Integrate"

on:
  pull_request: null
  push:
    branches:
      - "main"

jobs:
  coding-standards:
    name: "Coding Standards"

    runs-on: "ubuntu-latest"

    strategy:
      matrix:
        php-version:
          - "8.1"

    steps:
      - name: "Checkout"
        uses: "actions/checkout@v3.5.0"

      - name: "Set up PHP"
        uses: "shivammathur/setup-php@v2.24.0"
        with:
          coverage: "none"
          php-version: "${{ matrix.php-version }}"

      - name: "Validate composer.json and composer.lock"
        run: "composer validate --ansi --no-check-publish"

      - name: "Install locked dependencies with composer"
        run: "composer install --ansi --no-interaction --no-progress"

      - name: "Run friendsofphp/php-cs-fixer"
        run: "vendor/bin/php-cs-fixer fix --ansi --config=.php-cs-fixer.php --diff --dry-run --show-progress=dots --verbose"

Depending on your project setup and continuous integration system, your configuration may look different - but the steps will be roughly the same.

With this GitHub Actions workflow in place, you can not commit and push PHP code that does not follow your coding standards without failing the build.

💡 You can improve the coding-standards job by caching dependencies installed with composer and caching the directory containing the cache file for PHP-CS-Fixer between runs.

Running PHP-CS-Fixer in a development environment

The following command will run PHP-CS-Fixer and fix coding standard violations:

vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --diff --show-progress=dots --verbose

Depending on how you installed PHP-CS-Fixer and named your configuration file, the command may look different. Again, you do not care about reporting coding standard violations in a development environment; you are going straight for the fixes.

The command is a bit long to type, and if you want to run PHP-CS-Fixer frequently, you probably want to use a task runner or some other tool that makes it easier to run tools in a development environment.

If you use Makefiles, add a coding-standards target to your Makefile.

.PHONY: coding-standards
coding-standards: vendor
	vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --diff --show-progress=dots --verbose

vendor: composer.json composer.lock
	composer validate --strict
	composer install --no-interaction --no-progress

With a coding-standards target in your Makefile, you can run the following command to let PHP-CS-Fixer fix coding standard violations:

make coding-standards

💡 If you do not yet use Makefiles or find that the command is still to long, read Makefile for lazy developers.

If you prefer composer scripts, add a coding-standards script to your composer.json.

{
  "scripts": {
    "coding-standards": "@php vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --diff --show-progress=dots --verbose"
  }
}

With a coding-standards script in your composer.json, you can run the following command to let PHP-CS-Fixer fix coding standard violations:

composer coding-standards

Evolving the configuring for PHP-CS-Fixer

Now that you are running PHP-CS-Fixer in your continuous integration system and your development environment, there is one thing left: you want PHP-CS-Fixer to apply fixes that are compatible with the version of PHP that you use in production, and so far, you have only configured an empty array of rules.

Here is what has worked well for me.

First, obtain a complete list of rules for all available fixers, for example, from the Custom ruleset in ergebnis/php-cs-fixer-config-template.

Second, adjust your rules configuration to configure, but disable all these fixers. At the time of writing, there should be 250 rules.

<?php

$finder = PhpCsFixer\Finder::create()
    ->exclude([
        '.build/',
        '.docker/',
        '.github/',
    ])
    ->ignoreDotFiles(false)
    ->in(__DIR__)
    ->name('.php-cs-fixer.php');

$config = new PhpCsFixer\Config();

$config
    ->setFinder($finder);
    ->setRules([
        'align_multiline_comment' => false,
        'array_indentation' => false,
        'array_push' => false,
        'array_syntax' => false,
        // ...
        'visibility_required' => false,
        'void_return' => false,
        'whitespace_after_comma_in_array' => false,
        'yoda_style' => false,
   ]);

return $config;

💡 Alternatively, if you already share configurations for PHP-CS-Fixer across projects as described in Sharing configurations for PHP-CS-Fixer across projects, override the existing rule configuration by disabling all rules.

Third, go through the list of rules, from top to bottom, from bottom to top, or whatever works best for you, pick a rule, carefully inspect its documentation, and enable and configure one rule at a time - but only when you can be sure that it only applies fixes that are compatible with the version of PHP running in production.

Example of enabling and configuring a rule at a time

Let's look at concrete examples, considering and configuring the array_syntax rule, when you are working with pull requests and pre-merge code reviews.

First, create a branch, for example, feature/array-syntax.
Second, copy the name of the rule.
Third, navigate to https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/tree/v3.16.0 (replace 3.16.0 with the version of PHP-CS-Fixer that you actually use). Press T to open the file navigation. Paste the name of the rule into the input field (here array_syntax). Select the corresponding documentation file in the drop-down (here array_syntax.rst).
Fourth, inspect the documentation. Can you safely enable the array_syntax fixer? For example, PHP 5.4 introduced the short array syntax. Is your legacy PHP project running on PHP 5.3 in production? Then you should probably enable the array_syntax fixer and configure the syntax option to use long as value. Or is your legacy PHP project running on PHP 5.4 or above? Then you should probably enable the fixer and configure the syntax option to use short as value.
Fifth, commit and push the changes to your .php-cs-fixer.php configuration file.
Sixth, open a pull request and document in the body that this pull request will enable the array_syntax fixer. Opening the pull request will start a run of your GitHub Actions workflow.
Seventh, run PHP-CS-Fixer in your development environment. If PHP-CS-Fixer has applied fixes, the GitHub Actions workflow will fail. Commit and push the fixes in a separate commit to make the build pass.
Eighth, review the changes in the pull request and verify that they make sense. If necessary, have someone else review your pull request as well.
Ninth, merge the pull request and delete the branch.
Tenth, check out your default branch in your development environment.
Eleventh, pull the latest changes.
Twelfth, delete the feature branch.

Repeat the steps above for every rule.

💡 You can find an example of a pull request that enables and configures the array_syntax fixer for the official PHP website here.

Disadvantages of enabling and configuring one rule at a time

At the time of writing, PHP-CS-Fixer ships with 250 rules. Enabling and configuring one rule at a time can take a while, even more so when you are working with pull requests and require pre-merge code reviews. But you could significantly speed up the process by using Ship/Show/Ask.

If you are unwilling to invest the time, good luck applying all rules and reviewing all fixes at once!

Advantages of enabling and configuring one rule at a time

In my opinion, enabling and configuring a single rule at a time has the following advantages:

You minimize risk: each pull request contains only related changes that are easier to review.
You invite other developers to collaborate on your coding standard.
You will probably touch code in all corners of your legacy PHP project, which allows you to discover and take note of weird spots that need closer inspection.

Collecting line, branch, and path coverage with PHPUnit

2023-03-22T16:40:00+01:00

Collecting line, branch, and path coverage with PHPUnit

phpunit/phpunit allows the collection of code coverage through phpunit/php-code-coverage, which currently supports two code coverage drivers: PCOV and Xdebug.

With PCOV, you can collect line coverage; with Xdebug, you can collect line, branch, and path coverage.

The PHPUnit documentation explains line, branch, and path coverage as follows:

The Line Coverage software metric measures whether each executable line was executed.

The Branch Coverage software metric measures whether the boolean expression of each control structure evaluated to both true and false while running the test suite.

The Path Coverage software metric measures whether each of the possible execution paths in a function or method has been followed while running the test suite. An execution path is a unique sequence of branches from the entry of the function or method to its exit.

PHPUnit documentation

As you can see, line, branch, and path coverage provide insights into different aspects of your safety net of automated tests.

But what are the costs of running tests and collecting line, branch, and path coverage? Let's find out by running tests and collecting code coverage with PHPUnit for PHPUnit!

Preparing to run tests for PHPUnit

I assume you have installed PHP 8.1 (or PHP 8.2) with the PCOV and Xdebug extensions.

First, run the following command to clone PHPUnit:

git clone git@github.com/sebastianbergmann/phpunit.git

Second, run the following command to create a branch with the name 10.0.18 based on the tag 10.0.18:

git checkout -b 10.0.18 10.0.18

Third, run the following command to install dependencies with composer:

composer install

Now you are ready to run tests and collect code coverage with PHPUnit for PHPUnit!

Collecting line, branch, and path coverage with PHPUnit for PHPUnit

First, disable PCOV and Xdebug (if you are on macOS, take a look at Quickly switching between PCOV and Xdebug). Then run the following command to run tests for PHPUnit and take note of time and memory:

./phpunit --no-progress

On my machine, a 2021 Apple MacBook Pro with an Apple M1 Max chip, 64 GB of RAM, and running PHP 8.2.4, the output looks like this:

PHPUnit 10.0.18 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.4
Configuration: /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml

Time: 00:22.092, Memory: 38.00 MB

OK, but some tests were skipped!
Tests: 2804, Assertions: 7302, Skipped: 3.

Second, enable PCOV and run the following command to collect line coverage for PHPUnit and take note of time and memory:

./phpunit --coverage-clover=clover.xml --no-progress

On my machine, the output looks like this:

PHPUnit 10.0.18 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.4 with PCOV 1.0.11
Configuration: /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml

Time: 00:34.150, Memory: 96.00 MB

OK, but some tests were skipped!
Tests: 2804, Assertions: 7304, Skipped: 1.

Generating code coverage report in Clover XML format ... done [00:00.131]

Third, disable PCOV and enable Xdebug, then run the following command to collect line coverage for PHPUnit and take note of time and memory:

./phpunit --coverage-clover=clover.xml --no-progress

On my machine, the output looks like this:

PHPUnit 10.0.18 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.4 with Xdebug 3.2.1
Configuration: /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml

Time: 00:49.498, Memory: 90.00 MB

OK, but some tests were skipped!
Tests: 2804, Assertions: 7300, Skipped: 5.

Generating code coverage report in Clover XML format ... done [00:00.185]

Fourth, keeping Xdebug enabled, run the following command to collect line, branch, and path coverage for PHPUnit and take note of time and memory:

./phpunit --coverage-clover=clover.xml --no-progress --path-coverage

On my machine, the output looks like this:

PHPUnit 10.0.18 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.4 with Xdebug 3.2.1
Configuration: /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml

Time: 07:30.861, Memory: 451.34 MB
Time: 07:30.861, Memory: 451.34 MB

OK, but some tests were skipped!
Tests: 2804, Assertions: 7300, Skipped: 5.

Generating code coverage report in Clover XML format ... done [00:00.715]

Let's take a look at the results to understand the costs of running tests and collecting code coverage!

Costs of collecting code coverage

As mentioned before, I ran the tests on a 2021 Apple MacBook Pro with an Apple M1 Max chip, 64 GB of RAM, and running PHP 8.2.4. You will probably observe different results on another machine, but the relative results will be similar.

Code Coverage Driver	Code Coverage	Time (in i:s.u)	Memory (in MB)
none	none	00:22.092	38.00 MB
PCOV	line	00:34.150	96.00 MB
Xdebug	line	00:49.498	90.00 MB
Xdebug	line, branch, path	07:30.861	451.34 MB

💡 As Sebastian Bergmann points out in Optimizing Your Test Suite (slide 49) , Xdebug does not use PHP's memory manager, so the memory shown by PHPUnit is incorrect when collecting code coverage with Xdebug.

You will probably observe different results, so let's compare the relative results!

Running tests for PHPUnit as a baseline

First, let's consider running tests for PHPUnit as a baseline.

If you drive the development of your PHP projects with tests (Test-Driven Development), you would never write a bit of production code without writing a failing test first. In theory, your code coverage would be 100%. Unless you wanted to report code coverage, for example, because you have external requirements or would like to display a shiny badge in your repository, you would never need to collect code coverage.

Code Coverage Driver	Code Coverage	Time (in i:s.u)	Memory (in MB)
none	none	00:22.092 100%	38.00 MB 100%
PCOV	line	00:34.150 154.6%	96.00 MB 252.6%
Xdebug	line	00:49.498 224.1%	90.00 MB 236.8%
Xdebug	line, branch, path	07:30.861 2040.8%	451.34 MB 1187.7%

As you can see above,

collecting line coverage with PCOV takes 1.5 times
collecting line coverage with Xdebug takes 2.2 times
collecting line, branch, and path coverage with Xdebug takes 20.4 times

as long as running tests for PHPUnit without collecting code coverage.

Collecting line coverage for PHPUnit with PCOV as a baseline

Second, as I have yet to meet someone who consistently applies Test-Driven Development, let's consider collecting line coverage for PHPUnit with PCOV as a baseline.

Code Coverage Driver	Code Coverage	Time (in i:s.u)	Memory (in MB)
none	none	00:22.092 64.7%	38.00 MB 39.6%
PCOV	line	00:34.150 100%	96.00 MB 100%
Xdebug	line	00:49.498 144.9%	90.00 MB 93.8%
Xdebug	line, branch, path	07:30.861 1320.2%	451.34 MB 470.1%

As you can see above,

collecting line coverage with Xdebug takes 1.4 times
collecting line, branch, and path coverage with Xdebug takes 13.2 times

as long as collecting line coverage for PHPUnit with PCOV.

Collecting line coverage for PHPUnit with Xdebug as a baseline

Third, since Xdebug also provides a step debugger and you may not want to switch back and forth between PCOV and Xdebug all the time, let's consider collecting line coverage for PHPUnit with Xdebug as a baseline.

Code Coverage Driver	Code Coverage	Time (in i:s.u)	Memory (in MB)
none	none	00:22.092 44.6%	38.00 MB 42.2%
PCOV	line	00:34.150 69%	96.00 MB 106.7%
Xdebug	line	00:49.498 100%	90.00 MB 100%
Xdebug	line, branch, path	07:30.861 910.9%	451.34 MB 501.5%

As you can see above,

collecting line, branch, and path coverage with Xdebug takes 9.1 times

as long as collecting line coverage for PHPUnit with Xdebug.

Conclusion

Collecting line, branch, and path coverage is costly if you value your time.

While waiting for the line, branch, and path coverage collection to finish (07:30.861!), I zoned out and checked Instagram on my phone. Context switches indirectly affect the costs of your business.

Even if you don't value your time, external services, such as GitHub Actions, put a price on the time you use for collecting code coverage using their infrastructure (currently $0.008 per minute). The invoices you need to pay directly affect the costs of your business.

Last but not least, the consumption of computing resources indirectly affects the environment, increasing social costs that we all have to pay in different terms.

What are your arguments for collecting line, branch, and path coverage when line coverage would suffice?

Avoiding one-liners in PHP

2023-03-18T07:30:00+01:00

Avoiding one-liners in PHP

PHP developers frequently share how they transform multiple lines of PHP code into one-liners. Through the eye of a maintainer, how do these one-liners compare to their multi-line counterparts? After all, writing PHP code is not a problem, but maintaining it is even more so.

Maintenance of PHP projects

With a safety net of automated tests, the maintenance of a PHP project is easy.

If you have that safety net, the readability of the production does not matter: you can always refactor it into something more or less readable without worrying about breaking it.

If you have that safety net, the syntactic sugar you use in the production code does not matter: you can always be more progressive or conservative, depending on the minimum version of PHP you support and the features you are comfortable using.

If you have that safety net, you could probably let ChatGPT generate your production code based on yiur automated tests and consider the production code a build artifact that you do not even bother checking into version control. Well, maybe we are not quite there yet!

But, if you have seen your fair share of PHP projects, you know that most of these, particularly closed-source PHP projects, suffer from a lack of tests.

Without a safety net of automated tests, the maintenance of a PHP project can quickly become a nightmare, and there is little reason to make it even more difficult for you.

But how good is your safety net of automated tests?

Effects of one-liners on code coverage

As a maintainer of a PHP project with less than 100% code coverage, you understand how deleting, adding, and formatting code can affect code coverage metrics.

Code coverage will decrease when

you delete tests
you reformat tested production code from more to fewer executable lines (one-liners, anyone?)
you add untested code
you reformat untested production code from fewer to more executable lines

Code coverage will increase when

you add tests
you reformat tested production code from fewer to more executable lines
you deleted untested production code
you reformat untested production code from more to fewer executable lines (one-liners, anyone?)

By using clever one-liners in your production code, you can gain misleadingly high confidence in your production code and your safety net of automated tests.

Collecting line, path, and branch code coverage

When you use PHPUnit to collect code coverage, PHPUnit will only collect line coverage by default. You could additionally collect line, branch, and path coverage, but as you can see in Collecting line, branch, and path coverage with PHPUnit, the collection of branch and path coverage comes at a cost.

Are the conditional one-liners in your PHP project worth these costs?

Instead of spending time, resources, and money to collect branch and path coverage when line coverage would suffice, why not avoid conditional one-liners in the first place?

Running mutation tests

When you use infection/infection to run mutation tests, you can combine your code coverage metrics with mutation score indicators to get a better idea of the quality of your test suites.

infection/infection will mutate your production code and run the tests against the mutations. If the tests pass after applying mutants, your tests are not good enough, and infection/infection will log the uncovered mutations.

But you do not maintain your PHP project in a log file, do you? You maintain your production code in an IDE.

Visualizing code coverage in PhpStorm

When you use PhpStorm and run tests with code coverage, PhpStorm will mark tested and untested lines of code as green and red, so you can immediately identify which lines of code require tests.

PhpStorm does not yet support branch coverage, so if you use conditional one-liners in your PHP project, PhpStorm does not show whether your tests cover both branches of a condition.

By using conditional one-liners in your PHP project, you are potentially hiding untested branches in your production code in plain sight.

Instead of hiding these untested parts of your production code in your IDE, why not avoid conditional one-liners in the first place?

Effects of one-liners on debugging

When you use PhpStorm and Xdebug to debug PHP code, you can set breakpoints to halt the execution, inspect variables in the current scope, and step through the program.

If you set breakpoints in your one-liners, where exactly is the execution going to halt? How will you understand where you are in the current execution, step into, over, and out of the current expression?

The widespread use of clever one-liners will make it rather difficult for you to use a step debugger.

Candidates for clever one-liners

Let's look at a few PHP language features that allow you to use one-liners instead of their multi-line counterparts (all of these are from the PHP website).

ternary operators
short ternary operators
null-coalescing operators
null-coalescing assignment operators
arrow functions
null-safe operators
throw expressions

Ternary operators

The following example demonstrates the use of the ternary operator. Unfortunately, I do not know which PHP version introduced it, but 3v4l.org shows that the ternary operator works on PHP 4.3.0.

<?php

$username = isset($_GET['user']) ? $_GET['user'] : 'nobody';

The example above is equivalent to the following PHP code:

<?php

if (isset($_GET['user'])) {
    $username = $_GET['user'];
} else {
    $username = 'nobody';
}

The example above is also equivalent to the following PHP code:

<?php

$username = 'nobody';

if (isset($_GET['user'])) {
    $username = $_GET['user'];
}

While the use of isset() is debatable, the multi-line examples will immediately expose a lack of code coverage and allow you to set a breakpoint on a line with a single expression.

Short ternary operators

The following example demonstrates the use of the short ternary operator, introduced with PHP 5.3.0.

<?php

$result = $action ?: 'default';

The example above is equivalent to the following PHP code (see ternary operators):

<?php

$result = $action ? $action : 'default';

The example above is equivalent to the following PHP code:

<?php

if ($action) {
    $result = $action;
} else {
    $result = 'default';
}

The example above is equivalent to the following PHP code:

<?php

$result = 'default';

if ($action) {
    $result = $action;
}

While the use of non-boolean expressions in conditions is debatable, the multi-line examples will immediately expose a lack of code coverage and allow you to set a breakpoint on a line with a single expression.

Null-coalescing operators

The following example demonstrates the use of the null-coalescing operator, introduced with PHP 7.0.0.

<?php

$username = $_GET['user'] ?? 'nobody';

The example above is equivalent to the following PHP code (see ternary operators):

<?php

$username = isset($_GET['user']) ? $_GET['user'] : 'nobody';

The example above is equivalent to the following PHP code:

<?php

if (isset($_GET['user'])) {
    $username = $_GET['user'];
} else {
    $username = 'nobody';
}

The example above is also equivalent to the following PHP code:

<?php

$username = 'nobody';

if (isset($_GET['user'])) {
    $username = $_GET['user'];
}

Again, while the use of isset() is debatable, the multi-line examples will immediately expose a lack of code coverage and allow you to set a breakpoint on a line with a single expression.

Null-coalescing assignment operators

The following example demonstrates the use of the null-coalescing assignment operator, introduced with PHP 7.4.0.

<?php

$array['key'] ??= computeDefault();

The example above is equivalent to the following PHP code:

<?php

if (!isset($array['key'])) {
    $array['key'] = computeDefault();
}

Again, while the use of isset() is debatable, the multi-line example will immediately expose a lack of code coverage and allow you to set a breakpoint on a line with a single expression.

Arrow functions

The following example demonstrates the use of arrow functions, introduced with PHP 7.4.0.

<?php

$factor = 10;

$nums = array_map(fn($n) => $n * $factor, [1, 2, 3, 4]);

The example above is equivalent to the following PHP code:

<?php

$factor = 10;

$nums = array_map(function ($n) use ($factor) {
   return $n * $factor;
}, [1, 2, 3, 4]);

While the lack of type and return type declarations is debatable, the multi-line example will allow you to set a breakpoint on a line with a single expression. Also, the arrow function only implicitly captures the variable $factor. At the same time, the multi-line example requires you to explicitly declare which variables you want to import into the scope of the closure. Explicit is better than implicit.

Null-safe operator

The following example demonstrates the use of the null-safe operator, introduced with PHP 8.0.0.

<?php

$result = $repository?->getUser(5)?->name;

The example above is equivalent to the following PHP code:

<?php

if (is_null($repository)) {
    $result = null;
} else {
    $user = $repository->getUser(5);

    if (is_null($user)) {
        $result = null;
    } else {
        $result = $user->name;
    }
}

The example above is equivalent to the following PHP code:

<?php

$result = null;

if ($repository !== null) {
    $user = $repository->getUser(5);

    if ($user !== null) {
        $result = $user->name;
    }
}

While the use of is_null() is debatable, the multi-line examples will immediately expose a lack of code coverage and allow you to set a breakpoint on a line with a single expression.

Throw expressions

The following example demonstrates the use of the throw expression, introduced with PHP 8.0.0.

<?php

function test() {
    do_something_risky() or throw new Exception('It did not work');
}

The example above is equivalent to the following PHP code:

<?php

function test() {
    if (!do_something_risky()) {
        throw new Exception('It did not work');
    }
}

The example above is equivalent to the following PHP code:

<?php

function test() {
    $result = do_something_risky();

    if (!$result) {
        throw new Exception('It did not work');
    }
}

Recommendation

Avoid clever one-liners or use them with care. Focus on writing code that solves real problems, is well-tested, and is easy to maintain. The developers who follow your path will thank you!

Sharing configurations for PHP-CS-Fixer across projects

2023-03-10T08:40:00+01:00

Sharing configurations for PHP-CS-Fixer across projects

You are working on PHP applications and packages and use friendsofphp/php-cs-fixer to enforce coding standards.

What are your options for sharing your configurations for friendsofphp/php-cs-fixer to enforce a consistent coding standard across these projects in your organization?

Configuring PHP-CS-Fixer

You can configure friendsofphp/php-cs-fixer with command line options only or by using a configuration file. I recommend using a configuration file.

The configuration file, typically with the name .php-cs-fixer.php or .php-cs-fixer.dist.php, contains PHP and needs to return a configuration object.

<?php

declare(strict_types=1);

use PhpCsFixer\Config;

$config = new Config();

// ...

return $config;

The configuration object must configure a finder that supplies friendsofphp/php-cs-fixer with a list of files to inspect.

<?php

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$finder = Finder::create()
    ->exclude([
        '.build/',
        '.github/',
    ])
    ->in(__DIR__);

$config = new Config();

$config->setFinder($finder)

return $config;

The configuration object can optionally configure zero or more of the 38 rulesets and 250 rules.

If you do not configure any rulesets or rules, friendsofphp/php-cs-fixer currently uses @PSR12 as default ruleset.

If you configure one or more of the available rulesets and rules, friendsofphp/php-cs-fixer will create, configure, and apply the corresponding fixers to the PHP files.

<?php

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$finder = Finder::create()
    ->exclude([
        '.build/',
        '.github/',
    ])
    ->in(__DIR__);

$config = new Config();

$config
    ->setFinder($finder)
    ->setRules([
        // one or more of 38 rulesets
        '@PSR12' => true,

        // one or more of 250 rules for fixers
        'blank_line_before_statement' => [
            'statements' => [
                'break',
                'case',
                'continue',
                // ...
        ],

        // ...

        'yoda_style' => true,
    ]);

return $config;

Since the location of PHP files will differ from one project to another, you will want to configure the finder per project and are only concerned with sharing the configuration of rulesets and rules across projects.

If you use GitHub and do not feel like setting up a new project from scratch every time, you probably already have a GitHub template repository.

A GitHub repository template, such as ergebnis/php-package-template enables you to set up a new project quickly - which could be an ideal location for maintaining a configuration of rulesets and rules for friendsofphp/php-cs-fixer.

But, you may realize that the PHP applications and packages you build have very different requirements and setups, so maybe you need more than one GitHub repository template.

So which of these GitHub template repositories should now be the source of truth for your configurations of rulesets and rules for friendsofphp/php-cs-fixer?

Also, you may realize that you need to support a wide range of PHP versions, requiring different configurations for friendsofphp/php-cs-fixer. So how can you make sure that you use the correct configuration?

And, even if you had only a single GitHub repository template where you maintain a configuration of rulesets and rules for friendsofphp/php-cs-fixer, how would you propagate the configuration of rulesets and rules to all of your other projects?

Copying the configurations from there and pasting them into a PHP project whenever you pick up work could be an option.

But this option is prone to errors. And how do you know whether the configuration in the central location has changed since you last worked on a specific project?

If we only had a delivery mechanism for distributing configurations!

As Paul Redmond rightly points out in his recent article about sharing configurations of rules for squizlabs/php_codesniffer (an alternative to friendsofphp/php-cs-fixer), the ideal solution for sharing and propagating configurations is a PHP package.

A PHP package can not only provide files, such as the XML configuration files for PHPCS in Paul's article, or PHP files or classes returning or creating arrays of rulesets and rules configurations for friendsofphp/php-cs-fixer, but also declare dependencies.

As friendsofphp/php-cs-fixer evolves, contributors and maintainers add, deprecate, and remove fixers and configuration options. You certainly want to ensure that your configuration of rulesets and rules works well with the version of friendsofphp/php-cs-fixer you use in your projects. You can achieve that by declaring the dependency on friendsofphp/php-cs-fixer in the PHP package instead of the consuming application or package.

A PHP package can receive automated updates via Dependabot, Renovate Bot, or similar services.

If you set up the PHP package cleverly, you can use these automated updates to discover added, deprecated, and removed fixers and configuration options with automated tests. Automatic discovery of new fixers and configuration options allows you to use the full potential of fixers that friendsofphp/php-cs-fixer provides and can free up time for more pressing problems than manually fixing coding standard violations.

Last but not least, by using Dependabot, Renovate Bot or similar services, you can propagate the configurations of rulesets and rules from your PHP package, which can now become the single source of truth of configurations for friendsofphp/php-cs-fixer, to all of your other PHP applications and packages.

The simplest solution would be to create one or more PHP files in your package that return the configuration of rulesets and rules.

<?php

declare(strict_types=1);

return [
    // one or more of 38 rulesets
    '@PSR12' => true,

    // one or more of 250 rules for fixers
    'blank_line_before_statement' => [
        'statements' => [
            'break',
            'case',
            'continue',
            // ...
    ],

    // ...

    'yoda_style' => true,
];

Then you can require the PHP file downstream in your configuration for PHP-CS-Fixer.

<?php

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$rules = require __DIR__ . '/vendor/ergebnis/php-cs-fixer-config/config/php82.php';

$finder = Finder::create()
    ->exclude([
        '.build/',
        '.github/',
    ])
    ->in(__DIR__);

$config = new Config();

$config
    ->setFinder($finder)
    ->setRules($rules);

return $config;

But why not extract a factory and concrete classes providing configurations of rulesets and rules that create the configurations for you?

For example, a factory could ensure that you are running friendsofphp/php-cs-fixer on the appropriate version of PHP. A factory could also further prepare the configuration object. Concrete classes for PHP-version-specific rulesets could allow you to override rules for project-specific configurations. A factory and classes also have the advantage that they are autoloadable, and you do not have to deal with exact file locations.

<?php

declare(strict_types=1);

use Ergebnis\PhpCsFixer;

$config = PhpCsFixer\Config\Factory::fromRuleSet(new PhpCsFixer\Config\RuleSet\Php82('', [
    'date_time_immutable' => false,
    'mb_str_functions' => false,
]);

$config->getFinder()
    ->exclude([
        '.build/',
        '.github/',
        'var/',
    ])
    ->in(__DIR__);

return $config;

Concrete examples from the field

In 2015, while supplying services for Refinery29, Inc., I started working on refinery29/php-cs-fixer-config.

As far as I can tell, this was the first PHP package that shared configurations of rulesets and rules for friendsofphp/php-cs-fixer, inspiring many others you can find on Packagist today.

Since 2015, I have successfully applied and refined this approach in ergebnis/php-cs-fixer-config, which I use in all my projects.

For your convenience, I have extracted a GitHub template repository at ergebnis/php-cs-fixer-config-template as a perfect starting point to create, share, and distribute configurations of rulesets and rules for friendsofphp/php-cs-fixer.

Take a look - you will not regret it!

Organizing test code in PHP

2023-03-03T15:05:00+01:00

Organizing test code in PHP

You are working on a PHP application or a package. You have decided that you want to use:

infection/infection for running mutation tests
phpbench/phpbench for running performance tests
phpunit/phpunit for running unit, integration, functional, and end-to-end tests

Perhaps you are considering other design and testing frameworks as well, for example:

What are your drivers and options for organizing test code?

Systems under test

For this article, let's assume you have relatively simple production code organized in a directory structure as follows (listing generated with the tree command):

.
└── src
    ├── Example.php
    ├── ValueCanNotBeBlank.php
    └── ValueCanNotBeEmpty.php

💡 You can inspect the source code in the main branch of localheinz/organizing-test-code-in-php.

Test code

Let's also clarify what we understand as test code.

First, you have test files.

When you use a class-based test case framework such as phpunit/phpunit, these test files declare tests in classes. Or, when you use a file-based test case framework such as pestphp/pest, these test files declare tests in functions.

Second, you have supporting test files.

You may extract abstract test cases, helper traits, data providers, and test doubles to share functionality across tests. You may also have fixtures for use in tests. You can organize all of these in classes, functions, or files.

Third, you have configuration files.

When you use a test framework that works with configuration files, you will have at least one configuration per test framework.

When you use composer, you have a composer.json file in which you not only configure your project's dependencies but also configure and document namespaces for autoloading production and test code.

When you use git and are working on a package, you may have a .gitattributes configuration to prevent the distribution of code that users of your package do not need.

Drivers for organizing test code

Let's also talk about potential drivers for organizing test code.

First, the mapping of test classes or files to production code drives the organization of your test code.

You could have a single test class or test file that contains tests for the entire application or package.

As you add more tests, you may find it challenging to decide where to add those tests - or you may have problems finding a specific test. Perhaps you conclude that it is better to have one test class or file per system under test, with a consistent naming (using prefixes, infixes, or suffixes) that makes it easier to find a test class or file.

Second, the kinds of test you intend to write drive the organization of your test code.

When you realize that you have different kinds of tests, for example, unit, integration, functional, or end-to-end tests, you could move different kinds of tests into separate files - each test class or file containing only a specific kind of test.

You could also group these tests by kind in separate directories and namespaces.

Third, the requirement to configure and bootstrap different kinds of tests drives the organization of your test code.

When you have different kinds of tests, you may also realize that these tests require completely different test bootstrapping. You may have to set up a database, run database migrations, and seed the database for integration, functional, and end-to-end tests, but certainly not for unit tests.

A single configuration file will only get you so far. You could use dedicated configuration files for different kinds of tests instead.

Forth, the number of testing frameworks drives the organization of your test code.

You could place all test classes and test files in a single directory and leave it up to your testing frameworks to decide whether they should consider a specific test class or file as a test case.

You could also group tests by testing framework. A grouping like that could considerably simplify the configuration, maintenance, and speed up running of tests.

Options for organizing test code

As far as I can tell, you have the following options for organizing test code:

no tests
in the same file
in the same directory
in a subdirectory
in subdirectories
in subdirectories with separate configuration files
in a separate directory
in separate directories
in separate directories with separate configuration files

No tests

By far, this is the simplest solution for organizing test code.

You have fewer lines of code, dependencies, and configuration files. You probably also have more bugs, downtimes, and sleepless nights.

If you are comfortable with that, you can stop reading now.

Declaring test code in the same file

You can declare test code in the same file as production code, but unfortunately, I have not been able to configure phpbench/phpbench or phpunit/phpunit to find benchmarks or tests in the production files.

Unless you have found a way to make this work, declaring test code in the same file is not an option. If you have found a way, I would like to hear about it.

I have found a way!

Declaring test code in the same directory

You can declare test code in the same directory as production code.

.
├── src
│   ├── Example.php
│   ├── ExampleBench.php
│   ├── ExampleTest.php
│   ├── Helper.php
│   ├── ValueCanNotBeBlank.php
│   ├── ValueCanNotBeBlankTest.php
│   ├── ValueCanNotBeEmpty.php
│   └── ValueCanNotBeEmptyTest.php
├── phpbench.json
└── phpunit.xml

💡 You can inspect the source code and a pull request that declares test code in the src/ directory in localheinz/organizing-test-code-in-php.

In my opinion, this approach has the following disadvantages:

It is hard to tell whether the code in the src/ directory is production or test code. How can you know whether a piece of code is only intended for use in test environments, for example, a test helper or a value object? How can you prevent developers from using test code in production?
If you want to run unit, integration, functional, and end-to-end tests, how can you distinguish between these different kinds of tests?
If you want to run unit, integration, functional, and end-to-end tests, how can you ensure appropriate test bootstrapping for each test? It is not necessary to bootstrap a database and run migrations for running unit tests, but it might be for integration, functional, and end-to-end tests.
Where are you going to place abstract test cases, helper traits, data providers, test doubles, and test fixtures if you need any?
You must excessively configure exclusions in composer.json to exclude test code from being autoloadable in production systems.
You need to configure exclusions for test code in infection.json to prevent infection/infection from mutating test code and reporting false negatives from mutated test code.
You need to configure exclusions for test code in phpunit.xml to prevent phpunit/phpunit from reporting test code as used in tests and not being covered by tests.
If you are working on a package, you need to excessively configure exclusions for test code in .gitattributes to prevent the unnecessary distribution of test code to users of your package.
If you are working on a package, how are you dealing with users who expect a test/ or tests/ directory in the root of your project and skip the inspection and consideration of your package entirely because they suspect you have not written any tests?

If you are interested in what others say about declaring test code in the same directory, check out the replies to this tweet by Brent Roose:

An out of the box idea: why would/wouldn't you store your tests alongside your source code, instead of keeping them completely separated? I can come up with a few pros and cons, but would like to hear your opinion.
— Brent (@brendt_gd) September 15, 2021

Declaring test code in a subdirectory

You can declare test code in a subdirectory of your production code.

.
├── src
│   ├── Test
│   │   ├── ExampleBench.php
│   │   ├── ExampleTest.php
│   │   ├── Helper.php
│   │   ├── ValueCanNotBeBlankTest.php
│   │   ├── ValueCanNotBeEmpty.php
│   │   └── ValueCanNotBeEmptyTest.php
│   ├── Example.php
│   ├── ValueCanNotBeBlank.php
│   └── ValueCanNotBeEmpty.php
├── phpbench.json
└── phpunit.xml

💡 You can inspect the source code and a pull request that declares test code in a subdirectory of the src/ directory in localheinz/organizing-test-code-in-php.

You will often see this organization of test code in repositories split from mono-repositories. For an example, inspect symfony/var-dumper which is a split from symfony/symfony.

In my opinion, this approach has the following advantages over declaring test code in the same directory

It is easier to tell whether code is production or test code.
The configuration of exclusions in composer.json to exclude test code from being autoloadable in production systems has become simpler.
If you are working on a package, the configuration of exclusions for test code in .gitattributes to prevent the unnecessary distribution of test code to users of your package has become simpler.

In my opinion, this approach still has the following disadvantages:

You still are not distinguishing between unit, integration, functional, and end-to-end tests.
You are still not ensuring appropriate test bootstrapping for unit, integration, functional, and end-to-end tests.
You still need to configure exclusions for test code in infection.json to prevent infection/infection from mutating test code and reporting false negatives from mutated test code.
You still need to configure exclusions for test code in phpunit.xml to prevent phpunit/phpunit from reporting test code as used in tests and from reporting test code as not being covered by tests.
You are still placing test fixtures and utilities along with test code.
If you are working on a package, potential users may still skip the inspection and consideration of your package entirely because they can not see a test/ or tests/ directory in the root of your project and suspect you have not written any tests.

Declaring test code in subdirectories

You can declare test code in subdirectories of your production code.

.
├── src
│   ├── Test
│   │   ├── Performance
│   │   │   └── ExampleBench.php
│   │   ├── Unit
│   │   │   ├── ExampleTest.php
│   │   │   ├── ValueCanNotBeBlankTest.php
│   │   │   ├── ValueCanNotBeEmpty.php
│   │   │   └── ValueCanNotBeEmptyTest.php
│   │   └── Util
│   │       └── Helper.php
│   ├── Example.php
│   ├── ValueCanNotBeBlank.php
│   └── ValueCanNotBeEmpty.php
├── phpbench.json
└── phpunit.xml

💡 You can inspect the source code and a pull request that declares test code in subdirectories of the src/ directory in localheinz/organizing-test-code-in-php.

In my opinion, this approach has the following advantages over declaring test code in a subdirectory:

You distinguish between unit, integration, functional, and end-to-end tests by grouping them in subdirectories and corresponding namespaces. Developers will understand where to place performance and unit tests more quickly.
If you need test fixtures or utilities, they can all go into subdirectories and corresponding namespaces.

In my opinion, this approach still has the following disadvantages:

You are still not ensuring appropriate test bootstrapping for unit, integration, functional, and end-to-end tests.
You still need to configure exclusions for test code in infection.json to prevent infection/infection from mutating test code and reporting false negatives from mutated test code.
You still need to configure exclusions for test code in phpunit.xml to prevent phpunit/phpunit from reporting test code as used in tests and from reporting test code as not being covered by tests.
If you are working on a package, potential users may still skip the inspection and consideration of your package entirely because they can not see a test/ or tests/ directory in the root of your project and suspect you have not written any tests.

Declaring test code in subdirectories with separate configuration files

You can declare test code in subdirectories of your production code with separate configuration files.

.
└── src
    ├── Test
    │   ├── Performance
    │   │   ├── ExampleBench.php
    │   │   └── phpbench.json
    │   ├── Unit
    │   │   ├── ExampleTest.php
    │   │   ├── phpunit.xml
    │   │   ├── ValueCanNotBeBlankTest.php
    │   │   ├── ValueCanNotBeEmpty.php
    │   │   └── ValueCanNotBeEmptyTest.php
    │   └── Util
    │       └── Helper.php
    ├── Example.php
    ├── ValueCanNotBeBlank.php
    └── ValueCanNotBeEmpty.php

💡 You can inspect the source code and a pull request that declares test code in subdirectories of the src/ directory with separate configuration files in localheinz/organizing-test-code-in-php.

In my opinion, this approach has the following advantages over declaring test code in subdirectories:

You ensure appropriate test bootstrapping for unit, integration, functional, and end-to-end tests by extracting dedicated configuration files.
If you are working on a package, the configuration of exclusions for test code in .gitattributes to prevent the unnecessary distribution of test code to users of your package has become even simpler.

In my opinion, this approach still has the following disadvantages:

You still need to configure exclusions for test code in infection.json to prevent infection/infection from mutating test code and reporting false negatives from mutated test code.
You still need to configure exclusions for test code in phpunit.xml to prevent phpunit/phpunit from reporting test code as used in tests and from reporting test code as not being covered by tests, and that configuration has become even worse.
If you are working on a package, potential users may still skip the inspection and consideration of your package entirely because they can not see a test/ or tests/ directory in the root of your project and suspect you have not written any tests.

Declaring test code in a separate directory

You can declare test code in a directory entirely separate from production code.

.
├── src
│   ├── Example.php
│   ├── ValueCanNotBeBlank.php
│   └── ValueCanNotBeEmpty.php
├── test
│   ├── ExampleBench.php
│   ├── ExampleTest.php
│   ├── Helper.php
│   ├── ValueCanNotBeBlankTest.php
│   ├── ValueCanNotBeEmpty.php
│   └── ValueCanNotBeEmptyTest.php
├── phpbench.json
└── phpunit.xml

💡 You can inspect the source code and a pull request that declares test code in a separate test/ directory in localheinz/organizing-test-code-in-php.

You can find documentation for this approach in the official PHPUnit documentation.

In my opinion, this approach has the following advantages over declaring test code in the same directory:

It is trivial to tell whether code is production or test code.
You do not need to configure exclusions in composer.json to exclude test code from being autoloadable in production systems. Instead, you configure an autoloader for test code in the autoload-dev section.
You do not need to configure exclusions for test code in infection.json for infection/infection.
You do not need to configure exclusions for test code in phpunit.xml for phpunit/phpunit.
If you are working on a package, you only need to configure exclusions for test configuration files and the test/ directory in .gitattributes to prevent the unnecessary distribution of test code to users of your package.
If you are working on a package, potential users will not skip the inspection and consideration of your package entirely as they can see a test/ or tests/ directory in the root of your project.

In my opinion, this approach still has the following disadvantages:

You still are not distinguishing between unit, integration, functional, and end-to-end tests.
You are still not ensuring appropriate test bootstrapping for unit, integration, functional, and end-to-end tests.
You are still placing test fixtures and utilities along with test code.

Declaring test code in separate directories

You can declare test code in subdirectories of a directory entirely separate from production code.

.
├── src
│   ├── Example.php
│   ├── ValueCanNotBeBlank.php
│   └── ValueCanNotBeEmpty.php
├── test
│   ├── Performance
│   │   └── ExampleBench.php
│   ├── Unit
│   │   ├── ExampleTest.php
│   │   ├── ValueCanNotBeBlankTest.php
│   │   ├── ValueCanNotBeEmpty.php
│   │   └── ValueCanNotBeEmptyTest.php
│   └── Util
│       └── Helper.php
├── phpbench.json
└── phpunit.xml

💡 You can inspect the source code and a pull request that declares test code in subdirectories of a separate test/ directory in localheinz/organizing-test-code-in-php.

In my opinion, this approach has the following advantages over declaring test code in a subdirectory:

You distinguish between unit, integration, functional, and end-to-end tests by grouping them in subdirectories and corresponding namespaces. Developers will understand where to place performance and unit tests more quickly.
If you need test fixtures or utilities, they can all go into subdirectories and corresponding namespaces.
If you are working on a package, potential users will not skip the inspection and consideration of your package entirely, as they can see a test/ or tests/ directory in the root of your project.

In my opinion, this approach still has the following disadvantages:

You are still not ensuring appropriate test bootstrapping for unit, integration, functional, and end-to-end tests.

Declaring test code in separate directories with separate configuration files

You can declare test code in subdirectories of a directory entirely separate from production code with separate configuration files.

.
├── src
│   ├── Example.php
│   ├── ValueCanNotBeBlank.php
│   └── ValueCanNotBeEmpty.php
└── test
    ├── Performance
    │   ├── ExampleBench.php
    │   └── phpbench.json
    ├── Unit
    │   ├── ExampleTest.php
    │   ├── phpunit.xml
    │   ├── ValueCanNotBeBlankTest.php
    │   ├── ValueCanNotBeEmpty.php
    │   └── ValueCanNotBeEmptyTest.php
    └── Util
        └── Helper.php

💡 You can inspect the source code and a pull request that declares test code in subdirectories of a separate test/ directory with separate configuration files in localheinz/organizing-test-code-in-php.

In my opinion, this approach has the following advantages over declaring test code in separate directories:

You ensure appropriate test bootstrapping for unit, integration, functional, and end-to-end tests.

In my opinion, this approach has the following disadvantages:

You may need to merge code coverage reports if you use different configuration files for unit, integration, function, and end-to-end tests and want to collect code coverage from multiple test runs.

Recommendation

I prefer to declare test code in separate directories with separate configuration files, but I am open to changing my mind and adapting to the circumstances.

Do what works best for you!

Documenting the system under test in PHPUnit

2023-02-22T14:35:00+01:00

Documenting the system under test in PHPUnit

You are working in a code base you inherited from someone else or have not touched in years. Customers have repeatedly asked for a feature or demanded that you fix a bug. You already know which class or classes you need to change, but - you still have difficulty understanding how to use them and what they do.

In your attempts to understand the code before you can change it, you search for usages of that class. Luckily, there are a few references in test cases because, surprisingly, the code base has a few tests written in phpunit/phpunit!

Identifying the system under test

Unfortunately, the organization of test code is unclear.

You inspect test class names, but they do not reveal the system under test (SUT).

Some test cases set up one or more objects in the setUp() and assign these objects to fields. Which of these fields represents the system under test? Or are these collaborators of the system under test?

You inspect test method names, but they also do not reveal the system under test.

You dive deeper into the test methods, hoping to find a clear structure, trying to identify the system under test. The test methods, however, are long and miss a clear structure. Does this section arrange something needed for the tests? Does this part act on the system under test? Here are a few assertions. Are these expectations yet? Hmm, there is more code after expectations, invoking methods on objects. Perhaps these expectations are pre-conditions only and have nothing to do with asserting the behavior of the system under test?

Unfortunately, it's not the class you are interested in, so you continue your investigation.

Finally, after rummaging in the test cases for a while, you have identified the system under test.

Documenting the system under test

Once you have identified in existing test cases what the system under test is, how can you document the system under test for yourself? Or if you use Test-Driven Development, how can you document the system under test for someone else?

How can you prevent yourself and others from going through this time-consuming research again?

As I suggested, you could discuss and establish naming conventions for test cases and test methods. But naming conventions are difficult to enforce and a matter of taste.

As I pointed out, you could use the setUp() method in test classes to set up the system under test and use explicit naming for fields referencing the system under test. But you may realize that the setUp() method was never intended for setting up the system under test, but the environment. You may also conclude that tests are harder to understand if you must go back and forth between the setUp() and test methods to understand what is happening.

Aren't there better options?

Using annotations

If you have read DocBlocks before, you know @link and @see annotations. You can use these annotations to link to a URI, a class, a method, or a field.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

/**
 * @see \Ergebnis\Package\Example
 */
final class ExampleTest extends Framework\TestCase
{
    // ...
}

However, these annotations are missing context.

Therefore, since you already use phpunit/phpunit, why not use annotations that phpunit/phpunit understands and add context to that relation?

@covers annotation

You can use the @covers annotation on the class level to document the system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

/**
 * @covers \Ergebnis\Package\Example
 */
final class ExampleTest extends Framework\TestCase
{
    // ...
}

You can also use the @covers annotation on the method level to document the system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

final class ExampleTest extends Framework\TestCase
{
    /**
     * @covers \Ergebnis\Package\Example
     */
    public function testFromStringRejectsEmptyValue(): void
    {
        // ...
    }

    /**
     * @covers \Ergebnis\Package\Example::fromString
     */
    public function testFromStringReturnsExample(): void
    {
        // ...
    }
}

@coversDefaultClass annotation

You can also use the @coversDefaultClass annotation on the method level in combination with the @covers annotation on the class level to avoid documenting the fully-qualified class name on the test method again.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

/**
 * @coversDefaultClass \Ergebnis\Package\Example
 */
final class ExampleTest extends Framework\TestCase
{
    public function testFromStringRejectsEmptyValue(): void
    {
        // ...
    }

    /**
     * @covers ::fromString
     */
    public function testFromStringReturnsExample(): void
    {
        // ...
    }
}

@coversNothing annotation

You can use the @coversNothing annotation on the class level to document that there is no clear system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

/**
 * @coversNothing
 */
final class ExampleTest extends Framework\TestCase
{
    // ...
}

You can also use the @coversNothing annotation on method level to indicate that there is no clear system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

final class ExampleTest extends Framework\TestCase
{
    /**
     * @coversNothing
     */
    public function testFromStringReturnsExample(): void
    {
        // ...
    }
}

Using attributes

Since the release of phpunit/phpunit:10.0.0, you can use attributes instead of annotations.

CoversClass attribute

You can use the CoversClass attribute on the class level to document the system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

#[Framework\CoversClass(Example::class)]
final class ExampleTest extends Framework\TestCase
{
    // ...
}

CoversFunction attribute

You can use the CoversFunction attribute on the class level to document the system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

#[Framework\Attributes\CoversFunction('dd')]
final class ExampleTest extends Framework\TestCase
{
    // ...
}

CoversNothing attribute

You can use the CoversNothing attribute on the class level to document that there is no clear system under test.

<?php

declare(strict_types=1);

namespace Ergebnis\Package\Test\Unit;

use Ergebnis\Package\Example;
use PHPUnit\Framework;

#[Framework\Attributes\CoversNothing]
final class ExampleTest extends Framework\TestCase
{
    // ...
}

Advantages of documenting the system under test

Documenting the system under test with annotations or attributes has the following advantages:

If you add these annotations or attributes to test classes or test methods, phpunit/phpunit will filter out code that is executed in a test but not intended to contribute to code coverage.

This avoids unintentional code coverage: you execute code in tests, but the tests do not test and only use the code. Your actual test coverage may unintentionally be lower than what you think it is.

Adding annotations or attributes not only documents the systems under test but also forces you to write dedicated tests for code that otherwise you only use in tests.

If you add annotations or attributes to test classes or test methods, you can easily navigate from the test class or test method to the system under test.

This is very useful when you want to see test and system under test at the same time. In Test to the left, production to the right, I suggest using a split view in PhpStorm. I find it very convenient to open the class that contains the test first, then quickly navigate to the system under test.

Disadvantages of documenting the system under test

An obvious disadvantage of documenting the system under test is that you need to add annotations or attributes to the test class.

Enforcing the documentation of the system under test

Now that you have decided to document the system under test using annotations or attributes, how can you enforce it?

If you use annotations and friendsofphp/php-cs-fixer, you can enable the php_unit_test_class_requires_covers fixer.

<?php

declare(strict_types=1);

$finder = PhpCsFixer\Finder::create()->in(__DIR__);

$config = new PhpCsFixer\Config();

$config
    ->setFinder($finder)
    ->setRules([
        // ...
        'php_unit_test_class_requires_covers' => true,
        // ...
    ]);

return $config;

This fixer will add a @coversNothing annotation to a test class when the test class does not have an existing @covers or @coversNothing annotation. While this fixer can not add a @covers annotation to the test class for you, it can at least remind you that you need to add it yourself.

In phpunit/phpunit:9.0.0 and below, you can set the forceCoversAnnotation attribute to true in phpunit.xml.

<?xml version="1.0"?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
    forceCoversAnnotation="true"
>
    // ...
</phpunit>

In phpunit/phpunit:10.0.0 and above, you can set the requireCoverageMetadata attribute to true in phpunit.xml.

<?xml version="1.0"?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
    requireCoverageMetadata="true"
>
    // ...
</phpunit>

If you run tests with phpunit/phpunit and execute tests that do not have a @covers or @coversNothing annotation, or CoversClass, CoversFunction or CoversNothing attribute, PHPUnit will mark these tests as risky.

PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.1.15
Configuration: test/Unit/phpunit.xml
Random Seed:   1677075031

R                                                                  1 / 1 (100%)

Time: 00:00.010, Memory: 12.00 MB

There was 1 risky test:

1) Ergebnis\Package\Test\Unit\ExampleTest::testFromStringReturnsExample
This test does not define a code coverage target but is expected to do so

/Users/am/Sites/ergebnis/php-package-template/test/Unit/ExampleTest.php:24

OK, but some tests have issues!
Tests: 1, Assertions: 1, Risky: 1.

Aiding the documentation of the system under test

How can you aid the documentation of the system under test?

When you use PhpStorm to generate a test class, PhpStorm uses a file template you can easily adjust.

On macOS, press CMD + .. Go to Editor and File and Code Templates, and in the list of files, you will find file templates for PHPUnit test classes.

For phpunit\phpunit:9.0.0 and below I use a template similar to the following:

<?php

declare(strict_types=1);

#if (${NAMESPACE})
namespace ${NAMESPACE};
#end

#if (${TESTED_NAME} && ${NAMESPACE} && !${TESTED_NAMESPACE})
use ${TESTED_NAME};
#elseif (${TESTED_NAME} && ${TESTED_NAMESPACE} && ${NAMESPACE} != ${TESTED_NAMESPACE})
use ${TESTED_NAMESPACE}\\${TESTED_NAME};
#end
use PHPUnit\Framework;

/**
#if (${TESTED_NAME} && ${NAMESPACE} && !${TESTED_NAMESPACE})
 * @covers \\${TESTED_NAME}
#elseif (${TESTED_NAME} && ${TESTED_NAMESPACE} && ${NAMESPACE} != ${TESTED_NAMESPACE})
 * @covers \\${TESTED_NAMESPACE}\\${TESTED_NAME}
#end
 */
final class ${NAME} extends Framework\TestCase
{
}

Recommendations

If you use phpunit/phpunit:9.0.0 and below, use @covers annotations to document the system under test on the class level. If there is no clear system under test, use the @coversNothing annotation annotation on the class level. Do not document the system under test on the method level, and do not bother with documenting individual methods - this functionality is not present in phpunit/phpunit:10.0.0. Set the forceCoversAnnotation attribute to true in phpunit.xml.

If you use phpunit/phpunit:10.0.0 and above, use CoversClass attributes to document the system under test on the class level. If there is no clear system under test, use the CoversNothing attribute on the class level. Set the requireCoverageMetadata attribute to true in phpunit.xml.

If you use @covers annotations in phpunit/phpunit and friendsofphp/php-cs-fixer, enable the php_unit_test_class_requires_covers fixer.

Extending PHPUnit with its new event system

2023-02-14T20:15:00+01:00

Extending PHPUnit with its new event system

You can extend phpunit/phpunit by creating and using abstract test classes and traits - or by using the event system of phpunit/phpunit.

As one of the contributors to the new event system of phpunit/phpunit, I will give you an overview of the iterations of the event systems of phpunit/phpunit, show how you can migrate from any of the previous event systems to PHPUnit's new event system, and share insights on components and the events in the new event system of PHPUnit.

tl;dr

Refer to the official phpunit/phpunit documentation for learning how to extend PHPUnit.

Inspect ergebnis/phpunit-slow-test-detector, an extension for detecting slow tests in PHPUnit.

This extension, inspired by johnkary/phpunit-speedtrap, uses the new event system of phpunit/phpunit. I started working on this package on January 23, 2021, so it is probably the first extension using the new event system of phpunit/phpunit. It provided helpful feedback during the development of the new event system of phpunit/phpunit.

Iterations of the event system

So far, the event system of phpunit/phpunit has seen three iterations:

the test listener event system
the hooks event system
the new event system

Test listener event system

The first iteration of the event system of phpunit/phpunit, the test listener event system, has been available since the release of phpunit/phpunit:0.3 in 2002.

The test listener event system has been deprecated since the release of phpunit/phpunit:8.0.0 on February 1, 2019, and it has been removed with the release of phpunit/phpunit:10.0.0 on February 3, 2023.

Events in the test listener event system

The test listener event system in phpunit/phpunit:9.6.3 ships with a single TestListener interface that defines nine methods.

<?php

declare(strict_types=1);

namespace PHPUnit\Framework;

interface TestListener
{
    public function addError(
        Test $test,
        \Throwable $t,
        float $time
    ): void;

    public function addWarning(
        Test $test,
        Warning $e,
        float $time
    ): void;

    public function addFailure(
        Test $test,
        AssertionFailedError $e,
        float $time
    ): void;

    public function addIncompleteTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void;

    public function addRiskyTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void;

    public function addSkippedTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void;

    public function startTestSuite(TestSuite $suite): void;

    public function endTestSuite(TestSuite $suite): void;

    public function startTest(Test $test): void;

    public function endTest(
        Test $test,
        float $time
    ): void;
}

Each of the nine methods in the TestListener interface corresponds to an event during a test run. When you have registered the test listener, phpunit/phpunit will invoke these methods as it sees fit.

Implementing an extension using the test listener event system

To implement an extension using the test listener event system, you must create a class that implements the TestListener interface.

Here is an example of an implementation of the TestListener interface from johnkary/phpunit-speedtrap:4.0.1, a popular extension that detects and reports slow tests - and can even fail a test run.

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Listener;

use PHPUnit\Framework;

class SpeedTrapListener implements Framework\TestListener
{
    use Framework\TestListenerDefaultImplementation;

    // ...

    public function endTest(
        Framework\Test $test,
        float $time
    ): void
    {
        // ...
    }

    public function startTestSuite(Framework\TestSuite $suite): void
    {
        // ...
    }

    public function endTestSuite(Framework\TestSuite $suite): void
    {
        // ...
    }

    // ...
}

This test listener uses the TestListenerDefaultImplementation trait.

The trait conveniently provides stubs for methods that the TestListener interface defines. If you import the trait into your test listener, you can focus on implementing methods for events that concern you - and ignore the rest.

<?php

declare(strict_types=1);

namespace PHPUnit\Framework;

trait TestListenerDefaultImplementation
{
    public function addError(
        Test $test,
        \Throwable $t,
        float $time
    ): void {
    }

    public function addWarning(
        Test $test,
        Warning $e,
        float $time
    ): void {
    }

    public function addFailure(
        Test $test,
        AssertionFailedError $e,
        float $time
    ): void {
    }

    public function addIncompleteTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void {
    }

    public function addRiskyTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void {
    }

    public function addSkippedTest(
        Test $test,
        \Throwable $t,
        float $time
    ): void {
    }

    public function startTestSuite(TestSuite $suite): void
    {
    }

    public function endTestSuite(TestSuite $suite): void
    {
    }

    public function startTest(Test $test): void
    {
    }

    public function endTest(
        Test $test,
        float $time
    ): void {
    }
}

To allow the configuration of a test listener, you need to add a constructor to your test listener:

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Listener;

use PHPUnit\Framework;

class SpeedTrapListener implements TestListener
{
    use Framework\TestListenerDefaultImplementation;

    // ...

    public function __construct(array $options = [])
    {
        // ...
    }

    // ...
}

Registering an extension using the test listener event system

To register an extension using the test listener event system, you need to configure it using the <listeners> and <listener> elements of phpunit.xml.

The following configuration registers johnkary/phpunit-speedtrap:4.0.1 with default options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <listeners>
        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
    </listeners>
</phpunit>

The following configuration registers johnkary/phpunit-speedtrap:4.0.1 with custom options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <listeners>
        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener">
            <arguments>
                <array>
                    <element key="slowThreshold">
                        <integer>250</integer>
                    </element>
                    <element key="stopOnSlow">
                        <boolean>true</boolean>
                    </element>
                </array>
            </arguments>
        </listener>
    </listeners>
</phpunit>

phpunit/phpunit provides facilities for casting values from the <arguments> element. phpunit/phpunit will pass these values to the constructor of the test listener.

In the example above, phpunit/phpunit will pass the following value to the constructor of SpeedTrapListener:

[
    'slowThreshold' => 250,
    'stopOnSlow'    => true,
]

Disadvantages of the test listener event system

As you have seen above, the test listener system has a few disadvantages.

To implement a test listener, you need to create a class that implements all methods of the TestListener interface, even when you are only interested in a single or a subset of all available events. This requirement violates the interface segregation principle.

The methods of the test listener accept mutable implementations of Test and mutable instances of TestSuite. Passing around mutable objects has an undesirable effect: a test listener can modify the outcome of test runs by manipulating these mutable objects.

Examples of test listener implementations that modify the outcome of test runs include:

hmlb/phpunit-vw, which makes failing tests pass when it has detected that it runs in a continuous integration system
johnkary/phpunit-speedtrap:4.0.1, which optionally stops a test run when it has detected a slow test

Deprecation and removal of the test listener event system

The test listener event system has been deprecated since the release of phpunit/phpunit:8.0.0 on February 1, 2019. It has been removed with the release of phpunit/phpunit:10.0.0 on February 3, 2023.

Hooks event system

The second iteration of the event system of phpunit/phpunit, the hooks event system, has been available since the release of phpunit/phpunit:7.1.0 on April 6, 2018.

The hooks event system has been deprecated since the release of phpunit/phpunit:8.5.23 on February 1, 2022. It has been removed with the release of phpunit/phpunit:10.0.0 on February 3, 2023.

Events in the hooks event system

The hooks event system in phpunit/phpunit:9.6.3 ships with eleven segregated interfaces, each of which defines a single method.

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface BeforeFirstTestHook extends Hook
{
    public function executeBeforeFirstTest(): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface BeforeTestHook extends TestHook
{
    public function executeBeforeTest(string $test): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterTestHook extends TestHook
{
    public function executeAfterTest(
        string $test,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterIncompleteTestHook extends TestHook
{
    public function executeAfterIncompleteTest(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterRiskyTestHook extends TestHook
{
    public function executeAfterRiskyTest(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterSkippedTestHook extends TestHook
{
    public function executeAfterSkippedTest(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterSuccessfulTestHook extends TestHook
{
    public function executeAfterSuccessfulTest(
        string $test,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterTestErrorHook extends TestHook
{
    public function executeAfterTestError(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterTestFailureHook extends TestHook
{
    public function executeAfterTestFailure(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterTestWarningHook extends TestHook
{
    public function executeAfterTestWarning(
        string $test,
        string $message,
        float $time
    ): void;
}

<?php

declare(strict_types=1);

namespace PHPUnit\Runner;

interface AfterLastTestHook extends Hook
{
    public function executeAfterLastTest(): void;
}

Unsurprisingly, each method corresponds to an event during a test run. When you have registered an extension with the hooks event system, phpunit/phpunit will invoke these methods as it sees fit.

Implementing an extension using the hooks event system

To implement an extension using the hooks event system, you must create one or more classes that implement one or more hook interfaces for events of your concern.

Here is an example of an implementation of an extension using the hooks event system from johnkary/phpunit-speedtrap:dev-master#a05623c (not yet released at the time of writing):

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Runner;

class SpeedTrap implements
    Runner\AfterSuccessfulTestHook,
    Runner\BeforeFirstTestHook,
    Runner\AfterLastTestHook
{
    // ...

    public function executeAfterSuccessfulTest(
        string $test,
        float $time
    ): void {
        // ...
    }

    public function executeBeforeFirstTest(): void
    {
        // ...
    }

    public function executeAfterLastTest(): void
    {
        // ...
    }

    // ...
}

To allow the configuration of an extension using the hooks event system, you need to add a constructor to your extension:

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Runner;

class SpeedTrap implements
    Runner\AfterSuccessfulTestHook,
    Runner\BeforeFirstTestHook,
    Runner\AfterLastTestHook
{
    // ...

    public function __construct(array $options = [])
    {
        // ...
    }

    // ...
}

Registering an extension using the hooks event system

To register an extension using the hooks event system, you need to configure it using the <extensions> and <extension> elements of phpunit.xml.

The following example registers johnkary/phpunit-speedtrap:dev-master#a05623c with default options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <extensions>
        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
    </extensions>
</phpunit>

The following example registers johnkary/phpunit-speedtrap:dev-master#a05623c with custom options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <extensions>
        <listener class="JohnKary\PHPUnit\Extension\SpeedTrap">
            <extension>
                <array>
                    <element key="slowThreshold">
                        <integer>250</integer>
                    </element>
                </array>
            </extension>
        </listener>
    </extensions>
</phpunit>

phpunit/phpunit provides facilities for casting values from the <arguments> element. phpunit/phpunit will pass these values to the constructor of the extension.

In the example above, phpunit/phpunit will pass the following value as $options argument to the constructor of SpeedTrapListener:

[
    'slowThreshold' => 250,
]

Migrating an extension from the test listener event system to the hooks event system

To migrate an extension from the test listener to the hooks event system, you need to require and support one ore more of phpunit/phpunit:^7.1.0, phpunit/phpunit:^8.0.0, and phpunit/phpunit:^9.0.0.

Next, instead of implementing the TestListener interface, you need to change the extension to implement one or more interfaces from the hooks event system. Consequently, you must remove the import of the TestListenerDefaultImplementation trait.

Furthermore, since the method signatures of the hook interfaces are different from the method signatures of the TestListener interface, you need to change the extension so it can work with scalars instead of mutable objects.

Moreover, since the extension can not modify test outcomes anymore, you need to remove functionality that attempts to do so. If the extension's purpose is solely the modification of test outcomes, it will not work with the test listener event system.

Finally, instead of using the <listeners> and <listener> elements, you need to instruct users of your extension to use the <extensions> and <extension> elements of phpunit.xml.

Here is a pull request by John Kary, migrating johnkary/phpunit-speedtrap from the test listener event system to the hooks event system.

Advantages of the hooks event system

The hooks event system has a few advantages compared to the test listener event system.

To implement hooks, you no longer need to create a class that implements methods for events that are not of your concern.

The methods of the hooks interfaces no longer accept mutable objects, so it is no longer possible to modify the outcome of a test run.

Disadvantages of the hooks event system

However, the hooks event system also has at least one disadvantage compared to the test listener event system.

Since the methods of the hooks interfaces only accept scalars, you have to do more work in an extension using the hooks event system yourself.

Instead of passing around scalars, the event system could benefit from additional test-related information and value objects.

Deprecation and removal of the hooks event system

The hooks event system has been deprecated since the release of phpunit/phpunit:8.5.23 on February 1, 2022. It has been removed with the release of phpunit/phpunit:10.0.0 on February 3, 2023.

New event system

The third and current iteration of the event system of phpunit/phpunit, the new event system, has been a long time coming and is finally available since the release of phpunit/phpunit:10.0.0 on February 3, 2023.

Initial work on the new event system started when the phpunit/phpunit development team - Sebastian Bergmann, Arne Blankerts, Stefan Priebsch, Ewout Pieter den Ouden, and I - attended the EU-FOSSA hackathon from October 5 to October 6, 2019, in Brussels.

Arne Blankerts, Andreas Möller, and Ewout Pieter den Ouden (from left to right) at the EU-FOSSA 2019 hackathon. Not pictured: Sebastian Bergmann (who took the picture) and Stefan Priebsch.

Find out more about the release of phpunit/phpunit:10.0.0 in the official release announcement.

Components in the new event system

The new event system in phpunit/phpunit:10.0.7 ships with an event Facade, an event Emitter interface, a DispatchingEmitter, a Dispatcher interface, a SubscribableDispatcher interface, a few implementations of the Dispatcher and SubscribableDispatcher interfaces, and an extension Facade.

The event Facade provides methods that allow registering subscribers and tracers and, most importantly, registers known events, and, most importantly, gives access to the event Emitter.

The event Facade is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
final class Facade
{
    // ...

    public static function registerSubscribers(Subscriber ...$subscribers): void
    {
        // ...
    }

    public static function registerSubscriber(Subscriber $subscriber): void
    {
        // ...
    }

    public static function registerTracer(Tracer\Tracer $tracer): void
    {
        // ...
    }

    public static function emitter(): Emitter
    {
        // ...
    }

    // ...
}

The event Emitter interface provides methods that allow emitting events.

The event Emitter is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

use PHPUnit\Framework;

/**
 * @internal
 */
interface Emitter
{
    public function applicationStarted(): void;

    // ...

    public function testAssertionFailed(
        mixed $value,
        Framework\Constraint\Constraint $constraint,
        string $message
    ): void;

    // ...

    public function applicationFinished(int $shellExitCode): void;
}

The DispatchingEmitter implements the event Emitter interface, creates events, and uses a Dispatcher to dispatch these events.

The DispatchingEmitter is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

use PHPUnit\Framework;

/**
 * @internal
 */
final class DispatchingEmitter implements Emitter
{
    // ...

    public function applicationStarted(): void
    {
        // ...
    }

    public function testAssertionFailed(
        mixed $value,
        Framework\Constraint\Constraint $constraint,
        string $message
    ): void {
        // ...
    }

    // ...

    public function applicationFinished(int $shellExitCode): void
    {
        // ...
    }

    // ...
}

The Dispatcher defines a single method for dispatching an event.

The Dispatcher interface is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
interface Dispatcher
{
    public function dispatch(Event $event): void;
}

The CollectingDispatcher implements the Dispatcher interface and collects events.

The CollectingDispatcher is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
final class CollectingDispatcher implements Dispatcher
{
    // ...

    public function dispatch(Event $event): void
    {
        // ...
    }

    public function flush(): EventCollection
    {
        // ...
    }
}

The SubscribableDispatcher interface extends the Dispatcher interface and defines methods for registering subscribers and tracers.

The SubscribableDispatcher interface is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
interface SubscribableDispatcher extends Dispatcher
{
    public function registerSubscriber(Subscriber $subscriber): void;

    public function registerTracer(Tracer\Tracer $tracer): void;
}

The DirectDispatcher implements the SubscribableDispatcher interface and immediately traces an event with all tracers, and notifies all subscribers that subscribe to an event of that event.

The DirectDispatcher is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
final class DirectDispatcher implements SubscribableDispatcher
{
    // ...

    public function registerTracer(Tracer\Tracer $tracer): void
    {
        // ...
    }

    public function registerSubscriber(Subscriber $subscriber): void
    {
        // ...
    }

    public function dispatch(Event $event): void
    {
        // ...
    }
}

The DeferringDispatcher implements the SubscribableDispatcher interface and defers tracing events and notifying subscribers of an event until it is flushed.

The DeferringDispatcher is for internal use only.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

/**
 * @internal
 */
final class DeferringDispatcher implements SubscribableDispatcher
{
    // ...

    public function registerTracer(Tracer\Tracer $tracer): void
    {
        // ...
    }

    public function registerSubscriber(Subscriber $subscriber): void
    {
        // ...
    }

    public function dispatch(Event $event): void
    {
        // ...
    }

    public function flush(): void
    {
        // ...
    }
}

The extension Facade provides methods for registering subscribers and traces.

<?php

declare(strict_types=1);

namespace PHPUnit\Runner\Extension;

use PHPUnit\Event;

final class Facade
{
    public function registerSubscribers(Event\Subscriber ...$subscribers): void
    {
        // ...
    }

    public function registerSubscriber(Event\Subscriber $subscriber): void
    {
        // ...
    }

    public function registerTracer(Event\Tracer $tracer): void
    {
        // ...
    }
}

Events in the new event system

In addition to the components above, the new event system in phpunit/phpunit:10.0.7 ships with an Event interface and sixty-three concrete events, a Subscriber interface and sixty-three event subscriber interfaces, a Tracer interface, and an Extension interface.

The Event interface declares methods that give access to basic telemetry information, such as duration and memory usage, and a string representation of an event.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

interface Event
{
    public function telemetryInfo(): Telemetry\Info;

    public function asString(): string;
}

All sixty-three events implement the Event interface and provide access to test-related information available when the event occurred and of interest to phpunit/phpunit internally and potential users of the new event system.

PHPUnit\Event\Application\Started
PHPUnit\Event\Application\Finished
PHPUnit\Event\Test\MarkedIncomplete
PHPUnit\Event\Test\AfterLastTestMethodCalled
PHPUnit\Event\Test\AfterLastTestMethodFinished
PHPUnit\Event\Test\AfterTestMethodCalled
PHPUnit\Event\Test\AfterTestMethodFinished
PHPUnit\Event\Test\AssertionSucceeded
PHPUnit\Event\Test\AssertionFailed
PHPUnit\Event\Test\BeforeFirstTestMethodCalled
PHPUnit\Event\Test\BeforeFirstTestMethodErrored
PHPUnit\Event\Test\BeforeFirstTestMethodFinished
PHPUnit\Event\Test\BeforeTestMethodCalled
PHPUnit\Event\Test\BeforeTestMethodFinished
PHPUnit\Event\Test\ComparatorRegistered
PHPUnit\Event\Test\ConsideredRisky
PHPUnit\Event\Test\DeprecationTriggered
PHPUnit\Event\Test\Errored
PHPUnit\Event\Test\ErrorTriggered
PHPUnit\Event\Test\Failed
PHPUnit\Event\Test\Finished
PHPUnit\Event\Test\NoticeTriggered
PHPUnit\Event\Test\Passed
PHPUnit\Event\Test\PhpDeprecationTriggered
PHPUnit\Event\Test\PhpNoticeTriggered
PHPUnit\Event\Test\PhpunitDeprecationTriggered
PHPUnit\Event\Test\PhpunitErrorTriggered
PHPUnit\Event\Test\PhpunitWarningTriggered
PHPUnit\Event\Test\PhpWarningTriggered
PHPUnit\Event\Test\PostConditionCalled
PHPUnit\Event\Test\PostConditionFinished
PHPUnit\Event\Test\PreConditionCalled
PHPUnit\Event\Test\PreConditionFinished
PHPUnit\Event\Test\PreparationStarted
PHPUnit\Event\Test\Prepared
PHPUnit\Event\Test\Skipped
PHPUnit\Event\Test\WarningTriggered
PHPUnit\Event\Test\MockObjectCreated
PHPUnit\Event\Test\MockObjectForAbstractClassCreated
PHPUnit\Event\Test\MockObjectForIntersectionOfInterfacesCreated
PHPUnit\Event\Test\MockObjectForTraitCreated
PHPUnit\Event\Test\MockObjectFromWsdlCreated
PHPUnit\Event\Test\PartialMockObjectCreated
PHPUnit\Event\Test\TestProxyCreated
PHPUnit\Event\Test\TestStubCreated
PHPUnit\Event\Test\TestStubForIntersectionOfInterfacesCreated
PHPUnit\Event\TestRunner\BootstrapFinished
PHPUnit\Event\TestRunner\Configured
PHPUnit\Event\TestRunner\EventFacadeSealed
PHPUnit\Event\TestRunner\ExecutionFinished
PHPUnit\Event\TestRunner\ExecutionStarted
PHPUnit\Event\TestRunner\ExtensionLoadedFromPhar
PHPUnit\Event\TestRunner\ExtensionBootstrapped
PHPUnit\Event\TestRunner\Finished
PHPUnit\Event\TestRunner\Started
PHPUnit\Event\TestRunner\DeprecationTriggered
PHPUnit\Event\TestRunner\WarningTriggered
PHPUnit\Event\TestSuite\Filtered
PHPUnit\Event\TestSuite\Finished
PHPUnit\Event\TestSuite\Loaded
PHPUnit\Event\TestSuite\Skipped
PHPUnit\Event\TestSuite\Sorted
PHPUnit\Event\TestSuite\Started

Here is the AssertionFailed event:

<?php

declare(strict_types=1);

namespace PHPUnit\Event\Test;

use PHPUnit\Event;

final class AssertionFailed implements Event\Event
{
    // ...

    public function telemetryInfo(): Event\Telemetry\Info
    {
        return $this->telemetryInfo;
    }

    public function value(): string
    {
        return $this->value;
    }

    public function count(): int
    {
        return $this->count;
    }

    public function message(): string
    {
        return $this->message;
    }

    public function asString(): string
    {
        $message = '';

        if (!empty($this->message)) {
            $message = sprintf(
                ', Message: %s',
                $this->message
            );
        }

        return sprintf(
            'Assertion Failed (Constraint: %s, Value: %s%s)',
            $this->constraint,
            $this->value,
            $message
        );
    }
}

The Subscriber interface is a marker interface for all sixty-three event subscribers.

<?php

declare(strict_types=1);

namespace PHPUnit\Event;

interface Subscriber
{
}

Here is the AssertionFailedSubscriber interface:

<?php

declare(strict_types=1);

namespace PHPUnit\Event\Test;

use PHPUnit\Event;

interface AssertionFailedSubscriber extends Event\Subscriber
{
    public function notify(AssertionFailed $event): void;
}

The Tracer interface declares a single method that allows phpunit/phpunit to notify a concrete tracer about every event that occurred during the execution of PHPUnit.

<?php

declare(strict_types=1);

namespace PHPUnit\Event\Tracer;

use PHPUnit\Event;

interface Tracer
{
    public function trace(Event\Event $event): void;
}

The Extension interface declares a method that accepts an immutable configuration object, an extension facade, and an immutable parameter collection and allows to register event subscribers and event tracers with the new event system of phpunit/phpunit.

<?php

declare(strict_types=1);

namespace PHPUnit\Runner\Extension;

use PHPUnit\TextUI;

interface Extension
{
    public function bootstrap(
        TextUI\Configuration\Configuration $configuration,
        Facade $facade,
        ParameterCollection $parameters
    ): void;
}

Implementing event subscribers in the new event system

To implement an event subscriber in the new event system, you must create a class that implements an event subscriber interface corresponding to the event.

By design, an event subscriber processes a single event only.

If you are interested in more than one event, you must create one or more subscribers per event.

Here is an example of an implementation of an event subscriber using the new event system from localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from a pull request that has not yet been merged at the time of writing):

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Event;

final class RecordThatTestHasBeenPrepared implements Event\Test\PreparedSubscriber
{
    public function __construct(private readonly SpeedTrap $speedTrap)
    {
    }

    public function notify(Event\Test\Prepared $event): void
    {
        $this->speedTrap->recordThatTestHasBeenPrepared(
            $event->test(),
            $event->telemetryInfo()->time(),
        );
    }
}

Here is another example of an implementation of an event subscriber using the new event system from localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from the same pull request):

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Event;

final class RecordThatTestHasPassed implements Event\Test\PassedSubscriber
{
    public function __construct(private readonly SpeedTrap $speedTrap)
    {
    }

    public function notify(Event\Test\Passed $event): void
    {
        $this->speedTrap->recordThatTestHasPassed(
            $event->test(),
            $event->telemetryInfo()->time(),
        );
    }
}

Here is one more example of an implementation of an event subscriber using the new event system from localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from the same pull request):

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Event;

final class ShowSlowTests implements Event\TestRunner\ExecutionFinishedSubscriber
{
    public function __construct(private readonly SpeedTrap $speedTrap)
    {
    }

    public function notify(Event\TestRunner\ExecutionFinished $event): void
    {
        $this->speedTrap->showSlowTests();
    }
}

As you can see, the event subscribers are small. Each event subscriber serves a simple purpose and delegates the actual work to another service.

How you design your event subscribers largely depends on whether you need to share state between them.

Implementing event tracers in the new event system

To implement an event tracer in the new event system, you must create a class that implements the Tracer interface.

By design, an event tracer processes all events.

Unless you are interested in all events, you probably want to implement an event subscriber instead.

Here is the EventLogger, an example of an implementation of a tracer from phpunit/phpunit:10.0.7.

<?php

declare(strict_types=1);

namespace PHPUnit\Logging;

use PHPUnit\Event;

final class EventLogger implements Event\Tracer\Tracer
{
    // ...

    public function trace(Event\Event $event): void
    {
        $telemetryInfo = $this->telemetryInfo($event);
        $indentation   = PHP_EOL . str_repeat(' ', strlen($telemetryInfo));
        $lines         = explode(PHP_EOL, $event->asString());

        file_put_contents(
            $this->path,
            $telemetryInfo . implode($indentation, $lines) . PHP_EOL,
            FILE_APPEND | LOCK_EX
        );
    }

    // ...
}

The EventLogger is one of the first implementations in phpunit/phpunit:10.0.0 that uses the new event system. It dumps string representations of all events into a text file.

Implementing an extension in the new event system

To allow others to register your event subscribers or event tracers, you must create a class that implements the Extension interface.

Here is an example of an implementation of an extension using the new event system from localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from a pull request that has not yet been merged at the time of writing) with default options:

<?php

declare(strict_types=1);

namespace JohnKary\PHPUnit\Extension;

use PHPUnit\Runner;
use PHPUnit\TextUI;

final class SpeedTrapExtension implements Runner\Extension\Extension
{
    public function bootstrap(
        TextUI\Configuration\Configuration $configuration,
        Runner\Extension\Facade $facade,
        Runner\Extension\ParameterCollection $parameters
    ): void {
        if (getenv('PHPUNIT_SPEEDTRAP') === 'disabled') {
            return;
        }

        $slowThreshold = 500;

        if ($parameters->has('slowThreshold')) {
            $slowThreshold = (int) $parameters->get('slowThreshold');
        }

        $reportLength = 10;

        if ($parameters->has('reportLength')) {
            $reportLength = (int) $parameters->get('reportLength');
        }

        $speedTrap = new SpeedTrap(
            $slowThreshold,
            $reportLength
        );

        $facade->registerSubscribers(
            new RecordThatTestHasBeenPrepared($speedTrap),
            new RecordThatTestHasPassed($speedTrap),
            new ShowSlowTests($speedTrap),
        );
    }
}

As you can see from the example above, the SpeedTrapExtension checks whether an environment variable was set to determine whether it should register itself with the extension facade or not.

Next, it declares default configuration values and inspects the parameter collection to determine whether it should override any default configuration values.

Finally, it creates a service and event subscribers and registers these event subscribers using the extension facade.

Registering an extension using the new event system

To register an extension using the new event system, you need to configure it using the <extensions>, <extension>, and <parameter> elements of phpunit.xml.

The following example registers localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from a pull request that has not yet been merged at the time of writing) with default options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <extensions>
        <bootstrap class="JohnKary\PHPUnit\Extension\SpeedTrapExtension" />
    </extensions>
</phpunit>

The following example registers localheinz/phpunit-speedtrap:dev-feature-phpunit-10 (from a pull request that has not yet been merged at the time of writing) with custom options:

<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
    bootstrap="vendor/autoload.php"
>
    <extensions>
        <bootstrap class="JohnKary\PHPUnit\Extension\SpeedTrapExtension">
            <parameter name="slowThreshold" value="500" />
        </bootstrap>
    </extensions>
</phpunit>

Migrating an extension from the hooks event system to the new event system

To migrate an extension from the hooks event system to the new event system, you need to require and support phpunit/phpunit:^10.0.0.

Next, instead of implementing the hook interfaces, you need to extract event subscribers from your extension that subscribe to the corresponding events of the new event system.

Additionally, you must create a class that implements the Extension interface and registers your event subscribers. If your extension is configurable, it needs to inspect the parameter collection and process parameters from there instead of relying on phpunit/phpunit to cast values from phpunit.xml.

Finally, instead of using the <extensions> and <extension> elements, you need to instruct users of your extension to use the <extensions> and <bootstrap> elements of phpunit.xml.

Here is a pull request from me, migrating johnkary/phpunit-speedtrap from the hooks event system to the new event system. Does the code look familiar? You have seen it before in this article!

Advantages of the new event system

While implementing the new event system, the phpunit/phpunit development team identified many new events. The previous test listener and hooks event systems are aware of less than a dozen events. The new event system has more granularity, with a whopping sixty-three events.

All of these events are immutable and provide access to more data with higher accuracy.

Using the new event system internally, the phpunit/phpunit development team cleaned up a lot of code and simplified maintenance.

Disadvantages of the new event system

Admittedly, an obvious disadvantage of the new event system is that developers interested in supporting the new event system need to make some effort to migrate existing extensions.

Questions

Do you have any questions regarding the new event system of phpunit/phpunit? Do you have any feedback? Do you know of any exciting new extensions based on PHPUnit's new event system?

Indenting YAML files

2023-02-06T14:25:00+01:00

Indenting YAML files

YAML files are omnipresent: whether you use continuous integration systems, external code quality tools, or container virtualization, the chances are that you are dealing with YAML files.

At first glance, the YAML specification is straightforward:

dashes create sequences
colons separate key-value pairs to create mappings
indentation spaces can create structure
separation spaces separate tokens

Whitespace is essential - but how much?

I recommend using two spaces of indentation for YAML files. But let's take a closer look!

Sequences

A flow sequence contains values separated by commas and surrounded by square brackets.

The example below shows a flow sequence.

["8.0", "8.1", "8.2"]

A block sequence is a series of nodes, each denoted by a leading dash.

The example below shows a block sequence.

- "8.0"
- "8.1"
- "8.2"

According to the YAML specification, the examples above are equivalent.

Mappings

A flow mapping contains values separated by commas and surrounded by curly braces.

The example below shows a flow mapping.

{ name: "bug", color: "ee0701" }

A block mapping is a series of entries, each representing pairs of keys and values.

The example below shows a block mapping.

name: "bug"
color: "ee0701"

According to the YAML specification, the examples above are equivalent.

Indentation spaces

Indentation spaces are zero or more space characters at the beginning of a line.

Following a key and a colon, you start a new block mapping by indenting a line of YAML with more spaces than the previous line. By indenting a line of YAML with fewer spaces than the previous line, you close a block mapping.

According to the YAML specification, the amount of indentation is an implementation detail.

The example below shows a combination of sequences and mappings using two spaces of indentation. Note how the sequence assigned to the mapping is indented.

labels:
  - name: "bug"
    color: "ee0701"

  - name: "enhancement"
    color: "0e8a16"

repository:
  allow_merge_commit: true
  allow_rebase_merge: false
  default_branch: "main"

The example below shows a combination of sequences and mappings using two spaces of indentation. Note how the sequence assigned to the mapping does not use indentation.

labels:
- name: "bug"
  color: "ee0701"

- name: "enhancement"
  color: "0e8a16"

repository:
  allow_merge_commit: true
  allow_rebase_merge: false
  default_branch: "main"

The example below shows a combination of sequences and mappings using four (and two) spaces of indentation. Note how the sequence assigned to the mapping inconsistently uses two spaces of indentation.

labels:
    - name: "bug"
      color: "ee0701"

    - name: "enhancement"
      color: "0e8a16"

repository:
    allow_merge_commit: true
    allow_rebase_merge: false
    default_branch: "main"

The example below shows a combination of sequences and mappings using four spaces of indentation. Note how the sequence assigned to the mapping consistently uses four spaces of indentation.

labels:
    -   name: "bug"
        color: "ee0701"

    -   name: "enhancement"
        color: "0e8a16"

repository:
    allow_merge_commit: true
    allow_rebase_merge: false

The example below shows a combination of sequences and mappings using four spaces of indentation. Note how the sequence assigned to the mapping consistently uses four spaces of indentation and how the mappings in the sequence wrap to ensure consistent indentation.

labels:
    -
        name: "bug"
        color: "ee0701"

    -
        name: "enhancement"
        color: "0e8a16"

repository:
    allow_merge_commit: true
    allow_rebase_merge: false

According to the YAML specification, the above examples are equivalent.

Separation spaces

Separation spaces are sequences of space or tab characters outside of indentation and string literals for separating tokens within a single line. For example, you use spaces and tabs to separate a colon and a value when creating mappings or a dash from a value when creating block sequences.

The example below uses a single space to separate colons and dashes from values.

labels:
  - name: "bug"
    color: "ee0701"

  - name: "enhancement"
    color: "0e8a16"

repository:
  allow_merge_commit: true
  allow_rebase_merge: false
  default_branch: "main"

The example below uses varying numbers of spaces before and a single space after colons to separate colons from values.

labels:
  - name : "bug"
    color: "ee0701"

  - name : "enhancement"
    color: "0e8a16"

repository:
  allow_merge_commit: true
  allow_rebase_merge: false
  default_branch    : "main"

The example below uses varying numbers of spaces after colons to separate colons from values.

labels:
  - name:  "bug"
    color: "ee0701"

  - name:  "enhancement"
    color: "0e8a16"

repository:
  allow_merge_commit: true
  allow_rebase_merge: false
  default_branch:     "main"

According to the YAML specification, the above examples are equivalent.

Indentation in YAML in the real world

So how do people use indentation spaces in the real world?

Indentation of block sequences and mappings with two spaces

The following indent block sequences and mappings with two spaces:

Indentation of block mappings with two spaces

The following indent block mappings with two spaces but do not indent block sequences:

Indentation of block sequences and mappings with four spaces

The following indent block sequences and mappings with four spaces:

Indentation of block mappings with four spaces

The following indent block mappings with four spaces, but do not indent block sequences:

Recommendation

Avoid YAML

Avoid YAML when possible.

For example, it is not necessary to configure a Symfony application with YAML files. Symfony not only supports YAML, but also XML (cough), and PHP configuration file formats. You can easily convert Symfony YAML (and XML) configuration files to PHP files with symplify/config-transformer.

Use two spaces of indentation

Do yourself a favor, and indent YAML files with two instead of four spaces. When you use two spaces of indentation for block sequences and mappings, you can avoid inconsistent indentation and awkward wrapping.

As you can see from the collection above, most services that use YAML files implicitly suggest to use two spaces of indentation.

Use EditorConfig

Use EditorConfig to configure indentation size and indentation type for YAML files in every project that uses YAML files. Most IDEs have built-in support for EditorConfig and will adjust their code style configuration.

Here is an example of an .editorconfig that configures an indentation of two spaces for YAML files:

[*.{yaml,yml}]
indent_size = 2
indent_style = space

Use Yamllint

Use Yamllint to lint YAML files in local development environments and continuous integration systems.

Here is an example of a .yamllint.yaml that configures an indentation of two spaces and a separation of one space.

extends: "default"

ignore: |
  .build/
  vendor/

rules:
  braces:
    max-spaces-inside-empty: 0
    max-spaces-inside: 1
    min-spaces-inside-empty: 0
    min-spaces-inside: 1
  brackets:
    max-spaces-inside-empty: 0
    max-spaces-inside: 0
    min-spaces-inside-empty: 0
    min-spaces-inside: 0
  colons:
    max-spaces-after: 1
    max-spaces-before: 0
  commas:
    max-spaces-after: 1
    max-spaces-before: 0
    min-spaces-after: 1
  comments:
    ignore-shebangs: true
    min-spaces-from-content: 1
    require-starting-space: true
  comments-indentation: "enable"
  document-end:
    present: false
  document-start:
    present: false
  indentation:
    check-multi-line-strings: false
    indent-sequences: true
    spaces: 2
  empty-lines:
    max-end: 0
    max-start: 0
    max: 1
  empty-values:
    forbid-in-block-mappings: true
    forbid-in-flow-mappings: true
  hyphens:
    max-spaces-after: 2
  key-duplicates: "enable"
  key-ordering: "disable"
  line-length: "disable"
  new-line-at-end-of-file: "enable"
  new-lines:
    type: "unix"
  octal-values:
    forbid-implicit-octal: true
  quoted-strings:
    quote-type: "double"
  trailing-spaces: "enable"
  truthy: "enable"

yaml-files:
  - "*.yaml"
  - "*.yml"

Documenting namespaces for test code in composer.json

2023-01-29T13:25:00+01:00

Documenting namespaces for test code in composer.json

When you build an application or library and use composer for autoloading, you typically configure one or more autoloaders for production code in the autoload section of composer.json.

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

phpunit/phpunit, the popular testing framework, will search directories configured in phpunit.xml or passed as arguments to the test runner for instantiable classes that directly or indirectly extend PHPUnit\Framework\TestCase and with a class name ending with Test.

phpbench/phpbench, the popular benchmarking framework, will search a directory passed to the test runner for instantiable classes with a class name ending with Bench.

Neither of these tools is concerned with whether these classes are declared in namespaces or can be autoloaded.

So why bother configuring an autoloader for test code in the autoload-dev section of composer.json?

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "App\\Test\\": "test/"
    }
  }
}

Configuring an autoloader for test code in the autoload-dev section of composer.json has the following advantages:

You document the namespace for tests for yourself and other developers.

When other developers join your closed-source project or want to contribute to your open-source project, or even when you pick up work on this project after a pause, everyone will understand which namespace they should declare in tests.

By documenting the namespace for tests in the autoload-dev section of composer.json, you can avoid confusing other developers or repeatedly having to answer the question of which namespace you should use.
You document the namespace and allow autoloading of abstract test cases, test helpers, test doubles, data providers, and other helpful objects.

When your project grows, you may extract abstract test cases to share functionality across test cases when inheritance is an option. Alternatively, you may implement one or more helper traits to share functionality across test cases when inheritance is not an option. For example, the PHP framework of your choice may ship with abstract test cases that you need to extend, but you still want to reuse functionality.

When you have had your share of mocking frameworks, you may prefer to implement test doubles for specific scenarios by hand.

When you find that your tests could benefit from reusing data providers, you may want to extract data providers into classes.

When you extensively use data providers with complex scenarios, you may decide to extract test scenarios into value objects.

By documenting the namespace for auxiliary test code in the autoload-dev section of composer.json, you acknowledge and encourage developers to extract functionality in abstract test cases, test helpers, test doubles, data providers, and other helpful objects into autoloadable classes.
You document the namespace for your favorite IDE.

When PhpStorm indexes and analyzes a project, it also inspects composer.json and synchronizes the autoloading configuration with the PHP namespace configuration in the project.

When you create classes or test cases using the user interface of PhpStorm, it creates classes and test cases in the appropriate directories based on the namespace configuration.

When you copy or move classes, or move or rename namespaces using the user interface of PhpStorm, PhpStorm will move classes to the appropriate location based on the namespace configuration.

By documenting the namespace for test code in the autoload-dev section of composer.json, you avoid having to configure namespace mappings manually in PhpStorm and allow PhpStorm to do its magic right out of the box.

By documenting namespaces for test code in the autoload-dev section of composer.json of a project, you make the life of every developer working on that project easier and can be more productive.

Do you have any projects where you have not yet documented namespaces for test code?

Enhancing types in PHP

2022-09-20T13:15:00+02:00

Enhancing types in PHP

Matthias Noback has published an article questioning whether DateTimeImmutable can be considered a primitive type. Matthias concludes that a DateTimeImmutable is not a primitive type.

Primitive type

We can probably agree that the following types

array
bool
float
int
object
string

are all primitive types.

Simple type

We can probably also agree that a DateTimeImmutable is better than a string, a non-empty string, and better than a string that matches a certain regular expression. So if you are dealing with a DateTimeImmutable, you can be sure it holds a valid date.

If you look at all the usages of a DateTimeImmutable in a code base, the only thing the corresponding values have in common is that they are valid dates. But are these values reasonable in a specific context? For example, do they refer to a date in the next quarter or a date of birth?

I am arguing that, at best, a DateTimeImmutable is a sophisticated primitive type, perhaps something we can call a simple type.

Ted M. Young calls these types unconstrained types.

This is why I include all of the Collection classes under the "Primitive Obsession" umbrella. They're "primitives", too, i.e., unconstrained types, that need encapsulation.

In IntelliJ IDEA, it's a few automated steps to refactor to a new class in case you waited too long. https://t.co/yEs7FWKokP
— Ted M. Young (@jitterted) September 2, 2022

Also see the slides for Ted's talk Stop Obsessing About Primitives.

Proper type

In my opinion, a proper type describes an object

that carries meaning (it's a date of birth)
that enforces constraints for the primitive(s) it encapsulates (it's today or in the past)
that encapsulates operations when necessary, for example, comparison with other instances (it refers to the same day)
that a developer can trace across a code base (all of these instances refer to dates of birth)

A DateTimeImmutable

does not carry meaning beyond referring to a date
can not enforce whether the encapsulated value is in the future or the past
does not encapsulate necessary operations, for example, comparison with other instances without knowing which components need to be considered
can not be reliably traced across a code base

Without context, a DateTimeImmutable object does not satisfy the requirements of a proper type.

From primitive to proper type

Replacing primitive types with simple types certainly enhances legacy code bases. However, it is only a step in the right direction while figuring out requirements.

For example, assume a legacy code base has a User.

<?php

declare(strict_types=1);

class User
{
    private string $dateOfBirth;

    // ...

    public function __construct(string $dateOfBirth)
    {
        $this->dateOfBirth = $dateOfBirth;
    }

    public function dateOfBirth(): string
    {
        return $this->dateOfBirth;
    }

    // ...
}

As a first step, we can replace the primitive string with a DateTimeImmutable.

<?php

declare(strict_types=1);

class User
{
    private \DateTimeImmutable $dateOfBirth;

    // ...

    public function __construct(DateTimeImmutable $dateOfBirth)
    {
        $this->dateOfBirth = $dateOfBirth;
    }

    public function dateOfBirth(): DateTimeImmutable
    {
        return $this->dateOfBirth;
    }

    // ...
}

As a second step, we can introduce a simple DateOfBirth type to replace the simple DateTimeImmutable.

<?php

declare(strict_types=1);

final class DateOfBirth
{
    private DateTimeImmutable $value;

    private function __construct(DateTimeImmutable $value)
    {
        $this->value = $value;
    }

    public static function fromDateTimeImmutable(DateTimeImmutable $value): self
    {
        return new self($value);
    }

    public function toString(): string
    {
        return $this->value;
    }
}

The simple DateOfBirth type

carries meaning (it's a date of birth)
encapsulates necessary operations, for example, comparison with other instances (it refers to the same day)
can be traced by a developer across a code base (all of these instances refer to dates of birth)

The simple DateOfBirth type does not yet enforce constraints for the simple type it encapsulates.

However, the User class and corresponding call sites can now already start using the DateOfBirth type.

<?php

declare(strict_types=1);

class User
{
    private DateOfBirth $dateOfBirth;

    // ...

    public function __construct(DateOfBirth $dateOfBirth)
    {
        $this->dateOfBirth = $dateOfBirth;
    }

    public function name(): DateOfBirth
    {
        return $this->dateOfBirth;
    }

    // ...
}

As a third step, when requirements are clear, we can turn the simple DateOfBirth into a proper type that also enforces constraints for the simple DateTimeImmutable it encapsulates.

<?php

declare(strict_types=1);

final class DateOfBirth
{
    // ...

    /**
     * @throws InvalidDateOfBirth
     */
    public static function fromDateTimeImmutable(
        DateTimeImmutable $value,
        DateTimeImmutable $threshold
    ): self {
        if ($threshold->format('Y-m-d') < $value->format('Y-m-d')) {
            throw InvalidDateOfBirth::with($value);
        }

        return new self($value);
    }

    // ...
}

The proper DateOfBirth type now

carries meaning (it's a date of birth)
enforces constraints for the primitive(s) it encapsulates (it's today or in the past)
encapsulates comparison (it refers to the same day)
can be traced by a developer across a code base (all of these instances refer to dates of birth)

What do you think? Are you better off with primitive, simple, or proper types?

Asserting the output of Symfony console commands

2022-08-29T22:30:00+02:00

Asserting the output of Symfony console commands

If you write console commands using symfony/console and have not used SymfonyStyleyet, you should give it a try.

SymfonyStyle provides additional methods for rendering output in the terminal. These methods allow rendering titles, section headings, success and error messages, tables, bullet lists, and more - all of them nicely formatted and indented.

Here is an example from ergebnis/day-one-to-obsidian-converter:

<?php

declare(strict_types=1);

namespace Ergebnis\DayOneToObsidianConverter\Outside\Adapter\Primary\Console;

use Ergebnis\DayOneToObsidianConverter\Inside;
use Symfony\Component\Console;

final class ConvertCommand extends Console\Command\Command
{
    protected function execute(
        Console\Input\InputInterface $input,
        Console\Output\OutputInterface $output,
    ): int {
        $io = new Console\Style\SymfonyStyle(
            $input,
            $output,
        );

        // ...

        $dayOneDirectory = $input->getArgument('day-one-directory');

        if (!\is_dir($dayOneDirectory)) {
            $io->error(\sprintf(
                'DayOne directory %s does not exist',
                $dayOneDirectory,
            ));

            return self::FAILURE;
        }

        // ...

        return self::SUCCESS;
    }
}

While the error message looks great, when you write tests and want to make assertions about the output generated by the command, you quickly run into issues.

If the length of an error or success message depends on variable input, you can never be sure whether a message can fit into a single or will spread across multiple lines.

<?php

namespace Ergebnis\DayOneToObsidianConverter\Test\Integration\Outside\Adapter\Primary\Console;

use Ergebnis\DayOneToObsidianConverter\Outside;
use Ergebnis\DayOneToObsidianConverter\Test;
use PHPUnit\Framework;
use Symfony\Component\Console;

final class ConvertCommandTest extends Framework\TestCase
{
    use Test\Util\Helper;

    public function testExecuteFailsWhenDayOneDirectoryDoesNotExist(): void
    {
        // ...

        $application = self::createApplication();

        $input = new Console\Input\ArrayInput([
            'day-one-directory' => $dayOneDirectory,
        ]);

        $output = new Console\Output\BufferedOutput();

        $exitCode = $application->run(
            $input,
            $output,
        );

        self::assertSame(Console\Command\Command::FAILURE, $exitCode);

        $expected = \sprintf(
            'DayOne directory %s does not exist',
            $dayOneDirectory,
        );

        self::assertStringContainsString($expected, $output->fetch());
    }

    // ...
}

Unfortunately, the test above fails because the actual error message is wrapped across multiple lines.

While Symfony allows specifying the terminal width via a COLUMNS environment variable, SymfonyStyle does not accept values greater than 120 characters. Setting the COLUMNS environment variable to a value larger than 120 in the context of tests will not work.

You could try working around the formatting and indenting by fiddling with regular expressions, but why bother?

Instead, let SymfonyStyle generate the expected output!

<?php

declare(strict_types=1);

namespace Ergebnis\DayOneToObsidianConverter\Test\Util;

use Faker\Factory;
use Faker\Generator;
use Symfony\Component\Console;

trait Helper
{
    // ...

    /**
     * @param \Closure(OutputStyle):void $closure
     */
    final protected static function captureConsoleOutput(\Closure $closure): string
    {
        $output = new Console\Output\BufferedOutput();

        $io = new Console\Style\SymfonyStyle(
            new Console\Input\ArrayInput([]),
            $output,
        );

        $closure($io);

        return $output->fetch();
    }

    // ...
}

Now you can simplify your tests by asserting that the actual output contains the expected output.


         self::assertSame(Console\Command\Command::FAILURE, $exitCode);

-        $expected = \sprintf(
-            'DayOne directory %s does not exist',
-            $dayOneDirectory,
-        );
+        $expected = self::captureConsoleOutput(static function (Console\Style\OutputStyle $io) use ($dayOneDirectory): void {
+            $io->error(\sprintf(
+                'DayOne directory %s does not exist',
+                $dayOneDirectory,
+            ));
+        });

         self::assertStringContainsString($expected, $output->fetch());
     }

     // ...
 }

Do you have a better idea?

Naming constructors in PHP

2022-03-26T19:00:00+02:00

Naming constructors in PHP

The chances are that you are already aware of the concept of named constructors. If not, take a look at Matthias Verraes' excellent article Named Constructors in PHP.

When it comes to consistently naming constructors, I currently apply the following rules for different types of objects.

services
exceptions
entities
value objects

Services

When a service requires dependencies, use the default __construct() method for instantiation.

<?php

declare(strict_types=1);

namespace Example;

final class AccountService
{
    public function __construct(
        private readonly AccountEventStore $accountEventStore,
        private readonly AccountEventDispatcher $accountEventDispatcher,
    ) {
    }

    // ...
}

Why? Typically, a service has a single way of construction. Consequently, it only needs a single constructor.

During yesterday's Office Hours of The PHP Consulting Company, Stefan Priebsch shared that he experimented with named constructors for services. Stefan marks the __construct() method as private and uses a named constructor collaboratingWith() instead, which sounds like an idea that I might give a try.

<?php

declare(strict_types=1);

namespace Example;

final class AccountService
{
    private function __construct(
        private readonly AccountEventStore $accountEventStore,
        private readonly AccountEventDispatcher $accountEventDispatcher,
    ) {
    }

    public static function collaboratingWith(
        AccountEventStore $accountEventStore,
        AccountEventDispatcher $accountEventDispatcher,
    ): self {
        return new self(
            $accountEventStore,
            $accountEventDispatcher,
        );
    }

    // ...
}

Stefan also pointed out that marking the __construct() method as private and using a named constructor instead has the advantage that developers cannot invoke the __construct() method on an already instantiated object, which is technically possible. Stefan notes that an RFC proposing to disallow multiple constructor calls has become inactive. Hence, marking the __construct() method as private and using a named constructor takes away one more possibility for a PHP developer to shoot themselves in the foot.

Following our conversation, Stefan has published How do you name constructors?, where he provides additional examples, explanations, and reasoning.

Exceptions

When implementing a custom exception, allow instantiation via a named constructor that suits the purpose, never override the default constructor.

<?php

declare(strict_types=1);

namespace Example;

use Doctrine\ORM;

final class CouldNotFindUser extends \RuntimeException
{
    public static function identifiedBy(UserId $userId): self
    {
        return new self(\sprintf(
            'Could not find a user identified by "%s".',
            $userId->toString(),
        ));
    }

    public static function withEmailAddress(EmailAddress $emailAddress): self
    {
        return new self(\sprintf(
            'Could not find a user with email-address "%s".',
            $emailAddress->toString(),
        ));
    }
}

Why? Depending on the scenario, you may want to throw an exception of the same type, but based on different inputs. Named constructors allow doing just that. When you override the default constructor, it will be harder for cases where you are not ready to extract a named constructor yet or want to pass in an exception code, a previous exception, or both during the construction of the exception.

Entities

When an ORM entity requires other entities or values, use the default __construct() method for instantiation.

In a typical project using the Doctrine ORM an entity also has only a single way of construction. I have chosen to use the default __construct() method for this kind of entity.

<?php

declare(strict_types=1);

namespace Example;

use Doctrine\ORM;

#[ORM\Mapping\Entity]
#[ORM\Mapping\Table(name="user_reset_password_token")]
class UserResetPasswordToken
{
    #[ORM\Mapping\Column(
        length: 255,
        name: 'token',
        nullable: false,
        type: 'example_token',
        unique: true,
    )]
    #[ORM\Mapping\Id]
    private Token $token;

    #[ORM\Mapping\JoinColumn(
        name: 'user_id',
        nullable: false,
        onDelete: 'CASCADE',
        referencedColumnName: 'id',
        unique: true,
    )]
    private User $user;

    #[ORM\Mapping\Column(
        name: 'expires_at',
        nullable: false,
        type: 'datetime_immutable',
    )]
    private \DateTimeImmutable $expiresAt;

    public function __construct(
        private Token $token,
        private User $user,
        private \DateTimeImmutable $expiresAt,
    ) {
    }

    // ...
}

Although I am currently still working on projects using the Doctrine ORM, I have become more interested in working on projects using message-driven architectures.

For an event-sourced entity, mark the default __construct() method as private, add a named constructor create() that initiates the lifecycle of the entity, and add a named constructor fromEvents() that allows reconstituting the entity from a list of events.

<?php

declare(strict_types=1);

namespace Example;

final class Order
{
    /**
     * @var array<int, OrderEvent>
     */
    private array $events = [];

    private function __construct(OrderEvent ...$events)
    {
        foreach ($events as $event) {
            $this->apply($event);
        }
    }

    public static function create(
        OrderId $orderId,
        OrderStartedAt $orderStartedAt,
    ): self {
        $order = new self();

        $order->record(OrderStarted::create(
            $orderId,
            $orderStartedAt,
        ));

        return $orderId;
    }

    public static function fromEvents(OrderEvent ...$orderEvents): self
    {
        return new self(...$orderEvents);
    }

    // ...
}

Value Objects

I distinguish ~~two~~ three types of value objects:

value objects wrapping a primitive value
value objects composing primitive values
value objects composing other value objects

Value Objects wrapping a primitive value

When a value object wraps a single primitive value, such as

a bool
a float
an int
a string

or an immutable object from the Standard PHP Library (SPL) , for example,

an instance of DateTimeImmutable

mark the default __construct() method as private and add named constructors with corresponding counterparts for accessing the wrapped value (or a representation of it).

For example, to allow instantiation of a Name value object from a string value, I add a constructor with the name fromString() and a corresponding method toString() that provides access to the wrapped string value.

<?php

declare(strict_types=1);

namespace Example;

final class Name
{
    private function __construct(private readonly string $value)
    {
    }

    /**
     * @throws \InvalidArgumentException
     */
    public static function fromString(string $value): self
    {
        if ('' === \trim($value)) {
            throw new \InvalidArgumentException('Value can not be blank or empty.');
        }

        return new self($value);
    }

    public function toString(): string
    {
        return $this->value;
    }
}

As another example, to allow instantiation of a DateOfBirth value object from an instance of DateTimeImmutable, I add a named constructor fromDateTimeImmutable() and a corresponding accessor toDateTimeImmutable() that provides access to the wrapped DateTimeImmutable instance.

<?php

declare(strict_types=1);

namespace Example;

final class DateOfBirth
{
    private function __construct(private readonly \DateTimeImmutable $value)
    {
    }

    public static function fromDateTimeImmutable(\DateTimeImmutable $value): self
    {
        return new self(\DateTimeImmutable::createFromFormat(
            '!Y-m-d',
            $value->format('Y-m-d'),
        ));
    }

    public function toDateTimeImmutable(): \DateTimeImmutable
    {
        return $this->value;
    }
}

Why bother with a toDateTimeImmutable() method when the field is already readonly and not make the field public instead?

From the perspective of a user, the internal value does not matter. The only thing that matters to a user is that they can create the value object from some primitive value and obtain a primitive representation of the value object when necessary. In the example above, the DateOfBirth value object could use a string as internal representation, three ints, or three strings. If I exposed the internal representation directly by making the field public, I would need to change every place that references the field(s). By encapsulating the primitive entirely, I am still open to changing the internal representation without making these changes anywhere else.

When it later turns out that I want to construct a DateOfBirth from a string value, I can easily add a constructor with the name fromString(), and if need be, a corresponding accessor toString() that returns an appropriate string representation.

<?php

declare(strict_types=1);

namespace Example;

final class DateOfBirth
{
    private function __construct(private readonly \DateTimeImmutable $value)
    {
    }

    // ...

    /**
     * @throws \InvalidArgumentException
     */
    public static function fromString(string $value)
    {
        try {
            $parsed = \DateTimeImmutable::createFromFormat(
                '!Y-m-d',
                $value,
            );
        } catch (\Exception) {
            throw new \InvalidArgumentException(\sprintf(
                'Value "%s" does not appear to be a valid date of birth.',
                $value,
            ));
        }

        // ...

        return new self($parsed);
    }

    public function toString(): string
    {
        return $this->value->format('Y-m-d');
    }
}

Value objects composing primitive values

I am still on the fence about whether a value object that composes more than one primitive value is a good idea. Generally, I prefer value objects to wrap a single primitive value or compose other value objects.

Why? For me, value objects serve two purposes:

traceability
enforcing invariants
expressive operations

For example, a legacy codebase might use an int or a string for representing the concept of an International Bank Account Number (IBAN). When I slowly replace usages of the int or string value with an Iban type, the concept becomes traceable throughout the codebase. Before the change, the only indication I was dealing with an IBAN was the variable name, perhaps even with a different spelling. I now have a concrete type and can easily find usages with an IDE or static code analysis. In other words, at this time, without enforcing invariants or providing expressive operations, introducing a value object already has the great benefit of traceability.

Step by step, I could enforce invariants using guard clauses and add methods that allow expressive operations.

If I composed multiple primitives into a value object and cared about these primitives, then I would not benefit from traceability and expressive operations anymore.

For example, I could compose two DateTimeImmutables into a Duration value object to model the duration of a specific event.

<?php

declare(strict_types=1);

namespace Example;

final class Duration
{
    private function __construct(
        public readonly \DateTimeImmutable $start,
        public readonly \DateTimeImmutable $end,
    ) {
    }

    /**
     * @throws \InvalidArgumentException
     */
    public static function create(
        \DateTimeImmutable $start,
        \DateTimeImmutable $end,
    ): self {
        // ...

        return new self(
            $start,
            $end,
        );
    }
}

Given proper enforcement of invariants (an event can not end before it starts), the Duration object works fine, and the concept of a Duration is now clearly more traceable than passing around two DateTimeImmutables. However, if I care about the concept of a Start and End, and when I want to distinguish between a Start, an End, and an ordinary instance of DateTimeImmutable, and want to provide expressive operations for these values, it will make more sense to introduce additional value objects.

<?php

declare(strict_types=1);

namespace Example;

final class Duration
{
    private function __construct(
        public readonly Start $start,
        public readonly End $end,
    ) {
    }

    /**
     * @throws \InvalidArgumentException
     */
    public static function create(
        Start $start,
        End $end,
    ): self {
        if (!$start->isBefore($end)) {
            // ...
        }

        return new self(
            $start,
            $end,
        );
    }
}

Value objects composing other value objects

When a value object composes other value objects, mark the default __construct() method as private and add a named constructor create().

I have found that this kind of value object only has a single way of construction. However, instead of using the default __construct() method, I prefer to use a named constructor create() for this kind of value object.

<?php

declare(strict_types=1);

namespace Example;

final class Attendee
{
    private function __construct(
        public readonly Name $name,
        public readonly DateOfBirth $dateOfBirth,
    ) {
    {
    }

    public static function create(
        Name $name,
        DateOfBirth $dateOfBirth,
    ): self {
        return new self(
            $name,
            $dateOfBirth,
        );
    }
}

Why create() and not fromNameAndDateOfBirth()? When I name the method fromNameAndDateOfBirth(), and later decide to compose additional value objects, it would be consistent to reflect the change by changing the method name. However, the method name would become longer and longer, and I would like to avoid that.

Consistency

Using named constructors for value objects, even when these value objects have only a single way of construction, provides a consistent naming scheme. Consistency is key to making it easier for developers to join, understand, and contribute to a project.

Creating releases with GitHub Actions

2022-01-24T12:15:00+02:00

Creating releases with GitHub Actions

In October 2021, GitHub introduced a feature that enables maintainers to generate release notes for a release with the click of a button.

By default, the automatically generated release notes contain

a list of pull requests maintainers have merged since the last release
a list of first-time contributors to that release
a link to the diff, comparing the changes between this and the previous release

Additionally, you can configure filters and groups to fine-tune the content of these release notes, depending on the authors and labels attached to the pull requests.

While these automatically generated release notes may not be perfect, they can be a good companion for a curated, hand-crafted CHANGELOG.md as proposed by the keepachangelog form.

But - why bother clicking buttons when you could automatically create a release with release notes any time you push a tag to GitHub? In addition to the user interface, GitHub allows maintainers to create a release via their API. In combination with actions/github-script, you can quickly implement a GitHub Actions workflow that will create a release with generated release notes every time you push a tag!

Release workflow

Here is an example of a release workflow, placed in .github/workflows/release.yaml in the root of your repository:

# https://docs.github.com/en/actions

name: "Release"

on: # yamllint disable-line rule:truthy
  push:
    tags:
      - "**"

jobs:
  release:
    name: "Release"

    runs-on: "ubuntu-latest"

    steps:
      - name: "Determine tag"
        run: "echo \"RELEASE_TAG=${GITHUB_REF#refs/tags/}\" >> $GITHUB_ENV"

      - name: "Create release"
        uses: "actions/github-script@v6"
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
          script: |
            try {
              const response = await github.rest.repos.createRelease({
                draft: false,
                generate_release_notes: true,
                name: process.env.RELEASE_TAG,
                owner: context.repo.owner,
                prerelease: false,
                repo: context.repo.repo,
                tag_name: process.env.RELEASE_TAG,
              });

              core.exportVariable('RELEASE_ID', response.data.id);
              core.exportVariable('RELEASE_UPLOAD_URL', response.data.upload_url);
            } catch (error) {
              core.setFailed(error.message);
            }

With a release workflow in place, run

git tag -s x.y.z

followed by

git push --tags

to create a release with automatically generated release notes from the terminal.

Composite action

Since I have started to use this workflow in all of my open-source repositories on GitHub, I have extracted this workflow into a composite action in ergebnis/.github for easier reuse.

Here is what the composite action looks like:

# https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs
# https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions
# https://docs.github.com/en/rest/reference/releases#create-a-release
# https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push

name: "Create a release"

description: "Creates a release"

inputs:
  github-token:
    description: "GitHub token of a user with permission to create a release"
    required: true

runs:
  using: "composite"

  steps:
    - name: "Determine tag"
      if: "${{ github.event_name }} == 'push' && ${{ github.ref_type }} == 'tag'"
      run: "echo \"RELEASE_TAG=${GITHUB_REF#refs/tags/}\" >> $GITHUB_ENV"
      shell: "bash"

    - name: "Create release"
      uses: "actions/github-script@v6.3.3"
      with:
        github-token: "${{ inputs.github-token }}"
        script: |
          if (!process.env.RELEASE_TAG) {
            core.setFailed("The environment variable RELEASE_TAG is not defined.")

            return;
          }

          try {
            const response = await github.rest.repos.createRelease({
              draft: false,
              generate_release_notes: true,
              name: process.env.RELEASE_TAG,
              owner: context.repo.owner,
              prerelease: false,
              repo: context.repo.repo,
              tag_name: process.env.RELEASE_TAG,
            });

            core.exportVariable('RELEASE_ID', response.data.id);
            core.exportVariable('RELEASE_UPLOAD_URL', response.data.upload_url);
          } catch (error) {
            core.setFailed(error.message);
          }

Release workflow using composite action

Thanks to the composite action above, a workflow for creating a release on GitHub with automatically generated release notes is as simple as this:

# https://docs.github.com/en/actions

name: "Release"

on: # yamllint disable-line rule:truthy
  push:
    tags:
      - "**"

jobs:
  release:
    name: "Release"

    runs-on: "ubuntu-latest"

    steps:
      - name: "Create release"
        uses: "ergebnis/.github/actions/github/release/create@1.8.0"
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"

You can see an example of a release with release notes created by this workflow in ergebnis/data-provider:1.3.0.

Wrapping it up

2021-12-31T19:30:00+02:00

Wrapping it up

Writing is a social activity: although often performed in solitude, all writers write to be read by an audience. If you have difficulties finding readers, you have failed - whether you write for print or web, fiction or non-fiction, or computer programs.

Line Length

Typographers of print and web agree that the hard limit for line length should be somewhere between 50 and 75 characters (including spaces). When lines are too short, readers will be too busy traveling back and forth between the beginning and end of the line. When lines are too long, readers will have difficulties finding the following line.

Computer programmers usually have a different understanding.

In 1920, IBM introduced rectangular punched cards with 80 columns per line. Little did they know that these 80 columns would determine the width of computer terminals for years to come.

Punched cards (Ziffernkarten) from IBM Deutschland, with 80 columns each. Feel like you need a punched card? Send me an email with your mailing address and I will send you a punched card by snail mail.

In 2012, the PHP Framework Interop Group (PHP-FIG) accepted PSR-2, which recommended the following:

There MUST NOT be a hard limit on line length.

The soft limit on line length MUST be 120 characters; automated style checkers MUST warn but MUST NOT error at the soft limit.

Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD be split into multiple subsequent lines of no more than 80 characters each.

There MUST NOT be trailing whitespace at the end of non-blank lines.

Blank lines MAY be added to improve readability and to indicate related blocks of code.

There MUST NOT be more than one statement per line.

PHP Framework Interop Group (PHP-FIG)

In 2019, the PHP Framework Interop Group accepted PSR-12 as a replacement for PSR-2, which still recommends the same.

The popular development platform GitHub allows

139 characters per line in the compare branches view before starting to wrap lines
150 characters per line in the pull request view before starting horizontal scrolling
154 characters per line in the file view before starting to wrap lines

But hey, these are only recommendations and external constraints, and you can buy ultra-wide monitors for very little money!

An example of an ultra-wide monitor. I have never had one, and if I did, I am not sure I would be comfortable using its entire width for code. Instead, I am a big fan of splitting editor windows.

So why bother with line lengths?

Maintenance

While the compiler, the most frequent reader of the code, typically does not care whether a computer program is written in a single line or not, maintainers of the computer program will.

Like skimming an article, I tend to recognize patterns when reading code. If you have ever played Minesweeper for long enough, you know the feeling: you do not have to think hard where mines hide but recognize patterns on the board and flag them.

In my experience, complexity in code - the equivalent of mines in Minesweeper - tends to hide in long lines. So why not make it easier for maintainers and expose that complexity by unwrapping it into multiple lines?

Candidates

There are several candidates where authors of computer programs typically exceed line lengths:

annotations
attributes
array initializations
conditions
constructor declarations
constructor invocations
function declarations
function invocations
method declarations
method invocations

Annotations

Annotations allow developers to configure meta-data for classes, methods, fields, and functions. However, they are not a native feature of PHP and require an annotation parser, such as the widely used doctrine/annotations package, to read the meta-data from the DocBlocks.

For example, when using the popular doctrine/orm package, a developer can add annotations to a class to declare it as an entity.

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM;

/**
 * @ORM\Mapping\Entity(repositoryClass="App\Repository\UserRepository")
 */
class User
{
    // ...
}

The annotation Doctrine\ORM\Mapping\Entity refers to a class with the same name. The class declares properties, and by adding the annotation here, the annotation reader creates an instance of that class where the $repositoryClass property has the value 'App\Repository\UserRepository'.

Apart from doctrine/orm, there are a lot of popular packages out there that allow developers to add annotations, and a lot of these annotations can have a lot of properties. So when developers add more and more annotations with more and more properties, these annotations can become hard to read, understand, and maintain.

When an annotation has more than one property, wrap properties so that every property is on a new line.

 <?php

 declare(strict_types=1);

 namespace App\Entity;

 use Doctrine\ORM;

 /**
  * @ORM\Mapping\Entity(repositoryClass="App\Repository\UserRepository")
- * @ORM\Mapping\Table(name="user", indexes={@ORM\Mapping\Index(name="email_idx", columns={"email"})})
+ * @ORM\Mapping\Table(
+ *     name="user",
+ *     indexes={
+ *         @ORM\Mapping\Index(
+ *             name="email_idx",
+ *             columns={
+ *                 "email",
+ *             },
+ *         ),
+ *     },
+ * )
  */
  class User
  {
      // ...

      /**
-      * @ORM\Mapping\Column(name="email", type="string")
+      * @ORM\Mapping\Column(
+      *     name="email",
+      *     type="string",
+      * )
       */
      private string $email;

      // ...
  }

Applying the rule has the following advantages:

You can immediately see the complexity of the annotations - no horizontal scrolling required.
When adding a new property to an existing annotation, it will be more obvious where to add it.
When adding a new value to an existing annotation, it will be more obvious where to add it.

💡 You might find it easier to wrap and indent annotations when enabling the doctrine_annotation_indentation fixer for friendsofphp/php-cs-fixer.

💡 You can quickly sort properties by name, for example, by using the Lines Sorter plugin for PhpStorm.

💡 You can quickly move the line under the cursor (or a block of selected lines) up or down by pressing Option + Shift + ↑ or Option + Shift + ↓ on macOS. Also see Move Line in the IntelliJ IDEA Guide.

Attributes

Like annotations, attributes allow configuring meta-data on classes, properties, functions, methods, parameters, and constants. They are a native feature of PHP since their introduction with PHP 8.0.

When an attribute has more than one property, wrap properties so that every property is on a new line.

<?php

 declare(strict_types=1);

 namespace App\Http;

 use Symfony\Component\HttpFoundation;
 use Symfony\Component\Routing;

 final class HealthAction
 {
-    #[Routing\Annotation\Route(path: '/health/', name: 'health', methods: [HttpFoundation\Request::METHOD_GET])]
+    #[Routing\Annotation\Route(
+        path: '/health/',
+        name: 'health',
+        methods: [
+            HttpFoundation\Request::METHOD_GET,
+        ],
+    )]
     public function __invoke(): HttpFoundation\JsonResponse
     {
         // ...
     }

Applying the rule has the following advantages:

You can immediately see the complexity of the attributes - no horizontal scrolling required.
When adding a new property to an existing attribute, it will be more obvious where to add it.
When adding a new value to an existing attribute, it will be more obvious where to add it.

💡 You can quickly sort properties by name, for example, by using the Lines Sorter plugin for PhpStorm.

Array Initializations

When initializing a non-empty array, wrap elements so that each element is on a new line.

<?php

 declare(strict_types=1);

 $foo = [];

-$bar = ['baz'];
+$bar = [
+    'baz',
+];

-$baz = ['qux' => ['quux', 'quuz'], 'corge' => 'grault'];
+$baz = [
+    'qux' => [
+        'quux',
+        'quuz',
+    ],
+    'corge' => 'grault',
+];

Applying the rule has the following advantages:

You can immediately see the structure of the array - no horizontal scrolling required.
When an array is a list, and the order does not matter, you can easily sort elements by value.
When an array is a map, and the order does not matter, you can easily sort elements by key.
When adding a new element to a list or a map, it will be more obvious where to add it.

💡 You can quickly sort elements of a map by name and elements of a list by value, for example, by using the Lines Sorter plugin for PhpStorm.

Conditions

When a condition has more than one predicate, wrap predicates so that each predicate is on a new line.

 <?php

 declare(strict_types=1);

-if (($booking->getStatus() === Booking::STATUS_FIXED
-        || ($booking->getStatus() === Booking::STATUS_PROMISED && ($booking->getPromisedUntil() > $now || ($buildingIndex && $booking->getSynchronizeExpired()))))
-    && $allocation->getCapabilityBegin() < $allocation->getCapabilityEnd()) {
+if (
+    (
+        $booking->getStatus() === Booking::STATUS_FIXED
+        || (
+            $booking->getStatus() === Booking::STATUS_PROMISED
+            && (
+                $booking->getPromisedUntil() > $now
+                || (
+                    $buildingIndex
+                    && $booking->getSynchronizeExpired()
+                )
+            )
+        )
+    )
+    && $allocation->getCapabilityBegin() < $allocation->getCapabilityEnd()
+) {
     // ...
 }

Applying the rule has the following advantages:

You can immediately see the complexity of the condition - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all predicates were on the same line.
Are there too many predicates? Why?
Are the predicates using || and && combined correctly? Why not?
Should all cases be handled the same? Why?
Are there automated tests that assert that correct behaviour for all cases? Why not?
Can we reduce the cognitive load by breaking, continueing, or returning early? Why not?

Constructor Declarations

When a constructor declares more than one parameter, wrap parameters so that each parameter is on a new line.

<?php

 declare(strict_types=1);

 class Request
 {
     // ...

-    public function __construct(array $query = [], array $request = [], array $attributes = [], array $cookies = [], array $files = [], array $server = [], $content = null)
+    public function __construct(
+        array $query = [],
+        array $request = [],
+        array $attributes = [],
+        array $cookies = [],
+        array $files = [],
+        array $server = [],
+        $content = null,
     ) {
         // ...
     }
 }

Applying the rule has the following advantages:

You can immediately see the number of constructor parameters along with their visibilities, readonly modifiers, and default values - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all parameters were on the same line.
Does the constructor have too many parameters? Perhaps the class is doing too much?
When using constructor property promotion on PHP 8.0, do all parameters have visibilities? Why not?
When using readonly properties on PHP 8.1, do all parameters have readonly modifiers? Why not?
Do all parameters have type declarations? Why not?
Does the constructor have parameters with default values? Why?
Does the constructor have unused parameters? Why?
Do you keep seeing the same parameters used together again and again? Perhaps they belong together in a service or a value object?

Constructor Invocations

When a constructor invocation uses more than one argument, wrap arguments so that each argument is on a new line.

 <?php

 declare(strict_types=1);

 abstract class AbstractBrowser
 {
     // ...

     public function request(string $method, string $uri, array $parameters = [], array $files = [], array $server = [], string $content = null, bool $changeHistory = true): Crawler
     {
         // ...

-        $this->internalRequest = new Request($uri, $method, $parameters, $files, $this->cookieJar->allValues($uri), $server, $content);
+        $this->internalRequest = new Request(
+            $uri,
+            $method,
+            $parameters,
+            $files,
+            $this->cookieJar->allValues($uri),
+            $server,
+            $content,
+        );

         // ...
     }
 }

Looking at the constructor declaration from the call site, applying the rule has similar advantages:

You can immediately see the number of constructor arguments - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all arguments were on the same line.
Are there too many arguments? Perhaps the object is doing too much?
Are there more arguments than the constructor accepts? Why?
Are there arguments that are identical to the corresponding parameter default value? Why?
Do you keep seeing the same arguments used together again and again? Perhaps they belong together in a service or a value object?

Function Declarations

With exceptions, when a function declares more than one parameter, wrap parameters so that each parameter is on a new line.

 <?php

 declare(strict_types=1);

-function blog_get_headers($courseid = null, $groupid = null, $userid = null, $tagid = null, $tag = null, $modid = null, $entryid=null, $search = null) {
+function blog_get_headers(
+    $courseid = null,
+    $groupid = null,
+    $userid = null,
+    $tagid = null,
+    $tag = null,
+    $modid = null,
+    $entryid = null,
+    $search = null
+) {
     // ...
 }

 // ...

 $filter = static function (string $value): bool {
     return '' !== trim($value);
 };

 // ...

 $reducer = static function (array $carry, array $item): array {
     // ...
 });

 // ...

 $sorter = static function (string $a, string $b): int {
       // ...
 };

Applying the rule has the following advantages:

You can immediately see the number of parameters - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all parameters were on the same line.
Does the function have too many parameters? Perhaps the function is doing too much?
Do all parameters have type declarations? Why not?
Does the function have parameters with default values? Why?
Does the function have unused parameters? Why?
Do you keep seeing the same parameters used together again and again? Perhaps they belong together in a service or a value object?
Does the function have a return type declaration? Why not?
Is the return type declaration nullable? Why?

Function Invocations

With exceptions, when a function invocation uses more than one argument, wrap arguments so that each argument is on a new line.

 <?php

 declare(strict_types=1);

 // userland function, n-ary
-$blogheaders = blog_get_headers($filters['courseid'], $filters['groupid'], $filters['userid'], $filters['tagid'], $filters['tag'], $filters['cmid'], $filters['entryid'], $filters['search']);
+$blogheaders = blog_get_headers(
+    $filters['courseid'],
+    $filters['groupid'],
+    $filters['userid'],
+    $filters['tagid'],
+    $filters['tag'],
+    $filters['cmid'],
+    $filters['entryid'],
+    $filters['search'],
+);

 // native function invocation, binary
 $parts = explode(', ', $list);

 // native function invocation, binary
 $list = implode(', [
     'Gin',
     'Tonic',
     'Lemons',
 ]);

 // native function invocation, binary, using anonymous function with one argument as first argument
 $mapped = array_map(static function (string $value): string {
     // ...
 }, $values);

 // native function invocation, binary, using anonymous function with one argument as second argument
 $filtered = array_filter($values, static function (string $value): bool {
     // ...
 });

 // native function invocation, binary, using anonymous function with two arguments as as second argument
 usort($values, static function (string $a, string $b): int {
     // ...
 });

 // native function invocation, ternary
 $reduced = array_reduce(
     $values,
     static function (array $carry, array $item): array {
         // ...
     },
     []
 );

 // native function invocation, variying arity
 $message = sprintf(
     'Value should be one of "%s", got "%s" instead.',
     implode('", "', $values),
     $value
 );

Looking at the function declaration from the call site, applying the rule has similar advantages:

You can immediately see the number of function arguments - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all arguments were on the same line.
Are there too many arguments? Perhaps the function is doing too much?
Are there more arguments than the function accepts? Why?
Are there arguments that are identical to the corresponding parameter default value? Why?
Do you keep seeing the same arguments used together again and again? Perhaps they belong together in a service or a value object?

Method Declarations

When a method declares more than one parameter, wrap parameters so that each parameter is on a new line.

 <?php

 declare(strict_types=1);

 final class JWTCookieProvider
 {
     // ...

-    public function createCookie(string $jwt, ?string $name = null, $expiresAt = null, ?string $sameSite = null, ?string $path = null, ?string $domain = null, ?bool $secure = null, ?bool $httpOnly = null, array $split = []): Cookie
-    {
+    public function createCookie(
+        string $jwt,
+        ?string $name = null,
+        $expiresAt = null,
+        ?string $sameSite = null,
+        ?string $path = null,
+        ?string $domain = null,
+        ?bool $secure = null,
+        ?bool $httpOnly = null,
+        array $split = [],
+    ): Cookie {
         // ...
     }

     // ...
 }

Similar to function declarations, applying this rule has the following advantages:

You can immediately see the number of parameters - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all parameters were on the same line.
Does the method have too many parameters? Perhaps the method is doing too much?
Do all parameters have type declarations? Why not?
Does the method have parameters with default values? Why?
Does the method have unused parameters? Why?
Do you keep seeing the same parameters used together again and again? Perhaps they belong together in a service or a value object?
Does the method have a return type declaration? Why not?
Is the return type declaration nullable? Why?

Method Invocations

With exceptions, when a method invocation uses more than one argument, wrap arguments so that each argument is on a new line.

 <?php

 declare(strict_types=1);

 final class LoginSuccessHandler implements AuthenticationSuccessHandlerInterface
 {
     // ...
     public function handleAuthenticationSuccess(UserInterface $user, ?string $jwt = null): Response
     {
         // ...

-        $jwtCookie = $this->cookieProvider->createCookie($jwt, null, $cookieLifetime, null);
+        $jwtCookie = $this->cookieProvider->createCookie(
+            $jwt,
+            null,
+            $cookieLifetime,
+            null,
+        );

         // ...
     }
 }

 final class ListAction
 {
     // ...

     public function __invoke(): HttpFoundation\Response
     {
         // ...

         $content = $this->twig->render('view/article/list.html.twig', [
             'articlesGroupedByYear' => $articlesGroupedByYear,
         ]);

         // ...
     }

     // ...
}

Looking at the method declaration from the call site, applying the rule has similar advantages:

You can immediately see the number of method arguments - no horizontal scrolling required.
You can more easily identify opportunities for improvement and refactoring - all of which you could have easily missed if all arguments were on the same line.
Are there too many arguments? Perhaps the method is doing too much?
Are there more arguments than the method accepts? Why?
Are there arguments that are identical to the corresponding parameter default value? Why?
Do you keep seeing the same arguments used together again and again? Perhaps they belong together in a service or a value object?

Creating Doctrine entities populated with fake data

2020-07-16T18:30:00+02:00

Creating Doctrine entities populated with fake data

Creating database fixtures in projects using doctrine/orm can be cumbersome - but it doesn't have to be.

When you create and populate entities with fake data by hand, your tests can quickly become bloated and difficult to understand. In need of a cure, you might extract helper methods or classes. The chances are that you use a third-party package for setting up test fixtures.

At the time of writing, doctrine/data-fixtures and nelmio/alice are by far the most-downloaded packages for creating and loading fixtures for Doctrine entities, with 33 million and 11 million total downloads, respectively.

I have used both of them, but there are a few things that bother me.

The primary issue I have with these packages is that there is a considerable disconnect between entities created in a fixture and those used in a test. Developers can establish a connection loosely, using hard-coded values, or indirectly, using constants. I have found tests using these fixtures hard to understand and difficult to maintain.

`breerly/factory-girl-php`

In 2014, a colleague recommended breerly/factory-girl-php, a port of Ruby's factory_bot to PHP, and I have been a big fan since.

The big difference is that instead of creating fixtures, with breerly/factory-girl-php, I can use a fixture factory to create entity definitions. Based on these definitions, I can then use the fixture factory to create entities. Depending on the nature of the entity definitions, the fixture factory will populate the entities with fake data. Entities can have references to other entities, and the fixture factory establishes associations to these automatically. Similar to the other packages, I can create entities for demonstration or testing purposes. However, the connection between the test code and entities is immediate.

I have enjoyed working with breerly/factory-girl-php so much that I started contributing to it. To simplify working with entity definitions, I built ergebnis/factory-girl-definition, a companion that allows loading entity definitions from a directory. In March 2020, I sent an email to Grayson Koonce, the owner of breerly/factory-girl-php. I wondered if he would accept me as a collaborator.

`ergebnis/factory-bot`

Since I never got a reply, I decided to split and started working on ergebnis/factory-bot.

Splitting ergebnis/factory-bot from breerly/factory-girl-php allows me to work on my terms, make my own decisions, and, more importantly, will enable me to move faster.

Since splitting, I have removed code that I never needed and modernized the codebase. I have integrated ergebnis/factory-girl-definition, added features, and foremost, documentation and examples that help you get started.

You can install ergebnis/factory-bot by running

composer require --dev ergebnis/factory-bot

The fixture factory requires an instance of Doctrine\ORM\EntityManagerInterface (for reading class metadata from Doctrine entities, and for persisting Doctrine entities when necessary) and an instance of Faker\Generator for generating fake data.

<?php

declare(strict_types=1);

use Doctrine\ORM;
use Ergebnis\FactoryBot\FixtureFactory;
use Faker\Factory;

$entityManager = ORM\EntityManager::create(...);
$faker = Factory::create(...);

$fixtureFactory = new FixtureFactory(
    $entityManager,
    $faker
);

With the fixture factory set up, you can create definitions for Doctrine entities.

<?php

declare(strict_types=1);

use Ergebnis\FactoryBot\Count;
use Ergebnis\FactoryBot\FieldDefinition;
use Ergebnis\FactoryBot\FixtureFactory;
use Example\Entity;

/** @var FixtureFactory $fixtureFactory */
$fixtureFactory->define(Entity\User::class, [
    'avatar' => FieldDefinition::reference(Entity\Avatar::class),
    'id' => FieldDefinition::closure(static function (Generator $faker): string {
        return $faker->uuid;
    }),
    'location' => FieldDefinition::optionalClosure(static function (Generator $faker): string {
        return $faker->city;
    }),
    'login' => FieldDefinition::closure(static function (Generator $faker): string {
        return $faker->userName;
    }),
]);

$fixtureFactory->define(Entity\Avatar::class, [
    'height' => FieldDefinition::closure(static function (Generator $faker): int {
        return $faker->numberBetween(300, 600);
    }),
    'url' => FieldDefinition::closure(static function (Generator $faker): string {
        return $faker->imageUrl();
    }),
    'width' => FieldDefinition::closure(static function (Generator $faker): int {
        return $faker->numberBetween(400, 900);
    }),
]);

With the fixture factory aware of entity definitions, you can now create entities populated with fake data.

<?php

declare(strict_types=1);

use Ergebnis\FactoryBot\Count;
use Ergebnis\FactoryBot\FieldDefinition;
use Ergebnis\FactoryBot\FixtureFactory;
use Example\Entity;

/** @var FixtureFactory $fixtureFactory */
$user = $fixtureFactory->createOne(Entity\User::class, [
    'login' => FieldDefinition::value('localheinz'),
]);

var_dump($user->location()); // `null` or random city
var_dump($user->login());    // 'localheinz'

$users = $fixtureFactory->createMany(
    Entity\User::class,
    Count::between(0, 10),
    [
        'login' => FieldDefinition::sequence('user-%d'),
    ]
);

var_dump($users); // array with 0-10 instances of Entity\User

I have released ergebnis/factory-bot:0.2.0 yesterday, and you can take a look at the documentation and examples, and try it out today.

Merging pull requests with GitHub Actions

2020-06-15T10:25:00+02:00

Merging pull requests with GitHub Actions

In May 2019, GitHub acquired Dependabot, and recently GitHub announced that Dependabot is moving into GitHub.

When you follow the instructions, you will find that the migration is straightforward. However, there is one thing missing: after migrating from version 1 to version 2, Dependabot will not automatically merge pull requests anymore. That the feature is currently missing could indicate that GitHub will bring automatic merges onboard - independently from Dependabot.

In the meantime, you can configure a workflow with GitHub Actions and actions/github-script that will automatically merge pull requests created by Dependabot. actions/github-script uses octokit/rest.js, which is well documented, and it is often more convenient to use than maintaining a full-blown GitHub action.

Here is an example of a workflow that will run when the Integrate workflow has successfully completed for a pull request opened by dependabot[bot] that updates development or production dependencies for composer, or updates GitHub actions.

name: "Merge"

on:
  workflow_run:
    types:
      - "completed"
    workflows:
      - "Integrate"

jobs:
  merge:
    name: "Merge"

    runs-on: "ubuntu-latest"

    if: >
      github.event.workflow_run.event == 'pull_request' &&
      github.event.workflow_run.conclusion == 'success' &&
      github.actor == 'dependabot[bot]' && (
        startsWith(github.event.workflow_run.head_commit.message, 'composer(deps)') ||
        startsWith(github.event.workflow_run.head_commit.message, 'composer(deps-dev)') ||
        startsWith(github.event.workflow_run.head_commit.message, 'github-actions(deps)')
      )

    steps:
      - name: "Request review from @ergebnis-bot"
        uses: "actions/github-script@v5"
        with:
          github-token: "${{ secrets.ERGEBNIS_BOT_TOKEN }}"
          script: |
            const pullRequest = context.payload.workflow_run.pull_requests[0]
            const repository = context.repo

            const reviewers = [
              "ergebnis-bot",
            ]

            await github.rest.pulls.requestReviewers({
              owner: repository.owner,
              repo: repository.repo,
              pull_number: pullRequest.number,
              reviewers: reviewers,
            })

      - name: "Assign @ergebnis-bot"
        uses: "actions/github-script@v5"
        with:
          github-token: "${{ secrets.ERGEBNIS_BOT_TOKEN }}"
          script: |
            const pullRequest = context.payload.workflow_run.pull_requests[0]
            const repository = context.repo

            const assignees = [
              "ergebnis-bot",
            ]

            await github.rest.issues.addAssignees({
              owner: repository.owner,
              repo: repository.repo,
              assignees: assignees,
              issue_number: pullRequest.number
            })

      - name: "Approve pull request"
        uses: "actions/github-script@v5"
        with:
          github-token: "${{ secrets.ERGEBNIS_BOT_TOKEN }}"
          script: |
            const pullRequest = context.payload.workflow_run.pull_requests[0]
            const repository = context.repo

            await github.rest.pulls.createReview({
              event: "APPROVE",
              owner: repository.owner,
              repo: repository.repo,
              pull_number: pullRequest.number,
            })

      - name: "Merge pull request"
        uses: "actions/github-script@v5"
        with:
          github-token: "${{ secrets.ERGEBNIS_BOT_TOKEN }}"
          script: |
            const pullRequest = context.payload.workflow_run.pull_requests[0]
            const repository = context.repo

            await github.rest.pulls.merge({
              merge_method: "merge",
              owner: repository.owner,
              pull_number: pullRequest.number,
              repo: repository.repo,
            })

You can see this workflow in action in ergebnis/php-package-template.

Since the workflow references pull request titles, it works best when using it in conjunction with an explicit configuration for Dependabot.

# https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates

version: 2

updates:
  - commit-message:
      include: "scope"
      prefix: "composer"
    directory: "/"
    labels:
      - "dependency"
    open-pull-requests-limit: 10
    package-ecosystem: "composer"
    schedule:
      interval: "daily"
    versioning-strategy: "increase"

  - commit-message:
      include: "scope"
      prefix: "github-actions"
    directory: "/"
    labels:
      - "dependency"
    open-pull-requests-limit: 10
    package-ecosystem: "github-actions"
    schedule:
      interval: "daily"

Rolling up database migrations with Doctrine

2020-06-10T14:10:00+02:00

Rolling up database migrations with Doctrine

Introduction

As a user of doctrine/orm and doctrine/migrations, it is likely that you - like me - have encountered one of the following scenarios:

You have started using doctrine/migrations late in a project. Unfortunately, you can not set up a database from scratch using database migrations.
You use Doctrine entities or other services in the database migrations. You have realized that this was a mistake, regret it, and you would like to get rid of these database migrations.
You populate the database with data using database migrations. Again, you have realized that this was a mistake, regret it, and you would like to get rid of these database migrations.
You have accumulated a lot of database migrations in a mature project. Since you run these database migrations frequently to set up databases in development, test, and staging environments, and because you get that extra kick out of things running fast, you would like to collapse them into a single database migration.

If that does not describe you, for example, because you do not work on these kinds of projects or never make any mistakes, please share this article with someone who does.

Are you still here? Great!

doctrine/migrations:2.0.0 introduced a DumpSchemaCommand and a RollupCommand. The DumpSchemaCommand reads the schema from our entity mapping and dumps corresponding SQL statements into a single database migration. The RollupCommand verifies that only a single database migration exists, removes information about previously run database migrations from the configured table, and inserts information about this single database migration.

Using these commands, we can easily roll up database migrations. In the following, I will show you how.

The process consists of four steps:

validate entity mapping and database
remove existing migrations
dump the schema into a single database migration
validate the dumped database migration
roll up migrations

Commands

In a moment, we will run Doctrine console commands. These commands operate with options that have default values, but if our application has a setup that differs from the defaults, we need to specify values for these options.

Options

--connection: The name of the Doctrine DBAL database connection; could be default.
--env: The name of the environment; could be dev, develop, prod, or production.
--em: The name of the Doctrine ORM entity manager to use; could be default.

Environments

We will run these commands in development and production environments. To achieve the best results, our development environment should reflect the production environment. How to create such a development environment is out of the scope of this article.

❗ Make sure to use the appropriate parameters when executing the commands.

Validate entity mapping and database

As mentioned before, the DumpSchemaCommand reads the schema from our entity mapping and dumps corresponding SQL statements into a single database migration. When our entity mapping and the database are not in sync, this will result in a database migration that does not reflect the actual database structure.

To avoid that, we need to validate the schema and fix all errors in a development environment.

We run

bin/console doctrine:migrations:status

to show the database migration status in our development environment.

When the command reports that there are new database migrations, we run

bin/console doctrine:migrations:execute

to run these database migrations in our development environment.

When all database migrations have been run, we run

bin/console doctrine:schema:validate

to validate that the entity mapping is correct and in sync with the database in our development environment.

When this command reports errors, we need to fix them. Fixing these errors might involve adjusting our entity mapping and creating database migrations. These fixes are useful - even when we do not want to roll up database migrations. Therefore we can apply them to the main line of the project. When we have fixed these errors, we can return to rolling up the database migrations.

When this command does not report any errors, we can continue.

💡 To avoid validation errors, we can validate that the entity mapping is correct and in sync with the database in a continuous-integration environment.

When we cannot set up a database from database migrations, we validate the mapping only. Once we have rolled up the database migrations, we can set up a database from database migrations. Then we can also verify that the entity mapping is in sync with the database.

Remove existing database migrations

Since our entity mapping is valid and in sync with the database, we can now remove the existing database migrations from the configured migrations directory, and commit the changes.

Dump the schema

After removing the existing database migrations, we can now dump the schema from our entity mapping into a single database migration.

We run

bin/console doctrine:migrations:dump-schema

to dump the schema into a single migration in our development environment, and commit the changes.

Validate the dumped migration

We have dumped the schema into a single migration, but before we continue, let us double-check that running this migration really creates a database structure that reflects our entity mapping. We can do that by dropping and recreating the database, running the migration, and validating the schema.

We run

bin/console doctrine:database:drop

to drop the database in our development environment. Then we run

bin/console doctrine:database:create

to create the database in our development environment.

We now have an empty database in our development environment, and we run

bin/console doctrine:migrations:status

to show the database migration status. This command will show a single new database migration: the database migration we just dumped.

We run

bin/console doctrine:migrations:execute

to run this database migration in our development environment.

We now run

bin/console doctrine:schema:validate

to validate that the entity mapping is correct and in sync with the database in our development environment.

At this point, this command should not report any errors. When it does, we need to fix them, but we should not adjust our entity mapping. However, we can modify the dumped database migration. Remember, the RollupCommand will not run when more than one database migration exists.

We run

bin/console doctrine:migrations:diff

to create a database migration from the differences between our entity mapping and the database. Instead of committing the migration created from running this command, we manually merge it into the previously dumped migration and commit the resulting changes.

We repeat this process until the single migration creates a database in sync with our entity mapping.

Roll up

We have rolled up the database migrations in our development environment, and can finally roll up the database migrations in our production environment.

After deploying the changes, we run

bin/console doctrine:migrations:rollup

to roll up the migrations in our production environment.

We run

bin/console doctrine:migrations:status

to verify that there is only a single available migration and that there are more migrations that need to be executed.

Conclusion

We have now collapsed all existing database migrations into a single database migration.

We can set up a database from scratch in development, testing, or continuous-integration environments now, and run commands and tests that require the presence of a database. We have also rid ourselves of database migrations that use entities or services or populate the database with data. By reducing the number of migrations, we have sped up the process of running them.

Avoiding imports and aliases in PHP

2020-05-19T12:00:00+02:00

Avoiding imports and aliases in PHP

PHP 5.3, released on June 30, 2009, introduced namespaces as well as imports and aliases.

Developers quickly adopted these features. Where previously a class was named Foo_Bar_Baz_Qux, namespaces allow calling it Foo\Bar\Baz\Qux.

Imports

With imports, I can import the fully-qualified class name and reference the class by its terminating class name:

<?php

declare(strict_types=1);

use Foo\Bar\Baz\Qux;

$qux = new Qux();

Alternatively, I can import a namespace prefix and reference the class relative to it:

<?php

declare(strict_types=1);

use Foo\Bar;

$qux = new Bar\Baz\Qux();

Aliases

Aliases, you guessed it, allow importing either and assigning aliases to it:

<?php

declare(strict_types=1);

use Foo\Bar as Quux;
use Foo\Bar\Baz\Qux as Quuz;

$qux = new Quux\Baz\Qux();
$anotherQux = new Quuz();

Problems

When it comes to the possibilities of how I can use these features, there are two extremes. At one end, I use fully-qualified class names everywhere. At the other end, I import every single class.

Using fully-qualified class names everywhere is a bit like writing code as if today is June 29, 2009. It does not make any sense - so let us not get into it.

Importing every single class is possible, but potentially leads to a long list of imports. A long list of imports takes a long time to read. For every class I add to this list, developers need to recall the context from which I introduced it. Every time I import a class, I risk conflicts.

Aliases can help to avoid these conflicts. However, aliases only make the problem worse. For every alias, developers need to translate between the original class name and the aliased class name.

With aliases, navigating the code becomes more difficult. In PhpStorm, clicking on a symbol navigates to where it was declared. When I click on a class name referenced in code, I navigate to the class declaration. However, when I click on an alias, I navigate to the alias declaration. I now need to click again on the class name to navigate to its declaration.

Ugh.

Solution

The worst examples of importitis and aliasitis I have seen in a closed-source project included a class with 58 imports, and another class with 12 aliases. If we ignore for a moment that these classes were suffering from other problems, all of these issues could have been avoided by only importing a suitable parent namespace.

Here are few examples.

Take a look at the UserController from the symfony/demo application:

<?php

namespace App\Controller;

use App\Entity\Comment;
use App\Entity\Post;
use App\Events\CommentCreatedEvent;
use App\Form\CommentType;
use App\Repository\PostRepository;
use App\Repository\TagRepository;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\IsGranted;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

It has a fairly long list of imports, that can easily be reduced by importing only parent namespaces:

diff --git a/src/Controller/UserController.php b/src/Controller/UserController.php
index 85228f0..82723de 100644
--- a/src/Controller/UserController.php
+++ b/src/Controller/UserController.php
@@ -2,29 +2,31 @@

 namespace App\Controller;

-use App\Form\Type\ChangePasswordType;
-use App\Form\UserType;
-use Sensio\Bundle\FrameworkExtraBundle\Configuration\IsGranted;
-use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-use Symfony\Component\HttpFoundation\Request;
-use Symfony\Component\HttpFoundation\Response;
-use Symfony\Component\Routing\Annotation\Route;
-use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
+use App\Form;
+use Sensio\Bundle\FrameworkExtraBundle;
+use Symfony\Bundle\FrameworkBundle;
+use Symfony\Component\HttpFoundation;
+use Symfony\Component\Routing;
+use Symfony\Component\Security;

 /**
- * @Route("/profile")
- * @IsGranted("ROLE_USER")
+ * @Routing\Annotation\Route("/profile")
+ * @FrameworkExtraBundle\Configuration\IsGranted("ROLE_USER")
  */
-class UserController extends AbstractController
+class UserController extends FrameworkBundle\Controller\AbstractController
 {
     /**
-     * @Route("/edit", methods="GET|POST", name="user_edit")
+     * @Routing\Annotation\Route(
+     *     "/edit",
+     *     methods="GET|POST",
+     *     name="user_edit"
+     * )
      */
-    public function edit(Request $request): Response
+    public function edit(HttpFoundation\Request $request): HttpFoundation\Response
     {
         $user = $this->getUser();

-        $form = $this->createForm(UserType::class, $user);
+        $form = $this->createForm(Form\UserType::class, $user);
         $form->handleRequest($request);

         if ($form->isSubmitted() && $form->isValid()) {
@@ -42,13 +44,19 @@ class UserController extends AbstractController
     }

     /**
-     * @Route("/change-password", methods="GET|POST", name="user_change_password")
+     * @Routing\Annotation\Route(
+     *     "/change-password",
+     *     methods="GET|POST",
+     *     name="user_change_password"
+     * )
      */
-    public function changePassword(Request $request, UserPasswordEncoderInterface $encoder): Response
-    {
+    public function changePassword(
+        HttpFoundation\Request $request,
+        Security\Core\Encoder\UserPasswordEncoderInterface $encoder
+    ): HttpFoundation\Response {
         $user = $this->getUser();

-        $form = $this->createForm(ChangePasswordType::class);
+        $form = $this->createForm(Form\Type\ChangePasswordType::class);
         $form->handleRequest($request);

         if ($form->isSubmitted() && $form->isValid()) {

We have shortened the list of imports and referenced classes relative to the imported namespace prefixes. We can see immediately the context from which we imported a class. Additionally, we wrapped a few lines. Cognitive load is reduced.

Take a look at the Post entity from the same application:

<?php

namespace App\Entity;

use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
use Symfony\Component\Validator\Constraints as Assert;

The list of imports is not so long, but unnecessary aliases are used, and these can be avoided as well:

diff --git a/src/Entity/Post.php b/src/Entity/Post.php
index a47a862..a2328fd 100644
--- a/src/Entity/Post.php
+++ b/src/Entity/Post.php
@@ -11,16 +11,19 @@

 namespace App\Entity;

-use Doctrine\Common\Collections\ArrayCollection;
-use Doctrine\Common\Collections\Collection;
-use Doctrine\ORM\Mapping as ORM;
-use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
-use Symfony\Component\Validator\Constraints as Assert;
+use Doctrine\Common;
+use Doctrine\ORM;
+use Symfony\Bridge\Doctrine;
+use Symfony\Component\Validator;

 /**
- * @ORM\Entity(repositoryClass="App\Repository\PostRepository")
- * @ORM\Table(name="symfony_demo_post")
- * @UniqueEntity(fields={"slug"}, errorPath="title", message="post.slug_unique")
+ * @ORM\Mapping\Entity(repositoryClass="App\Repository\PostRepository")
+ * @ORM\Mapping\Table(name="symfony_demo_post")
+ * @Doctrine\Validator\Constraints\UniqueEntity(
+ *     fields={"slug"},
+ *     errorPath="title",
+ *     message="post.slug_unique"
+ * )
  */
 class Post
 {
@@ -35,88 +38,97 @@ class Post
     /**
      * @var int
      *
-     * @ORM\Id
-     * @ORM\GeneratedValue
-     * @ORM\Column(type="integer")
+     * @ORM\Mapping\Id
+     * @ORM\Mapping\GeneratedValue
+     * @ORM\Mapping\Column(type="integer")
      */
     private $id;

     /**
      * @var string
      *
-     * @ORM\Column(type="string")
-     * @Assert\NotBlank
+     * @ORM\Mapping\Column(type="string")
+     * @Validator\Constraints\NotBlank
      */
     private $title;

     /**
      * @var string
      *
-     * @ORM\Column(type="string")
+     * @ORM\Mapping\Column(type="string")
      */
     private $slug;

     /**
      * @var string
      *
-     * @ORM\Column(type="string")
-     * @Assert\NotBlank(message="post.blank_summary")
-     * @Assert\Length(max=255)
+     * @ORM\Mapping\Column(type="string")
+     * @Validator\Constraints\NotBlank(message="post.blank_summary")
+     * @Validator\Constraints\Length(max=255)
      */
     private $summary;

     /**
      * @var string
      *
-     * @ORM\Column(type="text")
-     * @Assert\NotBlank(message="post.blank_content")
-     * @Assert\Length(min=10, minMessage="post.too_short_content")
+     * @ORM\Mapping\Column(type="text")
+     * @Validator\Constraints\NotBlank(message="post.blank_content")
+     * @Validator\Constraints\Length(
+     *     min=10,
+     *     minMessage="post.too_short_content"
+     * )
      */
     private $content;

     /**
      * @var \DateTime
      *
-     * @ORM\Column(type="datetime")
+     * @ORM\Mapping\Column(type="datetime")
      */
     private $publishedAt;

     /**
      * @var User
      *
-     * @ORM\ManyToOne(targetEntity="App\Entity\User")
-     * @ORM\JoinColumn(nullable=false)
+     * @ORM\Mapping\ManyToOne(targetEntity="App\Entity\User")
+     * @ORM\Mapping\JoinColumn(nullable=false)
      */
     private $author;

     /**
-     * @var Comment[]|ArrayCollection
+     * @var Comment[]|Common\Collections\ArrayCollection
      *
-     * @ORM\OneToMany(
+     * @ORM\Mapping\OneToMany(
      *      targetEntity="Comment",
      *      mappedBy="post",
      *      orphanRemoval=true,
      *      cascade={"persist"}
      * )
-     * @ORM\OrderBy({"publishedAt": "DESC"})
+     * @ORM\Mapping\OrderBy({"publishedAt": "DESC"})
      */
     private $comments;

     /**
-     * @var Tag[]|ArrayCollection
+     * @var Tag[]|Common\Collections\ArrayCollection
      *
-     * @ORM\ManyToMany(targetEntity="App\Entity\Tag", cascade={"persist"})
-     * @ORM\JoinTable(name="symfony_demo_post_tag")
-     * @ORM\OrderBy({"name": "ASC"})
-     * @Assert\Count(max="4", maxMessage="post.too_many_tags")
+     * @ORM\Mapping\ManyToMany(
+     *     targetEntity="App\Entity\Tag",
+     *     cascade={"persist"}
+     * )
+     * @ORM\Mapping\JoinTable(name="symfony_demo_post_tag")
+     * @ORM\Mapping\OrderBy({"name": "ASC"})
+     * @Validator\Constraints\Count(
+     *     max="4",
+     *     maxMessage="post.too_many_tags"
+     * )
      */
     private $tags;

     public function __construct()
     {
         $this->publishedAt = new \DateTime();
-        $this->comments = new ArrayCollection();
-        $this->tags = new ArrayCollection();
+        $this->comments = new Common\Collections\ArrayCollection();
+        $this->tags = new Common\Collections\ArrayCollection();
     }

     public function getId(): ?int
@@ -174,7 +186,7 @@ class Post
         $this->author = $author;
     }

-    public function getComments(): Collection
+    public function getComments(): Common\Collections\Collection
     {
         return $this->comments;
     }
@@ -216,7 +228,7 @@ class Post
         $this->tags->removeElement($tag);
     }

-    public function getTags(): Collection
+    public function getTags(): Common\Collections\Collection
     {
         return $this->tags;
     }

Again, we have shortened the list of imports and referenced classes relative to the imported namespace prefixes. We can see immediately the context from which we imported a class. We removed unnecessary aliases Additionally, we wrapped a few lines. Cognitive load is reduced again.

Best practices

The changes I propose here do not conform with the examples found in the documentation for Doctrine or Symfony, which might be a problem when you intend to contribute to the core of Doctrine or Symfony or related projects.

When you work on other projects, you are free to do whatever you want.

Decide for yourself. Find out what works best for you.

Quickly switching between PCOV and Xdebug

2020-05-16T12:15:00+02:00

Quickly switching between PCOV and Xdebug

There are at least two PHP extensions I need during the development of a PHP application or package: PCOV and Xdebug.

PCOV is relatively new. Built by by Joe Watkins, it provides fast code coverage for use with phpunit/phpunit.

Xdebug has been around for a while. Built by Derick Rethans, it is a development tool that can not only be used for collecting code coverage, but also provides a single-step debugger for use with IDEs, is equipped with a profiler, upgrades var_dump(), and more. Since it does more things differently, it is slower at collecting code coverage.

Both are great tools and have their place. When I want to collect code coverage with recent versions of phpunit/phpunit, I use PCOV. When I work on a project with older versions of phpunit/phpunit, I use Xdebug to collect code coverage. When I want to debug production code while running tests in PhpStorm, I use Xdebug.

There are drawbacks, however. PCOV does not play well with Xdebug, so I only want one of them to be enabled at a time. Xdebug adds significant overhead when running other tasks in PHP, so I prefer to disable Xdebug when I do not need it.

Before I can enable or disable PCOV and Xdebug, I need to install and configure them. I am going to demonstrate the installation of both on PHP 7.4.

Installation of PCOV

Run

pecl install pcov

and take note of last few lines that are shown when the installation process is finished and the location of pcov.so is revealed (we need it in a moment):

Build process completed successfully
Installing '/usr/local/Cellar/php/7.4.6/pecl/20190902/pcov.so'
install ok: channel://pecl.php.net/pcov-1.0.6
Extension pcov enabled in php.ini

Configuration of PCOV

Run

php --ini

to show the names of configuration files loaded by PHP:

Configuration File (php.ini) Path: /usr/local/etc/php/7.4
Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
Additional .ini files parsed:      /usr/local/etc/php/7.4/conf.d/ext-opcache.ini

Open /usr/local/etc/php/7.4/php.ini and remove

- extension="pcov.so"

Create a file /usr/local/etc/php/7.4/conf.d/ext-pcov.ini, but use the exact location of pcov.so we noted earlier:

extension="/usr/local/Cellar/php/7.4.5_2/pecl/20190902/pcov.so"

Run

php --ini

again and observe that ext-pcov.ini has been loaded:

Configuration File (php.ini) Path: /usr/local/etc/php/7.4
Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
Additional .ini files parsed:      /usr/local/etc/php/7.4/conf.d/ext-opcache.ini,
/usr/local/etc/php/7.4/conf.d/ext-pcov.ini

Installation of Xdebug

Run

pecl install xdebug

and take note of the location of xdebug.so:

Build process completed successfully
Installing '/usr/local/Cellar/php/7.4.6/pecl/20190902/xdebug.so'
install ok: channel://pecl.php.net/xdebug-2.9.5
Extension xdebug enabled in php.ini

Configuration of Xdebug

Run

php --ini

to show the names of configuration files loaded by PHP:

Configuration File (php.ini) Path: /usr/local/etc/php/7.4
Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
Additional .ini files parsed:      /usr/local/etc/php/7.4/conf.d/ext-opcache.ini,
/usr/local/etc/php/7.4/conf.d/ext-pcov.ini

Open /usr/local/etc/php/7.4/php.ini and remove

- zend_extension="xdebug.so"

Create a file /usr/local/etc/php/7.4/conf.d/ext-xdebug.ini, but use the exact location of xdebug.so we noted earlier:

zend_extension="/usr/local/Cellar/php/7.4.6/pecl/20190902/xdebug.so"

Run

php --ini

again and observe that ext-xdebug.ini has been loaded:

Configuration File (php.ini) Path: /usr/local/etc/php/7.4
Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
Additional .ini files parsed:      /usr/local/etc/php/7.4/conf.d/ext-opcache.ini,
/usr/local/etc/php/7.4/conf.d/ext-pcov.ini,
/usr/local/etc/php/7.4/conf.d/ext-xdebug.ini

Disabling and enabling PCOV and Xdebug

Now that we have installed PCOV and Xdebug, we need a way for disabling and enabling them.

The easiest way to disable an extension is to prevent PHP from loading the corresponding configuration file. Since PHP is looking for files ending with a .ini extension, renaming the file seems smart.

In Switching PHP versions when using Homebrew, I collect PHP versions previously installed with Homebrew.

Again, I would like to have a command that works regardless of which version of PHP I currently use. I would also prefer to use a short command, especially when I am going to run them often. To achieve this, I have added the following to my .zhsrc:

# Toggle extension
function toggle()
{
    name=$1
    displayName=${2:-$1}

    for phpVersion in ${installedPhpVersions[*]}; do
        config="/usr/local/etc/php/${phpVersion}/conf.d/ext-${name}.ini"

        if [[ -f "${config}" ]]; then
            mv "${config}" "${config}.bak"
        elif [[ -f "${config}.bak" ]]; then
            mv "${config}.bak" "${config}"
        fi
    done

    php -v

    if [[ $(php -m | grep ${name}) ]]; then
        echo "${displayName} extension has been enabled."
    else
        echo "${displayName} extension has been disabled."
    fi
}

This function expects a single argument, the name of an extension, and optionally a second argument, the display name. The function iterates over all installed PHP versions, and either adds a .bak extension to the name of a matching configuration file, or removes it - effectively disabling or enabling the corresponding extension.

Now I could run

toggle pcov

toggle xdebug

but to be honest, that is still too much work. I have added the following to .zshrc instead:

# Toggle PCOV
function p () {
    toggle pcov PCOV
}

# Toggle Xdebug
function x () {
    toggle xdebug Xdebug
}

Thanks to these small functions, I can run

and

to quickly disable or enable PCOV and Xdebug.

Using Makefiles in projects where I can not use them

2020-05-07T09:45:00+02:00

Using Makefiles in projects where I can not use them

In Makefile for lazy developers, I have shared how I use Makefiles to save time running frequent tasks.

As a maintainer of a project, I can use any tool I like to get the job done, and of course, I use Makefiles in all of these projects.

As a collaborator of a project, I do not have that luxury. I depend on the owners of a project. Some projects already use an alternative, perhaps composer scripts or PHing. Occasionally I have suggested the use of Makefiles. Often the owners have stated that they prefer not to use Makefiles. Rarely the owners already have a Makefile but object to modifications.

I respect that. However, I can still use Makefiles the way I like in every single project, and as a matter of fact, I do.

In Project notes, I have shared how I keep files in a .notes directory within the root directory of a project - without the need to check them into version control. This directory is where I put a Makefile when necessary.

I can now run

make -f .note/Makefile

to run the first target of the Makefile, but I find that this is too much work.

Instead, I have adjusted the alias I previously used from

alias m="make"

alias m="if [[ -f .note/Makefile ]]; then make -f .note/Makefile; else make; fi"

Now I can run

in every single project and still use Makefiles the way I prefer.

Switching PHP versions when using Homebrew

2020-05-05T13:20:00+02:00

Switching PHP versions when using Homebrew

Homebrew is an excellent option for installing one or more PHP versions on your Mac.

But how can you switch PHP versions when you have installed more than one version of PHP with Homebrew?

Which do you prefer - slowly or quickly?

Scenario

You have installed PHP 7.4, 8.0, 8.1, and 8.2 with Homebrew. You have no idea which PHP version is currently linked, but you want to use PHP 8.2.

Slowly switching PHP versions

First, you need to find out which PHP version is currently linked.

Running

php -v

yields

PHP 7.4.33 (cli) (built: Jan 21 2023 06:43:54) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.33, Copyright (c), by Zend Technologies

Second, since you know that PHP 7.4 is currently linked, you need to unlink PHP 7.4.

Running

brew unlink php@7.4

yields

Unlinking /opt/homebrew/Cellar/php@7.4/7.4.33_1... 25 symlinks removed.

Third, you need to link PHP 8.2, the PHP version you want to use.

Running

brew link php@8.2 --force --overwrite

yields

Linking /opt/homebrew/Cellar/php/8.2.1_1... 24 symlinks created.

Fourth, you want to double-check that PHP 8.2 is actually linked now.

Running

php -v

yields

PHP 8.2.1 (cli) (built: Jan 12 2023 03:48:24) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.1, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.1, Copyright (c), by Zend Technologies

Perfect, you can start working with PHP 8.2 after running four (!) commands.

Quickly switching PHP versions

How about running a single command instead of four commands?

How about running

8.2

to switch from any (!) PHP version to PHP 8.2? Let me show you how you can achieve that in two steps.

First, you need to install a modern version of grep with Homebrew.

Running

grep --version

on macOS Ventura yields

grep (BSD grep, GNU compatible) 2.6.0-FreeBSD

Unfortunately, that version does not support Perl-compatible regular expressions (PCREs) that you will use in the next step.

Running

brew install grep

yields

==> Fetching grep
==> Downloading https://ghcr.io/v2/homebrew/core/grep/manifests/3.8_1
Already downloaded: /Users/am/Library/Caches/Homebrew/downloads/a2ee255269e00fca81c021b40c338155577736b42bab878651de2922798bd235--grep-3.8_1.bottle_manifest.json
==> Downloading https://ghcr.io/v2/homebrew/core/grep/blobs/sha256:d2450448352fb2c389634cab3dec581882f6fc0f02a79489b4ba9c603b8f780b
Already downloaded: /Users/am/Library/Caches/Homebrew/downloads/aefda17db919b6aed862b1ae9d2deb2d07197fef50b34f0bcacf179108b8fd12--grep--3.8_1.arm64_ventura.bottle.tar.gz
==> Pouring grep--3.8_1.arm64_ventura.bottle.tar.gz
==> Caveats
All commands have been installed with the prefix "g".
If you need to use these commands with their normal names, you
can add a "gnubin" directory to your PATH from your bashrc like:
  PATH="/opt/homebrew/opt/grep/libexec/gnubin:$PATH"
==> Summary
🍺  /opt/homebrew/Cellar/grep/3.8_1: 19 files, 1MB
==> Running `brew cleanup grep`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).

💡 Note that the command grep has been installed with the prefix g to allow you to use grep as installed with macOS if necessary.

Second, after careful inspection, add the following shell script to ~/.zshrc.

# determine versions of PHP installed with HomeBrew
installedPhpVersions=($(brew ls --versions | ggrep -E 'php(@.*)?\s' | ggrep -oP '(?<=\s)\d\.\d' | uniq | sort))

# create alias for every version of PHP installed with HomeBrew
for phpVersion in ${installedPhpVersions[*]}; do
    value="{"

    for otherPhpVersion in ${installedPhpVersions[*]}; do
        if [ "${otherPhpVersion}" = "${phpVersion}" ]; then
            continue;
        fi

        value="${value} brew unlink php@${otherPhpVersion};"
    done

    value="${value} brew link php@${phpVersion} --force --overwrite; } &> /dev/null && php -v"

    alias "${phpVersion}"="${value}"
done

The script will first determine the versions of PHP you have installed with Homebrew.

The script will then create aliases for each PHP version you have installed with Homebrew. For each PHP version, the corresponding alias will unlink all other PHP versions, link the PHP version, and finally show the version information.

By adding the script to .zshrc, the script will run every time you open a new terminal. This means that the list of aliases will stay current at all times, depending on the versions of PHP that you have currently installed with Homebrew.

When you have PHP 7.4, 8.0, 8.1, and 8.2 installed with Homebrew, added the script to .zshrc, and opened a new terminal, running

alias | grep php

yields

7.4='{ brew unlink php@8.0; brew unlink php@8.1; brew unlink php@8.2; brew link php@7.4 --force --overwrite; } &> /dev/null && php -v'
8.0='{ brew unlink php@7.4; brew unlink php@8.1; brew unlink php@8.2; brew link php@8.0 --force --overwrite; } &> /dev/null && php -v'
8.1='{ brew unlink php@7.4; brew unlink php@8.0; brew unlink php@8.2; brew link php@8.1 --force --overwrite; } &> /dev/null && php -v'
8.2='{ brew unlink php@7.4; brew unlink php@8.0; brew unlink php@8.1; brew link php@8.2 --force --overwrite; } &> /dev/null && php -v'

As promised, Running

8.2

switches to PHP 8.2 and yields

PHP 8.2.1 (cli) (built: Jan 12 2023 03:48:24) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.1, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.1, Copyright (c), by Zend Technologies

Have you found a better option for switching PHP versions when using Homebrew?

From @localheinz to @ergebnis

2019-12-10T16:40:00+01:00

From @localheinz to @ergebnis

With 2019 in review and 2020 coming closer, I am sorting out a few things related to open-source projects I am maintaining.

Move

I have decided to move the open-source PHP projects I am currently maintaining on my personal account @localheinz to the organization @ergebnis on GitHub.

The following projects have been moved so far:

Why

At the moment, I have ~350 public repositories under my personal account. Most of these repositories are forks of projects I have contributed to in the past, and only a few of them are sources.

By moving the source repositories to a separate organization:

they become more visible to me and can be more easily be discovered by others
they become less attached to my person and maintenance can be more easily transferred to collaborators when necessary
adding and managing maintainers or collaborators becomes a lot easier

If you are using any of the packages provided by these repositories: thank you! I am happy that I - standing on the shoulders of giants - have built something useful for others.

In any case, take a look at CHANGELOG.md; I have provided instructions for updating. In most cases, the only things that have changed are vendor prefixes (from localheinz to ergebnis) and namespaces (from Localheinz to Ergebnis).

How

Perhaps you have been considering to do something similar?

Here is an example of how I moved localheinz/test-util to ergebnis/test-util:

transfer ownership
rename references localheinz/test-util to ergebnis/test-util
rename namespace Localheinz\Test\Util to Ergebnis\Test\Util
provide details on how to update in CHANGELOG.md
submit package ergebnis/test-util to Packagist
ensure that integration with Packagist works
abandon package localheinz/test-util on Packagist and suggest ergebnis/test-util as a replacement
tag and push a new major release of ergebnis/test-util
update packages previously using localheinz/test-util to using ergebnis/test-util, for example, in ergebnis/phpstan-rules
keep fingers crossed 🤞

The grass could be a lot greener on both sides of the fence

2019-12-03T12:00:00+02:00

The grass could be a lot greener on both sides of the fence

It is the end of 2019, and the invitation to write an article for 24 Days in December is an excellent opportunity to reflect on what has happened this year - and maybe even look back a bit further.

Past

In 1990 I wrote my first line of code on an Atari Portfolio, and at the time, I would have never guessed that one day I would be building and maintaining software for a living.

In 1999 I got paid the first time for building a website with static HTML.

In 2001 I took up an internship in a startup in Berlin, and there I would write my first line of PHP code. In 2007, shortly before dropping out of business school, I started working full-time with PHP in another startup. In the years to follow, I worked for several startups, always with PHP.

In 2012 I found out that PHP developers meet up monthly to give and listen to talks about their experiences at so-called user groups, and I first attended the Berlin PHP user group.

From writing my first line of PHP code in 2001 to attending my first user group in 2012, it took me eleven years to realize that I am part of an actual community! A community of people who not necessarily work in the same companies but a community of people who share their experiences; people who are eager to learn from and eventually help each other to become better developers!

In the months and years to follow, a lot of things changed for me. Most of all, seeing that there is a community out there, and that it is easy to become a part of it, made me want to become a better developer.

Soon I started following other developers on Twitter. I made my first contributions to open-source software. I attended my first PHP conference. Attending the user groups more or less regularly, I got to know other developers, some of whom introduced me to other people in the PHP community. I took note of books recommended by speakers, and added them to an ever-growing reading list. I overcame my fear of writing tests. Eventually, I started writing tests first. I continued to make contributions to open-source software. I began working for a company with an actual build pipeline and a process that I still admire today. I overcame framework fanboy-ism and got hired over Twitter to work remotely for a company in New York. I attended conferences more regularly. Seeing a lot of developers over and over again, I found it rather easy to get in touch with them - and was surprised that they are very approachable. I became acknowledged with more and more developer tools - tools that made my life as a PHP developer a lot easier. I started contributing to these tools, and even published a few small open-source libraries that have users other than me. I came around to writing articles, and at the moment, I’m struggling with writing this article here.

Probably none of this would have happened if I had never attended the meetings of the PHP user group - none of it. Up until the moment when I first joined the user group meeting, I was entirely concerned with making things run. By going to these meetings, I had opened a new chapter and began wondering how to make things right.

Present

In the last five years, the focus of my work has shifted from creating to maintaining and modernizing legacy applications. Thanks to excellent tooling experiences made, dealing with legacy applications is not a hard problem.

What I have come to realize in 2019, but have heard numerous time before, is, that people are the hard problems - just as Jerry Weinberg, who passed away in August 2018, put it in The Secrets of Consulting:

No matter how it looks at first, it’s always a people problem.

Gerald M. Weinberg, The Secrets of Consulting

Setting up a build pipeline, putting developer tools in place, refining a process, making it harder for developers to ship faulty code - this is all excellent.

Working on code, however, has only short-term effects: as soon as the project is over, developers are left alone with a code base they hardly understand. When developers have only learned to follow the rules enforced by automated systems, but have not learned why they have been put in place, these automated systems become an annoyance rather than a crutch.

Working with developers, on the other hand, can have long-term effects: by asking developers questions instead of giving them directions, by letting developers fail and helping them up again, by showing them alternative ways of developing software, and by encouraging them to question the status quo, they will eventually become better versions of themselves.

Future

Perhaps you are working on a legacy code base, with colleagues who do not care so much. Perhaps you are looking for a new job already. Of course, the grass always looks greener on the other side - but is it?

For some of your colleagues, being a software developer is just a 9-to-5 job. Others have already so much on their plate, maybe they really cannot and will not be able to do much more. However, there will always be interested developers who only need a little nudge or a pointer.

You could be the person reaching out, go ahead and invite them to the next user group.

This article was originally published on 24 Days in December.

Project notes

2019-10-25T07:55:00+02:00

Project notes

In almost every project I work on, I take notes in Markdown files, keep track of small lists of things that need to be done, or create small scripts - and most of these are not important enough to find their way into a journal, an issue tracker, or version control.

I have observed developers who keep these files untracked within or in a separate directory outside of the project. I keep these files within the project. This way, they are always in reach.

In 2014, Jetbrains introduced the Scratch Files feature.

However, there's something better that you might have been using already and does not depend on features provided by your IDE: a global .gitignore file.

Run

touch ~/.gitignore_global

to create a .gitignore_global file in your home directory.

Run

git config --global core.excludesfile ~/.gitignore_global

to configure git to use .gitignore_global as a global exludes file.

Add the following

 .idea/
+.note/
 .DS_Store

to to .gitignore_global to ignore a .note/ directory in any project that is under version control with git.

For example, for a project I'm currently working on, my .note/ directory currently looks like this:

.note
├── XYZ-123         # sub-directory for issue XYZ-123
│   ├── commits.md  # list of commit hashes kept as a backup
│   ├── test.php    # small script for prototyping
│   └── todo.md     # list of todos for a ticket in Markdown
├── todo.md         # list of general todos in Markdown
└── XYZ-234.md      # notes regarding issue XYZ-234

Hope it helps!

Test to the left, production to the right

2019-10-14T06:40:00+02:00

Test to the left, production to the right

Not only do I speak and read languages where texts are written and read from left-to-right and top-to-bottom, but I also work with programming languages where programs are written in the same order.

I'm also a proponent of Test-Driven Development (TDD), a practice that suggests following three simple rules:

You are not allowed to write any production code unless it is to make a failing unit test pass.

You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.

You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

— Robert C. Martin, The Three Rules of TDD

Consequently, it only feels natural to me to split the editor screen vertically, with

the more important test code on the left side
the less important production code on the right side

In JetBrains IDEs this can be achieved by right-clicking on the editor tab and then selecting Split Vertically (find out more at Editor Basics: Split Screen.

How do you organize yourself working with test and production code?

Running tests for PHPUnit in PhpStorm

2019-04-27T11:01:00+01:00

Running tests for PHPUnit in PhpStorm

Have you been working on phpunit/phpunit? Are you a user of PhpStorm?

I have and I am, and until yesterday I have been struggling with setting up phpunit/phpunit as test framework for PhpStorm so I can run tests for phpunit/phpunit from within PhpStorm for phpunit/phpunit itself.

Use Composer autoloader

In any project that requires phpunit/phpunit as a development dependency, the setup is fairly simple: pick the Use Composer autoloader option and reference the path to vendor/autoload.php.

However, for phpunit/phpunit this will not work, as it does not have a dependency on itself:

Path to phpunit.phar (with downloaded phpunit.phar)

Ok, then, let's try the option Path to phpunit.phar!

Looks like we need to download phpunit.phar here, so let's head over to Getting Started with PHPUnit 8 and find out how to download phpunit.phar`.

Personally, I ran

wget -O ~/Sites/phpunit.phar https://phar.phpunit.de/phpunit.phar
chmod +x ~/Sites/phpunit.phar

Next, I pick the Path to phpunit.phar option and specify the path to the previously downloaded phpunit.phar:

Looks like that worked fine, now let's run the tests by right-clicking on phpunit.xml, and selecting the option Run 'phpunit.xml'.

Great, the tests run! But they fail with

Testing started at 11:25 ...
/usr/local/Cellar/php@7.2/7.2.17_1/bin/php /Users/am/Sites/phpunit --configuration /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml --teamcity
PHPUnit 8.1.3 by Sebastian Bergmann and contributors.

Runtime:       PHP 7.2.17 with Xdebug 2.7.1
Configuration: /Users/am/Sites/sebastianbergmann/phpunit/phpunit.xml


TypeError : Return value of PHPUnit\Framework\Constraint\Count::getCountOf() must be of the type integer or null, none returned
 phar:///Users/am/Sites/phpunit/phpunit/Framework/Constraint/Count.php:86
 phar:///Users/am/Sites/phpunit/phpunit/Framework/Constraint/Count.php:44
 phar:///Users/am/Sites/phpunit/phpunit/Framework/Constraint/Constraint.php:45
 /Users/am/Sites/sebastianbergmann/phpunit/tests/unit/Framework/Constraint/CountTest.php:164
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:1172
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:854
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestResult.php:685
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:808
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
 phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
 phar:///Users/am/Sites/phpunit/phpunit/TextUI/TestRunner.php:601
 phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:207
 phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:163

PHP Fatal error:  Class Mock_Exception_19a384fc contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (ExceptionWithThrowable::getAdditionalInformation) in phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php(608) : eval()'d code on line 1
PHP Stack trace:
PHP   1. {main}() /Users/am/Sites/phpunit:0
PHP   2. PHPUnit\TextUI\Command::main() /Users/am/Sites/phpunit:619
PHP   3. PHPUnit\TextUI\Command->run() phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:163
PHP   4. PHPUnit\TextUI\TestRunner->doRun() phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:207
PHP   5. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/TextUI/TestRunner.php:601
PHP   6. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
PHP   7. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
PHP   8. GeneratorTest->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
PHP   9. PHPUnit\Framework\TestResult->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:808
PHP  10. GeneratorTest->runBare() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestResult.php:685
PHP  11. GeneratorTest->runTest() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:854
PHP  12. GeneratorTest->testMockingOfThrowable() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:1172
PHP  13. PHPUnit\Framework\MockObject\Generator->getMock() /Users/am/Sites/sebastianbergmann/phpunit/tests/unit/Framework/MockObject/GeneratorTest.php:190
PHP  14. PHPUnit\Framework\MockObject\Generator->getObject() phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:196
PHP  15. PHPUnit\Framework\MockObject\Generator->evalClass() phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:562
PHP  16. eval() phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:608

Fatal error: Class Mock_Exception_19a384fc contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (ExceptionWithThrowable::getAdditionalInformation) in phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php(608) : eval()'d code on line 1

Call Stack:
    0.0057     543992   1. {main}() /Users/am/Sites/phpunit:0
    0.1437    9827856   2. PHPUnit\TextUI\Command::main() /Users/am/Sites/phpunit:619
    0.1437    9827968   3. PHPUnit\TextUI\Command->run() phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:163
    0.4764   23119992   4. PHPUnit\TextUI\TestRunner->doRun() phar:///Users/am/Sites/phpunit/phpunit/TextUI/Command.php:207
    0.7250   23869248   5. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/TextUI/TestRunner.php:601
    0.7466   23869440   6. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
    3.7839   25022328   7. PHPUnit\Framework\TestSuite->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
    3.8201   25324600   8. GeneratorTest->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestSuite.php:761
    3.8201   25324600   9. PHPUnit\Framework\TestResult->run() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:808
    3.8202   25324600  10. GeneratorTest->runBare() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestResult.php:685
    3.8204   25341232  11. GeneratorTest->runTest() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:854
    3.8204   25341288  12. GeneratorTest->testMockingOfThrowable() phar:///Users/am/Sites/phpunit/phpunit/Framework/TestCase.php:1172
    3.8204   25341288  13. PHPUnit\Framework\MockObject\Generator->getMock() /Users/am/Sites/sebastianbergmann/phpunit/tests/unit/Framework/MockObject/GeneratorTest.php:190
    3.8209   25344136  14. PHPUnit\Framework\MockObject\Generator->getObject() phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:196
    3.8209   25344136  15. PHPUnit\Framework\MockObject\Generator->evalClass() phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:562
    3.8211   25350656  16. eval('class Mock_Exception_19a384fc extends Exception implements ExceptionWithThrowable, PHPUnit\Framework\MockObject\MockObject
{
    private $__phpunit_invocationMocker;
    private $__phpunit_originalObject;
    private $__phpunit_configurable = [];
    private $__phpunit_returnValueGeneration = true;


    public function expects(\PHPUnit\Framework\MockObject\Matcher\Invocation $matcher): \PHPUnit\Framework\MockObject\Builder\InvocationMocker
    {
        return $this->__phpunit_getInvocationMocker()->expects($matcher);
    }

    public function method()
    {
        $any     = new \PHPUnit\Framework\MockObject\Matcher\AnyInvokedCount;
        $expects = $this->expects($any);

        return call_user_func_array([$expects, 'method'], func_get_args());
    }

    public function __phpunit_setOriginalObject($originalObject): void
    {
        $this->__phpunit_originalObject = $originalObject;
    }

    public function __phpunit_setReturnValueGeneration(bool $returnValueGeneration): void
    {
        $this->__phpunit_returnValueGeneration = $returnValueGeneration;
    }

    public function __phpunit_getInvocationMocker(): \PHPUnit\Framework\MockObject\InvocationMocker
    {
        if ($this->__phpunit_invocationMocker === null) {
            $this->__phpunit_invocationMocker = new \PHPUnit\Framework\MockObject\InvocationMocker($this->__phpunit_configurable, $this->__phpunit_returnValueGeneration);
        }

        return $this->__phpunit_invocationMocker;
    }

    public function __phpunit_hasMatchers(): bool
    {
        return $this->__phpunit_getInvocationMocker()->hasMatchers();
    }

    public function __phpunit_verify(bool $unsetInvocationMocker = true): void
    {
        $this->__phpunit_getInvocationMocker()->verify();

        if ($unsetInvocationMocker) {
            $this->__phpunit_invocationMocker = null;
        }
    }
}
') phar:///Users/am/Sites/phpunit/phpunit/Framework/MockObject/Generator.php:608


Process finished with exit code 255

Looks like we have some issues here because we are using a different version of phpunit/phpunit for testing the version of phpunit/phpunit we have currently checked out.

Path to phpunit.phar (with phpunit binary)

While not obvious, there's a rather simple solution that was suggested by Nicolas Hohm: pick the Path to phpunit.phar option and specify the path the phpunit binary in the root of the project!

Running the tests by right-clicking on phpunit.xml, and selecting the option Run 'phpunit.xml' now works like a charm!

Even better, when enabling Xdebug and selecting the option Run 'phpunit.xml' with Coverage, we can now easily identify areas of the code base which are obviously lacking tests - something we have been doing yesterday and today here at FLYERALARAM, where the 5th PHPUnit Code Sprint has been taking place.

Hope it helps!

Accessing a system-wide terminal via hotkey on macOS

2018-10-02T11:05:00+01:00

Accessing a system-wide terminal via hotkey on macOS

When pairing with other developers, I oftentimes notice them spending more time than necessary on things that are neither interesting nor should take a lot of time.

One of these things is opening a terminal window so commands can be entered.

Very often I have observed developers move around windows on the screen in search for a previously opened terminal. While it is possible on macOS to switch between applications using ⌥ + tab or shift + ⌥ + tab, there are certainly faster and better ways of reaching a terminal. While it is also possible to open an internal terminal window in any JetBrains IDE using ⌥ + F12, these windows are usually too small to show a lot of information, and at the same time they take away space that is better suited for displaying code.

TotalTerminal provided a system-wide terminal available on a hot-key - until OS X El Capitan was released in September 2015. Because of a lack of compatibility out of the box and a lack of interest by the original maintainers, development was stopped. Instead, the maintainers suggested to switch to iTerm2, which offers similar functionality.

If iTerm's documentation for hotkeys doesn't suffice, here's a step-by-step guide for setting up a full-screen, system-wide terminal accessible via hotkey:

Basic Setup

Download iTerm2, move iTerm.app from Downloads to Applications, and open iTerm.

In iTerm, press ⌘ + , to open preferences.

Go the Keys tab, and click on the Create a Dedicated Hotkey Window... button in the lower left.

In the panel that opens up, check the Double-tab key checkbox, and press OK.

Congratulations, your hotkey window has now been configured and can be toggled on and off by double-pressing the Control key!

Customization

In order to open terminal windows or tabs using the previously used location, go to the Profiles tab, select the Hotkey Window profile, select the General tab, and in the Working Directory section, click on Reuse previous session's directory.

In order to change the font, go to the Profiles tab, select the Hotkey Window profile, select the Text tab, and and in the Font section, click on Change Font to select your favorite font. Personally, I use Operator Mono by Hoefler & Co..

In order to reduce distraction and increase the size of the hotkey window, go to the Profiles tab, select the Hotkey Window profile, select the Windows tab, and in the Window Appearance section, reduce Transparency to opaque, then in the Settings for New Windows section, click on the Style options, and select Fullscreen.

Congratulations, your hotkey window is now full-screen!

Hope it helps!

If you think iTerm makes you more productive, please consider donating.

Cost and value of DocBlocks

2018-05-06T07:25:00+02:00

Cost and value of DocBlocks

Over the years I have added, updated, and removed a lot of DocBlocks. I have also suggested to add, update, or remove DocBlocks many times, as well as explained why I believe a DocBlock makes sense in one case, and doesn't in another. In order to have a document I can refer to if I need to explain my reasoning again, I'm writing this article - maybe it's of use for you as well.

As a user of products that run software, the products I like the most are those that can be used and explored without needing a lot of documentation. As a user of open-source software I have been surprised by excellent and up-to-date documentation, and disappointed by outdated or even entirely missing documentation. As a contributor to open-source software I have witnessed the struggles and challenges of projects to keep documentation up-to-date. As a software engineer working on closed-source software I understand that there are different documentation needs for open- and closed-source software.

Regardless of whether software is open- or closed-source software, its maintenance, and the maintenance of its documentation, incurs costs. Since resources are limited, it's in the interest of everyone involved to focus on activities that provide value.

DocBlocks can provide value as documentation that lives inline with the code: it can easily be understood by developers, and interpreted by tools. The information present in DocBlocks can guide developers on the what, how and why of a piece of software. However, the value of DocBlocks diminishes quickly when they only repeat information that is already present on the structural elements they intend to document. Worse, when not kept up-to-date, they can become misleading.

Code comments pic.twitter.com/2KDRdfFE9u
— Michael Koziarski (@nzkoz) November 30, 2014

Personally, when it comes to DocBlocks, I follow two rules:

Add a DocBlock when it adds value.
Remove a DocBlock when it does not add value.

DocBlocks can be applied to a number of structural elements:

files
classes (also: interfaces and traits)
constants
properties
methods (also: functions)
variables

File

Frequently found in open-source software, file-level DocBlocks document copyright information, refer to a license document, and link to the source repository:

<?php

declare(strict_types=1);

/**
 * Copyright (c) 2017 Andreas Möller.
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 *
 * @see https://github.com/ergebnis/test-util
 */

 namespace Ergebnis\Test\Util;

So far I have not found a use for file-level DocBlocks in closed-source software.

However, I have worked on a closed-source project where dependencies had actually been checked in into version control. When introducing composer and replacing the checked-in dependencies with requirements, file-level DocBlocks proved to be extremely useful to identify some of these dependencies.

When using friendsofphp/php-cs-fixer, file-level DocBlocks similar to above can be easily added or replaced with a configuration similar to the following:

<?php

declare(strict_types=1);

$header = <<<EOF
Copyright (c) 2017 Andreas Möller

For the full copyright and license information, please view
the LICENSE file that was distributed with this source code.

@see https://github.com/ergebnis/test-util
EOF;

$config = PhpCsFixer\Config::create()->setRules([
    'header_comment' => [
        'commentType' => 'PHPDoc',
        'header' => $header,
        'location' => 'after_declare_strict',
        'separate' => 'both',
    ],
]);

File-level DocBlocks can easily be removed with a configuration similar to the following:

<?php

declare(strict_types=1);

$config = PhpCsFixer\Config::create()->setRules([
    'header_comment' => [
        'header' => '',
    ],
]);

Class

I have rarely found a need for class-level DocBlocks, and in particular, class-level DocBlocks such as

 <?php

 declare(strict_types=1);

-/**
- * Represents a user in the system.
- */
 final class User
 {
 }

do not add any value - so I remove them.

Oftentimes, a need for a description of a class is a smell. Sometimes the only thing that is required to enhance clarity is a name that reveals intent.

Property

Depending on how properties are initialized (for example, via constructor injection), some IDEs are capable of inferring their type - either from method-level DocBlocks or type declarations on constructors, or from initializations of properties within constructors. Adding DocBlocks for properties with @var tags assists with auto-completion when using an IDE, but also helps when reading the code elsewhere, so I always add DocBlocks to properties.

 <?php

 declare(strict_types=1);

 final class User
 {
+    /**
+     * @var UserId
+     */
     private $id;

+    /**
+     * @var Login
+     */
     private $login;
 }

It is worth mentioning that there have been a few RFCs related to typed properties

PHP RFC: Property type-hints (2015-07-19, in draft)
PHP RFC: Typed Properties (2016-03-16, declined)
PHP RFC: Typed Properties 2.0 (2018-06-15, accepted)

an on September 27, 2018, the PHP RFC: Typed Properties 2.0 was accepted!

🎉 Typed properties have been accepted for PHP 7.4 🎉https://t.co/64kgmIw7TQ
— Nikita Popov (@nikita_ppv) September 26, 2018

That is, starting with PHP 7.4, a lot of DocBlocks on properties can be removed.

 <?php

 declare(strict_types=1);

 final class User
 {
-    /**
-     * @var UserId
-     */
-     private $id;
+     private UserId $id;

-    /**
-     * @var Login
-     */
-     private $login;
+     private Login $login;
 }

Descriptions on property-level DocBlocks such as

 <?php

 declare(strict_types=1);

 final class User
 {
     /**
-     * The identifier of the user.
-     *
      * @var UserId
      */
     private $id;

     /**
-     * The login of the user.
-     *
      * @var Login
      */
     private $login;
 }

do not add any value - so I remove them.

Again, a need for a description of a property is a smell.

Method

Method-level DocBlocks which only repeat information that is entirely present in type and return type declarations, such as

 <?php

 declare(strict_types=1);

 class User
 {
     /**
      * @var UserId
      */
     private $id;

     /**
      * @var Login
      */
     private $login;

-    /**
-     * @param UserId $id
-     * @param Login  $login
-     */
     public function __construct(
         UserId $id,
         Login $login
     ) {
         $this->id = $id;
         $this->login = $login;
     }

-    /**
-     * @return UserId
-     */
     public function id(): UserId
     {
         return $this->id;
     }

-    /**
-     * @return Login
-     */
     public function login(): Login
     {
         return $this->login;
     }
 }

do not add any value - so I remove them.

Again, oftentimes a need for a description of a method is a smell. Consider renaming instead to clarify the intent.

With the introduction of scalar and return type declarations in PHP 7.0, as well as with the introduction of nullable type and return declarations and void return type declarations in PHP 7.1, a lot of DocBlocks can easily be replaced by corresponding type declarations:

 <?php

 declare(strict_types=1);

 final class Login
 {
     /**
      * @var string
      */
     private $value;

-    /**
-     * @param string $value
-     */
-    public function __construct($value)
+    public function __construct(string $value)
     {
         $this->value = $value;
     }

-    /**
-     * @return string
-     */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->value;
     }
 }

However, oftentimes not all of the required information is present in type and return type declarations. For example, when a method throws exceptions

 <?php

 declare(strict_types=1);

 final class Login
 {
     /**
      * @var string
      */
     private $value;

+    /**
+     * @param string $value
+     *
+     * @throws \InvalidArgumentException
+     */
     public function __construct(string $value)
     {
         if ('' === trim($login)) {
             throw new \InvalidArgumentException('Value cannot be an empty string');
         }

         $this->value = $value;
     }

     public function __toString(): string
     {
         return $this->value;
     }
 }

or when a method returns an array (of objects or scalars)

 <?php

 declare(strict_types=1);

 class UserRepository
 {
+    /**
+     * @return array<int, User>
+     */
     public function all(): array
     {
         // ...
     }
 }

then DocBlocks add value - so I add them.

When an interface is extracted (or an implementation of an interface added) and the method on the interface already has all of the information

+<?php
+
+declare(strict_types=1);
+
+interface UserRepository
+{
+    /**
+     * @return array<int, User>
+     */
+    public function all(): array
+}

then a DocBlock on the corresponding method in the implementations such as

 <?php

 declare(strict_types=1);

-class UserRepository
+final class DoctrineUserRepository implements UserRepository
 {
-    /**
-     * @return array<int, User>
-     */
     public function all(): array
     {
         // ...
     }
 }

doesn't add any value - so I remove them.

Similarly, when an abstract class is extracted (or extending a class) and implementing an abstract method (overriding a method) the method on the interface already has all of the information, then a DocBlock on the corresponding method in the child class doesn't add any value - so I remove them as well.

Variable

Sometimes return types of methods are not clear

 <?php

 declare(strict_types=1);

 use PHPUnit\Framework;

 final class DoctrineUserRepositoryTest extends Framework\TestCase
 {
     public function testByLoginReturnsUser(): void
     {
         // ...

+        /** @var User $user */
         $user = $this->fixtureFactory->get(User::class, [
             'login' => $login,
         ]);

         // ...
     }
 }

and a clarifying inline DocComment adds value - so I add them.

Generated Code

When creating files and classes in IDEs, they often add unnecessary DocBlocks. However, DocBlocks such as

 <?php

  declare(strict_types=1);

-/**
- * Created by PhpStorm.
- * User: localheinz
- * Date: 05.05.18
- * Time: 22:18.
- */

 final class User
 {
 }

 <?php

 declare(strict_types=1);

-/**
- * Class User
- */
 final class User
 {
-    /**
-     * User constructor.
-     *
-     * @param Uuid   $id
-     * @param string $login
-     */
     public function __construct(Uuid $id, string $login)
     {
         $this->id = $id;
         $this->login = $login;
     }
 }

do not add any value - so I remove them.

When using PhpStorm, the file and code templates used when creating files and classy constructs can be easily configured (and unnecessary comments removed).

When creating code with command-line tools, for example, when creating database migrations using doctrine/migrations, the generated code often contains helpful comments for getting started, such as

 <?php

 declare(strict_types=1);

 use Doctrine\DBAL\Migrations\AbstractMigration;
 use Doctrine\DBAL\Schema\Schema;

-/**
- * Auto-generated Migration: Please modify to your needs!
- */
 class Version20180426054008 extends AbstractMigration
 {
     public function up(Schema $schema)
     {
-        // this up() migration is auto-generated, please modify it to your needs
     }

     public function down(Schema $schema)
     {
-        // this down() migration is auto-generated, please modify it to your needs
     }
 }

but other than that, these DocBlocks (and additional comments) add no value - so I remove them.

When code is generated from external sources, or its structure is dictated by external sources which we do not control, for example, when generating Data Transfer Objects or similar from API definitions or documentation, then DocBlocks with descriptions may add value. Especially when there is control over the mechanisms that generate the code, then including descriptions adds little maintenance cost.

If you have different opinions, that is fine - just make sure you don't blindly add DocBlocks everywhere, but weigh costs against value.

Hope it helps!

Code coverage is a meaningless metric

2018-02-01T14:25:00+01:00

Code coverage is a meaningless metric

Oftentimes people ask: How much code coverage is sufficient? While I believe that this is a legitimate question to ask, especially when just getting started with testing, there is a better, a counter-question: Do you want to do Test-Driven Development or not?

This question has three possible answers:

Yes
No
What is Test-Driven Development?

Test-Driven Development (TDD), is a practice that suggests following three simple rules:

You are not allowed to write any production code unless it is to make a failing unit test pass.

You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.

You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

Robert C. Martin, The Three Rules of TDD

If developers follow TDD, not a single line of production code is written without a failing test first. Consequently, the resulting code coverage will always be 100%, and code coverage becomes a meaningless metric.

If developers do not follow TDD, they likely write production code, and either never or only occasionally write tests afterwards. Consequently, code coverage will vary between 0% and 100%. Code coverage will decrease when

tests are deleted
untested code is added
tested code is reformatted or refactored (the same problem is solved with fewer lines of code)

and it will increase when

tests are added
untested code is removed
tested code is reformatted or refactored (the same problem is solved with more lines of code)

While you can achieve 100% code coverage when writing tests after the fact, how confident will you be that the tests are meaningful? How confident will you be that the code works as expected in production?

For example, I recently added a --dry-run option to ergebnis/composer-normalize. Since a collaborator from a 3rd-party package is marked as final and does not implement an interface, I did not have a possibility to create a test double for it. If you look closely, the code I added to output a diff in --dry-run mode is largely untested. Still, I have 100% code coverage.

While the changes in code coverage might tell you something (what exactly, you have to find out for yourself), do you still think code coverage itself is a meaningful metric?

Personally, I have decided to follow the three rules of TDD. Following these rules simplifies a lot of things for me:

There's no need to discuss what to test - every component is equally important and will be thoroughly tested.
There's no need to discuss when to test - tests are always written first.
There's no need to discuss how much code coverage is sufficient - it will always be 100%.

You might have a different point of view, and if that works for you and your clients, fine.

However, if you are still asking how much coverage you should aim for, here is a tweet by Marco Pivetta for you:

Broke production because I didn't bother covering >90%, and affected code path was in the 10%.

To those that say testing everything isn't worth doing: STFU.
— @ocramius@mastodon.social 🇺🇦🍥 (@Ocramius) January 31, 2018

If you are still hesitant, the hardest part with testing is getting started.

Good luck!

Makefile for lazy developers

2018-01-24T09:30:00+01:00

Makefile for lazy developers

Whatever the size of the software project, I believe in, subscribe to, and promote Continuous Integration. Personally, I rely on GitHub Actions as an automated build system. Even this blog here is built with, and eventually deployed into production using GitHub Actions.

Regardless of whether an automated build system can be set up and used for a project or not, I prefer to be able to run build steps locally. This prevents stress-testing the automated build system and taking away resources from other developers. Also, it gives me more confidence before committing and pushing changes upstream.

The first time I heard of an automated build tool was when I was working on a crowd investment project in 2011. Back then a developer set up Capistrano, and I didn't understand a thing. Then had used Phing for a while. For a couple of years now I have been using make, after having been introduced to it when working on a project in 2014. While it has its limitations, it's short and simple, and most of all, it get's the job done.

In most of my projects I use a Makefile similar to the following:

.PHONY: it
it: coding-standards static-code-analysis tests

.PHONY: code-coverage
code-coverage: vendor
	vendor/bin/phpunit --configuration=test/Unit/phpunit.xml --coverage-text

.PHONY: coding-standards
coding-standards: vendor
	vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --diff --show-progress=dots --verbose

.PHONY: mutation-tests
mutation-tests: vendor
	mkdir -p .build/infection
	vendor/bin/infection --configuration=infection.json

.PHONY: static-code-analysis
static-code-analysis: vendor
	mkdir -p .build/psalm
	vendor/bin/psalm --config=psalm.xml --clear-cache
	vendor/bin/psalm --config=psalm.xml --show-info=false --stats --threads=10

.PHONY: static-code-analysis-baseline
static-code-analysis-baseline: vendor
	mkdir -p .build/psalm
	vendor/bin/psalm --config=psalm.xml --clear-cache
	vendor/bin/psalm --config=psalm.xml --set-baseline=psalm-baseline.xml

.PHONY: tests
tests: vendor
	vendor/bin/phpunit --configuration=test/Unit/phpunit.xml
	vendor/bin/phpunit --configuration=test/Integration/phpunit.xml

vendor: composer.json composer.lock
	composer validate
	composer install
	composer normalize

As you can see, I have defined a few phony targets, which may run any number of commands, or depend on so-called prerequisites.

For example, running

make tests

will first execute the vendor target, followed by running unit and integration tests. Running

make coding-standards

will first execute the vendor target, followed by running php-cs-fixer. You get the idea.

A note on the vendor target: I previously used to have a composer target. After posting this article on Reddit, Nic Wortel provided an excellent suggestion:

I use the following recipe in my Makefiles:
vendor: composer.json composer.lock
	composer install
This will compare the timestamp of the vendor directory with those of composer.json and composer.lock, and will only execute the recipe if either of the composer files is newer than the vendor directory, or if the vendor directory is missing.

Nic Wortel

Excellent, this saves even more time!

Finally, I have added an it target. Running

make it

will execute all of the targets I consider important enough to be run before I commit and push changes upstream.

Now, you might have noticed that while I have a penchant for keeping things sorted, I have intentionally defined it as the first target. There's a good reason to it: unless a target has been specified explicitly, the first target defined in the Makefile will be executed. That is, by making it the first target, I can run

make

to execute all of the important targets.

Nonetheless, as I have gotten into the habit of running these tasks many, many (dozens? hundreds?) of times throughout the day, it's still a bit too much typing, right? Therefore, I have created an alias in my shell configuration:

# Makefile
alias m="make"

Running

achieves the same now. I believe that's the closest thing to making a build in one step, with only two key strokes.

Hope it helps to increase your productivity!

Normalizing composer.json

2018-01-15T08:30:00+01:00

Normalizing composer.json

If you are using composer, you have probably modified composer.json at least once to keep things nice and tidy.

In fact, when I started using composer in late summer 2012, I of course edited composer.json manually, even when I wanted to add or update dependencies. I soon learned that one should run

composer require foo/bar:~x.y.z

instead, as this prevents pulling in undesired updates. I did that, but in order to keep the list of dependencies sorted, I actually had to do it twice:

require package
move package in require or require-dev section so packages are sorted
run command again (to keep the lock file updated, as the order of dependencies matters for the calculation of the hash)

That's a bit crazy, right? And just to keep things nice and tidy!

Then I came across a tweet by Henrik Joreteg:

Favorite little OCD module that I use *all the time* fixpack: https://t.co/amXS7th05U

Alphabetizes dependencies, and cleans up package.json
— Henrik Joreteg (@HenrikJoreteg) March 25, 2014

Nice, I wasn't alone with liking things nice and tidy!

At the time I was contracting for a company here in Berlin. One of the best parts working there was that a lot of respected members of the PHP community stopped by the office oftentimes, for example, Benjamin Eberlei, David Zuelke, and Nils Adermann. Nils (whom you probably know as one of the maintainers of composer, together with Jordi Boggiano) even regularly worked out of the office. Hesitant at first, I approached him about this issue, and asked him whether they would consider a pull request. I think he liked it, so I was quite happy and figured it should be ok to do something about it.

Nonetheless, it took me until December 2014 until I eventually opened a pull request to add the --sort-packages option to composer.

Since then it has been possible to run, for example,

composer require --dev --sort-packages phpunit/phpunit

to require a package and keep packages sorted (if you already have that package required, you can run the command to trigger sorting).

With a bit of tweaking not only packages and platform requirements would be sorted, but platform requirements listed before packages. Thanks to Hanov Ruslan, this behaviour can be configured, making it unnecessary to use the option on the command line.

Not only have a lot of people blogged about the feature, but a quick search on GitHub reveals that the configuration option is used at least 327,598 times! Excellent!

Now, how about taking it a step further? Today I present to you ergebnis/composer-normalize, a composer plugin for tidying up all of composer.json!

Run

composer global require ergebnis/composer-normalize

to install the composer plugin globally.

Run

composer normalize

to normalize composer.json in the working directory or run

composer normalize ~/Sites/foo/bar/composer.json

to normalize composer.json in the ~/Sites/foo/bar directory.

The NormalizeCommand provided by the NormalizePlugin within this package will

determine whether a composer.json exists
determine whether a composer.lock exists, and if so, whether it is up to date
use the ComposerJsonNormalizer to normalize the content of composer.json
format the normalized content (either as sniffed, or as specified using the --indent-size and --indent-style options)
write the normalized and formatted content of composer.json back to the file
update the hash in composer.lock if it exists and if an update is necessary

Currently, the following normalizations will be applied

restructure composer.json according to the underlying JSON schema
sort entries in the bin section (by value)
sort entries in the config, extra, and scripts-descriptions sections (by key)
sort entries in the conflict, provide, replace, require, require-dev, and suggest sections (as you are used to from the sort-packages configuration)
normalize version constraints in conflict, provide, replace, require, and require-dev sections

The command accepts the following argument

file: Path to composer.json file (optional, defaults to composer.json in working directory)

The command comes with the following options

--dry-run: Show the results of normalizing, but do not modify any files
--indent-size: Indent size (an integer greater than 0); should be used with the --indent-style option
--indent-style: Indent style (one of "space", "tab"); should be used with the --indent-size option
--no-update-lock: Do not update lock file if it exists

Here is an example of running

composer normalize

on composer/composer itself:

diff --git a/composer.json b/composer.json
index dd672c3b..330f73d0 100644
--- a/composer.json
+++ b/composer.json
@@ -1,9 +1,13 @@
 {
     "name": "composer/composer",
+    "type": "library",
     "description": "Composer helps you declare, manage and install dependencies of PHP projects, ensuring you have the right stack everywhere.",
-    "keywords": ["package", "dependency", "autoload"],
+    "keywords": [
+        "package",
+        "dependency",
+        "autoload"
+    ],
     "homepage": "https://getcomposer.org/",
-    "type": "library",
     "license": "MIT",
     "authors": [
         {
@@ -17,52 +21,58 @@
             "homepage": "https://seld.be"
         }
     ],
-    "support": {
-        "irc": "irc://irc.freenode.org/composer",
-        "issues": "https://github.com/composer/composer/issues"
-    },
     "require": {
         "php": "^5.3.2 || ^7.0",
-        "justinrainbow/json-schema": "^3.0 || ^4.0 || ^5.0",
         "composer/ca-bundle": "^1.0",
         "composer/semver": "^1.0",
         "composer/spdx-licenses": "^1.2",
+        "justinrainbow/json-schema": "^3.0 || ^4.0 || ^5.0",
+        "psr/log": "^1.0",
+        "seld/cli-prompt": "^1.0",
         "seld/jsonlint": "^1.4",
+        "seld/phar-utils": "^1.0",
         "symfony/console": "^2.7 || ^3.0 || ^4.0",
-        "symfony/finder": "^2.7 || ^3.0 || ^4.0",
-        "symfony/process": "^2.7 || ^3.0 || ^4.0",
         "symfony/filesystem": "^2.7 || ^3.0 || ^4.0",
-        "seld/phar-utils": "^1.0",
-        "seld/cli-prompt": "^1.0",
-        "psr/log": "^1.0"
+        "symfony/finder": "^2.7 || ^3.0 || ^4.0",
+        "symfony/process": "^2.7 || ^3.0 || ^4.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^4.8.35 || ^5.7",
         "phpunit/phpunit-mock-objects": "^2.3 || ^3.0"
     },
+    "suggest": {
+        "ext-openssl": "Enabling the openssl extension allows you to access https URLs for repositories and packages",
+        "ext-zip": "Enabling the zip extension allows you to unzip archives",
+        "ext-zlib": "Allow gzip compression of HTTP requests"
+    },
     "config": {
         "platform": {
             "php": "5.3.9"
         }
     },
-    "suggest": {
-        "ext-zip": "Enabling the zip extension allows you to unzip archives",
-        "ext-zlib": "Allow gzip compression of HTTP requests",
-        "ext-openssl": "Enabling the openssl extension allows you to access https URLs for repositories and packages"
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.7-dev"
+        }
     },
     "autoload": {
-        "psr-4": { "Composer\\": "src/Composer" }
+        "psr-4": {
+            "Composer\\": "src/Composer"
+        }
     },
     "autoload-dev": {
-        "psr-4": { "Composer\\Test\\": "tests/Composer/Test" }
-    },
-    "bin": ["bin/composer"],
-    "extra": {
-        "branch-alias": {
-            "dev-master": "1.7-dev"
+        "psr-4": {
+            "Composer\\Test\\": "tests/Composer/Test"
         }
     },
+    "bin": [
+        "bin/composer"
+    ],
     "scripts": {
         "test": "phpunit"
+    },
+    "support": {
+        "issues": "https://github.com/composer/composer/issues",
+        "irc": "irc://irc.freenode.org/composer"
     }
 }

If you need to change the indentation, you can use the --indent-size and --indent-style options. Here's an example of running

composer normalize --indent-size=2 --indent-style=space

on composer/composer itself:

diff --git a/composer.json b/composer.json
index dd672c3b..071c99c6 100644
--- a/composer.json
+++ b/composer.json
@@ -1,68 +1,78 @@
 {
-    "name": "composer/composer",
-    "description": "Composer helps you declare, manage and install dependencies of PHP projects, ensuring you have the right stack everywhere.",
-    "keywords": ["package", "dependency", "autoload"],
-    "homepage": "https://getcomposer.org/",
-    "type": "library",
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "Nils Adermann",
-            "email": "naderman@naderman.de",
-            "homepage": "https://www.naderman.de"
-        },
-        {
-            "name": "Jordi Boggiano",
-            "email": "j.boggiano@seld.be",
-            "homepage": "https://seld.be"
-        }
-    ],
-    "support": {
-        "irc": "irc://irc.freenode.org/composer",
-        "issues": "https://github.com/composer/composer/issues"
+  "name": "composer/composer",
+  "type": "library",
+  "description": "Composer helps you declare, manage and install dependencies of PHP projects, ensuring you have the right stack everywhere.",
+  "keywords": [
+    "package",
+    "dependency",
+    "autoload"
+  ],
+  "homepage": "https://getcomposer.org/",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Nils Adermann",
+      "email": "naderman@naderman.de",
+      "homepage": "https://www.naderman.de"
     },
-    "require": {
-        "php": "^5.3.2 || ^7.0",
-        "justinrainbow/json-schema": "^3.0 || ^4.0 || ^5.0",
-        "composer/ca-bundle": "^1.0",
-        "composer/semver": "^1.0",
-        "composer/spdx-licenses": "^1.2",
-        "seld/jsonlint": "^1.4",
-        "symfony/console": "^2.7 || ^3.0 || ^4.0",
-        "symfony/finder": "^2.7 || ^3.0 || ^4.0",
-        "symfony/process": "^2.7 || ^3.0 || ^4.0",
-        "symfony/filesystem": "^2.7 || ^3.0 || ^4.0",
-        "seld/phar-utils": "^1.0",
-        "seld/cli-prompt": "^1.0",
-        "psr/log": "^1.0"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^4.8.35 || ^5.7",
-        "phpunit/phpunit-mock-objects": "^2.3 || ^3.0"
-    },
-    "config": {
-        "platform": {
-            "php": "5.3.9"
-        }
-    },
-    "suggest": {
-        "ext-zip": "Enabling the zip extension allows you to unzip archives",
-        "ext-zlib": "Allow gzip compression of HTTP requests",
-        "ext-openssl": "Enabling the openssl extension allows you to access https URLs for repositories and packages"
-    },
-    "autoload": {
-        "psr-4": { "Composer\\": "src/Composer" }
-    },
-    "autoload-dev": {
-        "psr-4": { "Composer\\Test\\": "tests/Composer/Test" }
-    },
-    "bin": ["bin/composer"],
-    "extra": {
-        "branch-alias": {
-            "dev-master": "1.7-dev"
-        }
-    },
-    "scripts": {
-        "test": "phpunit"
+    {
+      "name": "Jordi Boggiano",
+      "email": "j.boggiano@seld.be",
+      "homepage": "https://seld.be"
+    }
+  ],
+  "require": {
+    "php": "^5.3.2 || ^7.0",
+    "composer/ca-bundle": "^1.0",
+    "composer/semver": "^1.0",
+    "composer/spdx-licenses": "^1.2",
+    "justinrainbow/json-schema": "^3.0 || ^4.0 || ^5.0",
+    "psr/log": "^1.0",
+    "seld/cli-prompt": "^1.0",
+    "seld/jsonlint": "^1.4",
+    "seld/phar-utils": "^1.0",
+    "symfony/console": "^2.7 || ^3.0 || ^4.0",
+    "symfony/filesystem": "^2.7 || ^3.0 || ^4.0",
+    "symfony/finder": "^2.7 || ^3.0 || ^4.0",
+    "symfony/process": "^2.7 || ^3.0 || ^4.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^4.8.35 || ^5.7",
+    "phpunit/phpunit-mock-objects": "^2.3 || ^3.0"
+  },
+  "suggest": {
+    "ext-openssl": "Enabling the openssl extension allows you to access https URLs for repositories and packages",
+    "ext-zip": "Enabling the zip extension allows you to unzip archives",
+    "ext-zlib": "Allow gzip compression of HTTP requests"
+  },
+  "config": {
+    "platform": {
+      "php": "5.3.9"
+    }
+  },
+  "extra": {
+    "branch-alias": {
+      "dev-master": "1.7-dev"
+    }
+  },
+  "autoload": {
+    "psr-4": {
+      "Composer\\": "src/Composer"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Composer\\Test\\": "tests/Composer/Test"
     }
+  },
+  "bin": [
+    "bin/composer"
+  ],
+  "scripts": {
+    "test": "phpunit"
+  },
+  "support": {
+    "issues": "https://github.com/composer/composer/issues",
+    "irc": "irc://irc.freenode.org/composer"
+  }
 }

Hope you like it!

Pretty-printing JSON with custom indentation

2018-01-04T11:25:00+01:00

Pretty-printing JSON with custom indentation

PHP 5.4 added the JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, and JSON_UNESCAPED_UNICODE constants for use with the json_encode() function.

For example, you can use the JSON_PRETTY_PRINT constant to encode a value to a JSON string with four spaces of indentation.

<?php

declare(strict_types=1);

$data = [
    'name' => 'Andreas Möller',
    'emoji' => '🤓',
    'urls' => [
        'https://localheinz.com',
        'https://github.com/localheinz',
        'https://twitter.com/localheinz',
    ],
];

echo json_encode(
    $data,
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);

{
    "name":"Andreas Möller",
    "emoji":"🤓",
    "urls":[
        "https://localheinz.com",
        "https://github.com/localheinz",
        "https://twitter.com/localheinz"
    ]
}

But what if you need to indent a JSON string with two spaces or tabs?

In June 2022, only 7 out of 21 people voted for a related json_encode indentation RFC, which proposed adding a parameter to the json_encode() that would allow configuring the number of spaces to use for indenting the resulting JSON string.

If you need to indent a JSON string with an indentation other than four spaces, you need to solve the problem in PHP code.

But fear not - based on source code I found in composer/composer, linking back to an article by Dave Perrett from 2008, I have built the PHP package ergebnis/json-printer.

To install the PHP package, run

composer require ergebnis/json-printer

After adjusting the example from earlier using the printer, the script produces a JSON string indented with two spaces.

<?php

declare(strict_types=1);

use Ergebnis\Json\Printer;

$data = [
    'name' => 'Andreas Möller',
    'emoji' => '🤓',
    'urls' => [
        'https://localheinz.com',
        'https://github.com/localheinz',
        'https://twitter.com/localheinz',
    ],
];

$json = json_encode(
    $data,
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);

$printer = new Printer\Printer();

echo $printer->print(
    $json,
    str_repeat(' ', 2)
);

{
  "name":"Andreas Möller",
  "emoji":"🤓",
  "urls":[
    "https://localheinz.com",
    "https://github.com/localheinz",
    "https://twitter.com/localheinz"
  ]
}

I hope it helps - I definitely need this for normalizing composer.json!

Essential PhpStorm plugins

2017-10-27T09:30:00+01:00

Essential PhpStorm plugins

If you are like me and have been programming for a bit, you probably have worked with several editors and IDEs. Over the years, I have tried a bunch of them - with varying degrees of successes. Some of them were just the right tool to get started, others were recommended by friends and developers along the way. Most of them were quickly outgrown by the projects I worked on at the time.

So I kept looking for alternatives.

PhpStorm

In January 2012 I attended a meeting of BEPHPUG, the Berlin PHP user group. At that meeting, a few IDEs and editors (some of which I had worked with before) were demonstrated. Bastian Hofmann gave a demonstration of PhpStorm, and I was amazed! Directly after the meeting I went home, installed it, and have been using it ever since. As advertised, it's lightning fast and smart, and I can't image I could be any happier or more productive with any other IDE!

Plugins

Nonetheless, while PhpStorm already is the perfect development environment, there are plugins that make it even better. I have tried a few, and here's a list of what I see as essential PhpStorm plugins:

.env files support by Adel Fayzrakhmanov
.ignore by Jakub Chrzanowski
Apache config (.htaccess) support by Alexey Gopachenko, Maxim Kolmakov and Svetlana Zemlyanskaya
BashSupport by Joachim Ansorg
CamelCase by Johannes Pfeiffer
Code With Me by JetBrains s.r.o
CodeGlance by Adam Scarr
GitToolBox by Lukasz Zielinski
Key Promoter X by Patrick Scheibe
Lines Sorter by Sylvain Francois
Makefile support by Victor Kropp
Markdown Navigator Enhanced by Vladimir Schneider
NEON support by Jan Dolecek and David Matějka
PHP Annotations by Daniel Espendiller
PHPStan / Psalm / Generics by Daniel Espendiller
PHPUnit Enhancement by Daniel Espendiller
Php Inspections (EA Extended) by Vladimir Reznichenko, Ivan Scherbak and David Rodrigues
Php Inspections (EA Ultimate) by Vladimir Reznichenko
RegexpTester by Sergey Evdokimov
String Manipulation by Vojtěch Krása
Symfony Plugin by Daniel Espendiller

You can find more plugins from within the IDE or by browsing the JetBrains PhpStorm Plugin Repository.

Not using PhpStorm yet?

If you haven't been using PhpStorm before, I highly recommend giving it a try. If you are a student, you can even use PhpStorm or any JetBrains IDE free of charge. JetBrains also offer a free 30-day-trial, so you can find out if PhpStorm will work for you without any strings attached. If you need some more time, you can also participate in the PhpStorm Early Access Program, which allows you to use the early releases of upcoming versions in exchange for living with (and ideally reporting) an occasional bug or two.

Don't waste any more time with mediocre editors or IDEs!