design-patterns-php is a reading catalogue, and its licence keeps it that way

Two examples per pattern, one for the shape and one for the use

The repository is part of the Refactoring.Guru project and contains PHP examples for all the classic GoF design patterns. The structure of each pattern is the point, and the README is explicit about the two kinds of example it ships.

The conceptual examples show the internal structure of patterns, including detailed comments. The RealWorld examples show how patterns can be used in real-world PHP applications.

That pairing is what makes the repository more useful than a list of links. A pattern diagram tells you the participants and their relationships, and a production code sample tells you what the pattern looks like when it is not being explained to anybody. Most pattern catalogues give you one or the other.

The FAQ in the README addresses the confusion that comes from the second kind. When the roles in a RealWorld example are unclear, the advice is to take a look at the conceptual example first, because that is where you find detailed descriptions of each class in a pattern, its role, and its connection to other classes. The other FAQ entry defines the term that appears throughout the code, client code, meaning a client of classes defined as part of a pattern, which is merely a caller of the given methods or a user of the given classes, in other words the part of your application's code that uses the pattern's classes.

That definition is worth having before you read the examples, because the comments in the code refer to it.

Type declarations are a teaching tool here, not a style choice

The examples require PHP 7.3 and newer, and the README gives a reason for the requirement that is unusual and revealing. This version provides explicit argument and return type declarations, which help to understand better some patterns' features that are not very obvious in a dynamically typed language.

That is the justification. Patterns like Strategy, Command and State are defined by what a collaborator can do, and in PHP, where any object can respond to any method, the contract between the client and the collaborator is invisible unless the types are written down. The declarations make the interface legible.

The examples are also runnable rather than illustrative. All examples can be launched via the command line, using the PHP executable.

php src/Path-to-example/index.php

Each one is a self contained script that prints its own output, so the repository can be used as a set of executable notes rather than a library you import. The README recommends working with the examples in PhpStorm or Visual Studio Code, which is reasonable given that a reader will be stepping through the objects one by one.

The roadmap section lists one open item, Memento: RealLife, which is unchecked, and the explanation is that the author is out of decent ideas for real-world usages for that pattern in PHP applications, and invites suggestions through an issue. That single open box is a decent summary of the repository's character. The catalogue is broad and the examples are chosen where the pattern genuinely fits a PHP application, rather than being filled in for completeness.

One file per example, and a naming convention to match

The contributor's guide sets out the house style, and the fourth rule is the one that shapes the reading experience. Aim to put all code within one file. The author is honest about the tension, saying that yes, this is not how it is supposed to be done in production, but it helps people to understand examples better since all code fits into one screen.

That is a deliberate trade. A pattern example spread over four files teaches you the file layout of a PHP application as well as the pattern. A pattern example in one file teaches you the pattern, and the author has made the call that the second is worth more here.

The other rules are equally specific. All code should match the PSR12 extended coding style guide, and code should be hard wrapped at the 80th character, which the README explains is to help list the code on the website without scrollbars. Examples should follow the namespace convention RefactoringGuru\{pattern-name}\{example-name}.

<?php

namespace RefactoringGuru\FactoryMethod\Example\Buttons;

class Button {
...

There is one more convention that only makes sense once you know what the repository is for. Comments may carry language tags, such as an English section followed by a Russian one, and the notation exists to keep the code in one place while allowing the website to generate separate versions of the examples for all the listed languages. The README says not to be scared of the non-English part of such comments, and that you are free to change something in a comment even if you get it wrong, since the maintainers will tell you how to fix it during the pull request.

The repository root also carries composer.json, composer.lock and a ruleset.xml, which is the PHP_CodeSniffer ruleset that the style rules are enforced with, alongside a .travis.yml for the build.

The licence is the boundary of the whole project

The licence is stated in the README in one line, and it is the single most important line for anyone considering this repository as more than a reading list.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

The three terms matter separately. Attribution means you credit the authors, and the credits section names them, Alexander Shvets and Alexey Pyltsyn. NonCommercial means you cannot use the code in a commercial product. NoDerivatives means you cannot publish modified versions of it, and the contributor's guide is consistent with that, since the guide invites fixes but the licence still governs redistribution of the result.

So the repository is a catalogue to learn from and to read, and the examples are meant to be read. For a learner, that is exactly the right licence, because the code is short and the point is to understand the shape of a pattern. For a team that wants to adopt a pattern, the same licence is a hard stop, and the answer is to write the implementation themselves, which is a few tens of lines once the pattern is understood.

That is the design of the project as a whole. The value is in the explanation and the structure, and the code is the shortest possible illustration of it. The repository also points back to the wider Refactoring.Guru catalogue of design patterns, with the PHP page as the language specific entry.

What this repository is not

It is worth being clear about the category, because the name invites the wrong comparison.

This is not an implementation of the patterns, as a library or a framework. There is no service container, no autoloaded hierarchy of pattern classes and no API to call. The composer.json in the repository root is there because the examples are PHP projects that happen to have a manifest, and the README does not document a composer install as a step. The documented workflow is to run one file with the PHP executable.

It is also not a tutorial with a progression. There is no chapter order, no exercises and no narrative. The reader is expected to know which pattern they are about to look at, and the FAQ's advice to start with the conceptual example assumes you already have a pattern in mind.

What it is, then, is a reference set with a strong point of view about presentation. The conceptual example is annotated to the level where a class diagram would be, and the RealWorld example answers the question the diagram leaves open. The one file per example rule and the 80 character wrap exist to serve the website, which renders these snippets for every language the project covers.

That last point is the thing to keep in mind when you read the code. These files are written to be displayed, not to be shipped, and the style guide says so explicitly when it admits that putting everything in one file is not how production code should be done.

Editorial conclusion

design-patterns-php fits a developer who wants to see a pattern implemented in idiomatic PHP, in a form short enough to read in one sitting, and who is choosing a pattern for a specific problem rather than learning them in order. It is the wrong thing to depend on as a library, because it is a set of examples rather than a package, and the licence forbids commercial use and derivatives. Verify first that your PHP is 7.3 or newer, read the conceptual example before the RealWorld one as the FAQ advises, and check the style rules before you send a pull request, since the contribution guide is specific about wrapping and naming.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. RefactoringGuru/design-patterns-php on GitHub