Chemaclass - php

Recipes for Decoupling

2022-11-28T00:00:00+00:00

What is coupling, and why is it bad? What is decoupling, and how to do it efficiently? This book is a compilation of strategies to decouple your domain code from those infrastructure details, so you can enjoy a healthier system in the long run.

This book will teach you how to create PHPStan rules from no knowledge, and then it will guide you across many decoupling opportunities like, for example:

web framework
cli frameworks
form validation
orm and database
test framework

Read more about the book: matthiasnoback.nl/book/recipes-for-decoupling/

Buy it here: leanpub.com/recipes-for-decoupling

Phel: The Lisp That Compiles to PHP

2021-02-01T00:00:00+00:00

A new Functional Programming language built-in on the PHP ecosystem.

The Phel Language #

Phel is a Functional Programming (FP) language that compiles to PHP. It is a dialect of Lisp inspired by Clojure and Janet.

Features #

Built on PHP’s ecosystem
Good error reporting
Different Datastructures (Arrays, Tables, and Tuples)
Macros
Recursive functions
Powerful but simple Syntax
REPL

Why Phel? #

Phel is a creation of Jens Haase, and as he mentions on the website, “it is the result of many failed attempts to do functional programming in PHP”. He was looking for something with these characteristics:

A LISP-inspired
Functional Programming language
That runs on cheap hosting providers
It is easy to write and debug

From my point, it was ending May 2020 when I finished the book Seven Languages in Seven Weeks, in which I learned the basics of Prolog, Erlang, Clojure, Haskell… I even created a repository in GitHub to store my progress over the weeks with these learnings.

Suddenly, one day beginning of June 2020, I saw a post in Reddit’s PHP official channel, with a message of someone mentioning this “Phel” project, claiming to be a “functional programming language” written in PHP!

I’ve worked with PHP for around 8 years so far, and I always try to combine OOP with FP as much as possible (because I believe both paradigms are better combined; they are not necessarily exclusive), and a new dialect of Lisp fully written in native PHP 7.4 sounded really exciting. I decided to take a look at it. I wanted to see the code.

The fresh readings from Mathias NoBack books such as Object Design Style Guide, and Advanced Web Application Architecture, gave me the courage to try out what I learned and put it for real in a project. This was (and still is) a beautiful challenge, which helps me to test myself and grow professionally at the same time.

My first commit was done on 6 June 2020, and since then I’ve been dedicating a little time each day during my free hours to its development. It helps me to learn more about FP, languages’ internal design, and best practices on testing and software design architecture in general.

I started applying minor changes until I ended refactoring the whole compiler structure (among other things) in order to make the modules easier to read and understand. Psalm, strict types, good test coverage, unifying code style… These were some of my favorite topics.

Example of Phel code #

The following example gives a short impression of how Phel looks like:

# Define a namespace
(ns my\example)
# Define a variable with name "my-name" and value "world"
(def my-name "world")
# Define a func with name "print-name" and one argument
(defn print-name [your-name]
 (print "hello" your-name))
# Call the function
(print-name my-name)

Current status of Phel #

We prepared an easy Getting Started Guide
We prepared an easy GitHub Repository with a Phel Scaffolding Template
We just released the first official version: 0.1.0

Check out the official website with all documentation: https://phel-lang.org/

Also recommended #

Functional Programming with Phel - JesusValera

To Mock or Not to Mock

2021-01-11T00:00:00+00:00

Mocking is useful, but “what to mock” usually turns out to be more complicated than expected if you don’t treat this carefully.

How to escape the mocking hell #

What is actually happening when we create a mock? Which types of mocks are there? Is mocking good or bad? Well, as always, everything depends on the context. And here we will consider some of the main situations about when to mock and when not to mock, but especially why.

What happens when you mock something? #

First, we should define what is a mock:

In a unit test, mock objects can simulate the behavior of complex, real objects and are therefore useful when it is impractical or impossible to incorporate a real object into a unit test.

Mocking makes sense in a unit testing context. An integration test should go through the real implementation checking the integration between multiple units, which are even allowed to talk to the DB or File IO: infrastructure code. Therefore we should agree that a unit test is a fast and deterministic test that doesn’t rely on external dependencies and doesn’t require any special context to run.

Mock objects meet the interface requirements. In consequence, they allow us to write and unit-test functionality without calling complex underlying or collaborating classes.

A mock is a test double that stands in for real implementation code during the unit testing process. It is also capable of producing assertions about how it was manipulated by the test subject during the test run.

I strongly recommend you to read this post if you want to get into the details of why Mocking is a code smell (Topics like these: What is a mock? What is a unit test? What is test coverage? What is tight coupling? What causes tight coupling? What does composition have to do with mocking? How do we remove coupling? and more!)

The problem with mocking #

When you mock you are overriding the logic of the mocked class. The real logic is getting hidden behind the scenes and there is actually where bugs love to live. Consider that:

The mock may have attributes, methods, or arguments that the real object doesn’t.
The mock’s return values may differ from the real objects’ return values. For example, it may return a different type of object that has different attributes.
The mock’s side effects and behavior may differ from the real objects’ ones. For example, maybe the mock fails to raise an exception when the real object would raise it.

Alternatives to mocking #

“Are you saying that mocking is bad and we shouldn’t mock?!” No.

It depends on what you are “overriding”.

Is your business domain logic what you are mocking? Then it’s wrong.
Is the connection to the DB what you are mocking? Then it’s right.

It depends on the context of the logic and where that logic belongs.

Is it part of your business domain logic? Then you shouldn’t mock it but instantiate it.

Is it part of any infrastructure dependency like DB connection, IO file system, Network, or any external service that has nothing to do directly with your business domain? Then mock it using abstractions/interfaces.

The interface should be the contract between your business domain logic and its external infrastructure dependencies. Imagine how easy it would be to unit test your domain logic by instantiating it and calling their methods with different arguments expecting different inputs under your entire control.

Some tricks #

When you are writing a unit test:

Try to instantiate your classes first.
Avoid mocking concrete classes. I wrote an article exclusively about this: encouraging final classes and interfaces.

Mock interfaces. Instantiate concrete classes.

“Excessive use of mocks leads to legacy code.” - Philippe Boargau

How can we avoid excessive mocking? #

Favor immutable state over a mutable state.
Make dependencies explicit.
Program to an interface, not to an implementation.

References #

Mocking is a code smell - Eric Elliott
When to mock & Test Definitions - Uncle Bob
Final classes by default - Matthias Noback
The problem with mocks - Sean Hammond
A Set of Unit Testing Rules - Michael Feathers

Never Use array_merge in a Loop

2020-11-10T00:00:00+00:00

Using array_merge inside a loop is a performance killer. The spread operator will help you to improve this by flatting the array.

Flattening a one-level array #

I have seen people using the array_merge function in a loop like:

<?php
$lists = [
 [1, 2],
 [3, 4],
 [5, 6],
];
$merged = [];
foreach($lists as $list) {
 $merged = array_merge($merged, $list);
}
// $merged === [1, 2, 3, 4, 5, 6];

This is a very bad practice because it’s a (memory) performance killer! Instead, you should use the spread operator (in PHP since 5.6!):

<?php
$lists = [
 [1, 2],
 [3, 4],
 [5, 6],
];
$merged = array_merge(...$lists);
// === [1, 2, 3, 4, 5, 6];

Unpacking an assoc-array #

What if you had an assoc-array instead like this one?

<?php
$lists = [
 'key-1' => [1, 2],
 'key-2' => [3, 4],
 'key-3' => [5, 6],
];

In that case, you will need to unpack its values:

<?php
$merged = array_merge(...array_values($lists));
// === [1, 2, 3, 4, 5, 6];

In Functional Programming, this is known as flatting a list. No loops & no more performance problem.

Flatting a multilevel array #

What if you wanted to flat a multilevel array like this one?

<?php
$lists = [[1], 2, [[3, 4], 5], [[[]]], [[[6]]], 7, 8, []];

Or like this one, even with key-values?

<?php
$lists = [
 'key-1' => [
 1,
 [2],
 'key-2' => [
 3,
 [
 'key-3' => [4, 5],
 ],
 ],
 ],
 6,
 'key-4' => [7, 8],
];

In these cases, you might want to use the internal standard library:

<?php
$merged = iterator_to_array(
 new RecursiveIteratorIterator(
 new RecursiveArrayIterator($lists)
 ),
 $use_keys = false
);
// $merged === [1, 2, 3, 4, 5, 6, 7, 8];

Which flattening approach to reach for #

Usually, being aware of how to flat a “2 level” array might be sufficient:

<?php
$flattenList = array_merge(...array_values($lists));

Otherwise, the internal standard library will help you deal with it.

References #

Typed Arrays in PHP

2020-10-13T00:00:00+00:00

Argument unpacking, function variable argument list, and variadics function.

The perfect combination #

Argument unpacking: Instead of passing the argument itself to the function, the elements it contains will be passed (as individual arguments).
Function variable argument list: The arguments will be passed into the given variable as an array.
Variadics function: Types can be checked with a type-hint.

We will use this snippet for our examples. Having a class, Customer:

<?php
/** 
 * @psalm-immutable 
 */
final class Customer
{
 // Using PHP 8 constructor property promotion
 // https://wiki.php.net/rfc/constructor_promotion
 public function __construct(
 public string $name,
 ) {}
}
// We create a list of 6 customers
$customers = array_map(
 fn(int $i): Customer => new Customer("name-{$i}"),
 range(1, 6)
);

Whenever we want to manipulate a list of Customers, we can pass as an argument: …$customers.

How we used to do it #

We define the array type using the PHPDoc param comment block above. But we cannot define the real type of the item. The code will still run without any problem passing any type on that argument array $customers:

<?php
/** 
 * @param Customer[] 
 */
function createInvoiceForCustomers(array $customers): void
{
 foreach ($customers as $customer) {
 // ... some irrelevant logic for this example
 }
}

The code below would work at “compile-time”. But it might fail at “runtime”.

<?php
createInvoiceForCustomers($customers);
createInvoiceForCustomers([new Customer('any name')]);
createInvoiceForCustomers([new AnyOtherType()]);

An alternative (recommended!) might be to extract that logic and ask for the particular type in order to “check it” at runtime in that particular moment, failing if one of the items wasn’t really a Customer:

<?php
/** 
 * @param Customer[] 
 */
function createInvoiceForCustomers(array $customers): void
{
 foreach ($customers as $customer) {
 createInvoice($customer);
 }
}
function createInvoice(Customer $customer): void
{
 // ... some irrelevant logic for this example
}

Everything here below would work at “compile-time”. It will for sure break during “runtime” if the createInvoice(Customer $customer) receives something different than a Customer.

<?php
createInvoiceForCustomers($customers);
createInvoiceForCustomers([new Customer('any name')]);
createInvoiceForCustomers([new AnyOtherType()]); // won't work

By doing that createInvoice(Customer $customer) we are ensuring the type of the argument, which is good! But, what about going one step further. Could we check the types of the elements when calling the function createInvoiceForCustomers(array $customers), even making the IDE complain when the types are not right?

Well, that’s actually what Generics are for, but sadly, they are not yet in PHP. Not even in the upcoming PHP 8. Hopefully in a near future, but we cannot predict that for now. Luckily, we have currently an alternative nowadays, but it’s not that popular. It has its own “pros” and “cons”, so let’s take a look at an example first:

<?php
function createInvoiceForCustomers(Customer ...$customers): void
{
 foreach ($customers as $customer) {
 createInvoice($customer);
 }
}

Everything here below would work at “compile-time”. It will for sure break during “runtime” if the createInvoice() receives something different than a Customer.

<?php
createInvoiceForCustomers(...$customers); // OK
createInvoiceForCustomers(
 new Customer('any name'), 
 new Customer('any name'),
); // OK
// This is not even possible to write. The IDE will yell at you. 
// It's expecting a `Customer`, but `AnyOtherType` is given:
createInvoiceForCustomers(new AnyOtherType());

PROS #

We can easily type a list of any concrete type.

CONS #

We better define our functions with one or two arguments max. Otherwise, it would be too complicated to read.

Important remarks #

It needs to be the last taken argument of a function.
It helps to minimize the number of arguments that we use in a function.

Variadics simulate typed arrays, use them wisely #

Argument unpacking is a great feature that, in combination with variadic functions, can help us to simulate typed arrays. With great power comes great responsibility, and this is no exception. We need to learn about our toolbox in order to use it wisely.

References #

Object design style guide

2020-10-10T00:00:00+00:00

Objects are the central concept of languages like Java, Python, C#. Applying best practices for object design means that your code will be easy to read, write, and maintain.

This book captures dozens of techniques for creating pro-quality OO code that can stand the test of time.

Examples are in an instantly-familiar pseudocode, teaching techniques you can apply to any OO language, from C++ to PHP.

Advanced Web Application Architecture

2020-08-16T00:00:00+00:00

This book helps you get your web applications back in shape. It contains many techniques for decoupling from infrastructure (like the framework or the database).

“The best guide that brings your coding and architecture skills a level up. All the modern PHP features combined with the elegance of a well-designed modular design.”

In Part 1 we unlock a collection of design patterns which help you establish a clean separation between core and infrastructure code. Part 2 shows how these design patterns resonate at a higher level with architectural concepts like layers, ports and adapters (a.k.a. Hexagonal architecture). The book finishes with a discussion of testing strategies and design trade-offs.

What you’ll learn #

Separating mixed code into core and infrastructure code by refactoring into patterns.
Dividing your code into layers, and making a clear distinction between an application’s ports and adapters.
Testing decoupled applications.

Buy the book: https://leanpub.com/web-application-architecture

Design patterns for modernizing legacy code bases #

Strict Types in PHP

2020-08-09T00:00:00+00:00

In December 2015, PHP 7 introduced scalar type declarations and with it the strict types flag. What is this new feature?

The good thing about declaring a PHP file as strict is that it actually applies to ONLY the current file. It ensures that this file has strict types, but it doesn’t apply to any other file in the whole project. It allows you to do, step by step, this migration from non-strict code to strict code, especially for new files or projects.

To enable the strict mode, a single declare directive must be placed at the top of the file. This means that the strictness of typing for scalars is configured on a per-file basis. This directive not only affects the type declarations of parameters, but also a function’s return type.

Strict types affect coercion types #

Using a type hint without strict_types may lead to subtle bugs.

Without this, int $x meant $x must have a value coercible to an int. Any value that could be coerced to an int would pass the hint type, including:

a proper int (example: 42 -> 42)
a float (example: 13.1459 -> 13)
a bool (example: true -> 1)
a null (example: null -> 0)
a string with leading digits (example: “15 Trees” -> 15)

By setting strict_types=1, you tell the engine that int $x means $x must only be an int proper, no type coercion allowed. You have the great assurance you’re getting exactly and only what was given, without any conversion or potential loss.

Who should care about this “strict type” line? #

Actually, declare(strict_types=1); is more for the reader than for the writer. Why? Because it will explicitly tell the reader:

The types in this current scope (file/class) are treated strictly.

‘strict_types=1’ is more for the reader than for the writer

The writer just needs to maintain such strictness while writing the expected behavior. That said, as a writer, you should care about your readers, which also includes your future self. Because you are going to be one of them.

References #

Final Classes in PHP | Java | Any

2020-06-06T00:00:00+00:00

Clear contracts, isolated side effects, testability, low complexity and cognitive load, code fluidity, and confidence in yourself.

Motivation #

Reduce the scope visibility to the minimum #

When you see a class prefixed with final you will prevent a particular class to be extended by any other, which not only makes it more readable but also makes you be sure that the scope of the logic where you are is limited to that particular class.

Encourage “composition over inheritance” mentality #

The Open-Close Principle states: open for extension but closed for modification.

If for any reason, a good one you should be completely aware of, you decide to create an inheritance there, well, then just drop the final keyword and you are good to go.

When you “by default” can’t extend from a class (because it’s final), you will help yourself by thinking about using composition instead of inheritance.

Why isn’t this class final? #

If we aim for composition over inheritance, then we should try to avoid inheritance as much as possible, and use it only when it’s really necessary. Inheritance is often misused in OOP.

Misconception #

When we first taught OOP, we usually introduced the classic inheritance example.

Nonetheless, when Alan Kay created Smalltalk, the inheritance was never the main concept of it. The main concept was messaging, which is that you can send messages to objects and they encapsulate the data and logic in it, and you can change their behavior by using different objects, which is actually composition. But the concept of inheritance is so popular that it eventually overshadows composition.

Benefits #

Clear contracts. Using interfaces will force you to think in terms of communication between objects.
Isolated, side effect free code units. Injecting interfaces only as dependencies will remove every nasty side effect around the code you are working on.
Testability. Mocking dependencies is extremely easy when they are interfaces.
Low, manageable complexity. Since everything is isolated, you won’t need to worry about rippling changes. This dramatically decreases the complexity of your code.
Low cognitive load. With decreased complexity, your brain will be free to focus on what matters.
Code fluidity. By removing any unnecessary coupling, you will be able to move things around way more easily than before.
Confidence in yourself. Being able to test your code in isolation so well will give you a wonderful sense of confidence in changing it.

Composition over inheritance #

If you feel the need to reconfigure an object, to change parts of an algorithm, or to rewrite part of the implementation, consider creating a new class instead of overriding an existing class. If you need to represent a hierarchy of classes, where subclasses are proper substitutes for their parent classes. This would be the classic situation where you may still consider inheritance. However, the result may even be better if you don’t inherit from concrete parent classes but from abstract interfaces.

What you should start doing instead #

Use interfaces to define the contracts between your classes.
Use final classes to implement behavior for those interfaces.
Use composition (using dependency injection through constructor) to put things together and prevent complexity.

Interfaces -> Final classes -> Composition

Symfony 5

2020-02-20T00:00:00+00:00

This book, written by Symfony’s creator, lays out a pragmatic approach to developing web applications with Symfony 5: from scratch to production. Whether you are discovering Symfony for the first time or refreshing your knowledge, this practical guide provides the definitive introduction to modern Symfony applications.