DEV Community: Andrej Rypo

Why I Built Migrun

Andrej Rypo — Sat, 28 Mar 2026 20:17:40 +0000

I mostly work with PHP projects that do not live inside a full framework like Laravel or Symfony — frameworks that come with their own ORM-based migration tools.
The existing standalone migration tools like Phinx, Phpmig, Phoenix are available, but they come with problems that kept bothering me over the years.
I would not even call Phinx standalone — it pulls in the Cake framework's core.

Service container integration is a hack. At least in Phinx, which I used the most.
If you use a dependency injection container (and you really should), wiring services into Phinx migrations is not possible.
People resort to global static access or other workarounds to get their own database connection or a service like logger into their migration.
This completely goes against modern DI practices.
I wanted migrations to simply declare their dependencies and have them resolved from the container automatically.

Query builders add complexity you don't need.
Migration systems often provide table builders — APIs for creating columns, indexes, and tables in a database-agnostic way.
Usually based on the particular framework ORM. In theory, this lets you switch databases without rewriting migrations. In practice:

Most projects never switch databases. None of the projects I've worked with ever did. They introduced new databases, but did not replace one with another.
When they do, they have to deal with database-specific features, data types, and behaviors anyway.
The builder APIs cannot cover every database-specific case. Like this classic problem in Laravel. Phinx is even more limited. You end up writing raw SQL for the tricky parts regardless.
The builder adds a layer of abstraction and complexity for something that a simple CREATE TABLE statement does just fine.

I am not saying builders are useless. But for many projects, they are unnecessary overhead.

All the tools use inheritance. Your migration class must extend an AbstractMigration base class. This means you are locked into a class hierarchy.
In modern PHP, we prefer composition and interfaces over inheritance. Inheritance-based designs are rigid and harder to integrate with your own architecture.

They all impose naming conventions and rigid directory structure upon the adopters. Archiving migrations after hundreds have accumulated? Not an option or PITA.

The standalone tools feel outdated. Migration tools in the PHP ecosystem have not evolved with the language.
PHP has readonly classes, enums, named arguments, union types, fibers, pipelines.
Meanwhile, migration tools still use patterns from the PHP 5 era.

Any sort of I/O integration is a hack.
Phinx only works within Symfony Console, and the runner is tightly coupled to it. Go and try to create an HTML page with the list of migrations, I dare you.

What I wanted

Something dead simple:

An interface for migrations. Implement up(), optionally down(). Done.
Autowiring from the service container. Declare PDO $db as a parameter and it gets resolved.
No base classes to extend.
No config files.
No bundled CLI. No Symfony console.
No query builder.
No file naming constraints.
Zero runtime dependencies. Not even utility packages. No Cake core.
Any database, any tech stack, any service container.

So I built Migrun.

Who it is for

Migrun is for developers who:

Work on PHP projects outside of Laravel or Doctrine ecosystems
Want a migration runner that fits into their existing architecture, not one that dictates it
Prefer writing SQL directly instead of learning a builder API
Use a service container and want their migrations to benefit from it naturally
Want something minimal and hackable, not a full framework

If you already use Laravel or Doctrine, their migration systems are deeply integrated and you should keep using them.
Migrun was not built to replace those — it was built for everyone else.

How it works

Return an anonymous class instance from a PHP file. Get all the parameters auto-resolved from your service container.

// 20260326_181000_a_migration.php
<?php

use Dakujem\Migrun\Migration;
use Psr\Log\LoggerInterface;
use PDO;

return new class implements Migration
{
    public function up(?PDO $db = null, ?LoggerInterface $logger = null): void {
        $db->exec(<<<SQL

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE
)

SQL);
        $logger->debug('Users table created.');
    }
};

Need a rollback? Don't like the heredoc syntax? No problem.

// 20260326_181002_reversible_migration.php
<?php

use Dakujem\Migrun\ReversibleMigration;
use PDO;

return new class implements ReversibleMigration
{
    public function up(?PDO $db = null): void {
        $db->exec('CREATE INDEX idx_users_email ON users (email)');
    }

    public function down(?PDO $db = null): void {
        $db->exec('DROP INDEX idx_users_email');
    }
};

You can also just return a closure:

// 20260326_181008_closure_migration.php
<?php

return function (\PDO $db): void {
    $db->exec(<<<SQL

CREATE INDEX idx_users_email ON users (email)

SQL);
};

You write the SQL on your terms. You run whatever services your app needs. Fully in control. No hacks.

Setting it up takes a few lines of code.

$migrun = new MigrunBuilder()
    ->directory(__DIR__ . '/migrations')
    ->container($container)    // any PSR-11 container for autowiring
    ->pdoStorage($container->get(PDO::class))
    ->build();

$migrun->run();          // run pending migrations
$migrun->rollback(1);    // roll back the last one
$migrun->status();       // see what's applied and what's pending

See the readme for fully functional CLI examples (like composer migrate:up),
or have AI tools set them up for you in a minute.
Symfony console is supported but not required (e.g. php bin/console db:migrate).

The architecture

Migrun is built around four straight-forward interfaces that

look for migrations
execute migrations
resolve migration dependencies
store migration history

Want to load pure SQL files? Implement a new "executor" (a single method) and a new "finder" (two methods).
Want to use a different DI container? Implement a single "invoker" method.
Want to store the history in Redis? Implement a new storage class.

No inheritance anywhere in the library. No static methods. No global state.

Give it a try.
It's in beta phase — your feedback may shape the release version.

Repository: github.com/dakujem/migrun
Install: composer require dakujem/migrun; or prompt "Install dakujem/migrun from Packagist using the recommended setup and add CLI scripts called via Composer."

Stop using jQuery?

Andrej Rypo — Wed, 25 Jun 2025 08:03:53 +0000

I bumped into this article that states jQuery can be replaced by native code: Why jQuery 4 is a good reminder to stop using jQuery
It implies that jQuery has no place in contemporary web development and that the new version serves no practical purpose.

It is indeed an interesting post.

Yet, I have to contra with three aspects the post leaves unmentioned:

Developer's time is expensive. A more concise or fluent API that saves development time makes sense even in the modern age.
DX: Looking at the examples how native JS can be used to replace jQuery, I still find the jQuery API more developer friendly. Like method call chaining, manipulating classes of multiple selected elements with a single call, etc.
Legacy apps.

Don't get me wrong, I wouldn't use jQuery in a greenfield JS app, but it has its place in the browser environment.

Modern JS apps tend to opt-in for libs like lodash instead of jQuery to polyfill the utility methods jQuery provides by default.
Some more backend-heavy apps that don't use full-fledged JS frameworks I've worked with recently opted for Alpine instead of jQuery for DOM manipulation.

Having worked with multiple legacy apps using jQuery as well as apps completely written in Vue or React, this is just my humble experience talking.

I actually welcome the new/more-modern jQuery version. Replacing jQuery in legacy apps would be pain, so a refreshed version might be a blessing in certain scenarios.

In years since JS frameworks like React, Angular or Vue became popular, jQuery seems to have earned the disdain of many developers — not because it stopped working, but because fashion moved on.

What do you think?

How to properly set up WAMP stack with multiple PHP versions in parallel

Andrej Rypo — Tue, 18 Mar 2025 09:56:35 +0000

Ever wondered how to get rid of WampServer, Xampp, EasyPHP and similar stuff?

In this article:

how to set up PHP, MySQL/MariaDB and Apache on your Windows dev machine (WAMP stack)
how to run multiple PHP versions on your dev machine without constant switching
how to set up vhosts and batch scripts to do so efficiently

💡

This post is for intermediate PHP developers or someone looking for this particular setup. Don't worry, if different
PHP versions mean nothing to you, or you are not sure what a server is,
it's perfectly okay, just bookmark this post and come back later.

Over the years of my beginnings, I used several tools like WampServer, XAMPP or EasyPHP for PHP development. I quickly realised that these tools had one common disadvantage: Slow release cycle and limited flexibility.

They allowed me to switch PHP versions, but did not allow for multiple PHP versions simultaneously, so I had to constantly switch versions when switching projects (at the time, I would work on several projects for different clients, different servers etc.).

As an example, at time of writing this, XAMPP only comes bundled with PHP 8.2, while 8.4 has been out for a few months already.

So what does a developer do when they want to or have to use recent PHP versions?

A sidenote:
This is not about Docker.

Yes, Docker with WSL is a way to go to have the best flexibility, but the setup is more complicated, and there are performance issues that may be circumvented, with drawbacks.
Also, if you are on a Unix compatible platform, just use Docker.

WAMP stack

It comes down to installing and configuring 3 essential components that "WAMP" stack is composed of:

Apache server (using vhosts)
MySQL / MariaDB database
PHP
P.S., W stands for Windows, hence "WAMP"

It is possible to install multiple versions of PHP on a single Windows development machine. A single MySQL or MariaDB version was all I ever needed, but it should be no problem to run different versions in parallel on different ports, if needed be. I'm not sure about installing multiple Apache versions, I never needed those, but then again, it should be possible, serving on different ports.

Setup & Installation

I like to create a dir dedicated to my dev tools, like C:\dev.
I will be referring to it as such, or just "the install dir".
Then I keep the projects in a separate dir, let's call it C:\projects or "the projects dir".

Actually, I keep the projects on a separate encrypted drive, but that's out of scope of this article.

Stick to the x64 versions of software if your machine is x64 (it will most probably be the case). Do not mix x64 with x32 as some combinations might not work.

The trick to using several versions is in two parts:

configuring vhosts for each project (specifying the FCGIWrapper directive with PHP version of choice)
setting alias batch commands (.bat files) to invoke different PHP (and composer) executables, e.g. php84, php82, php74, composer@84, etc.

PHP

Download PHP Windows binaries of your choice. Pick the latest version, if possible.

You will spot two types of builds: Thread safe (a.k.a. TS or ZTS) and Non thread safe (a.k.a. NTS). Without going into details now, we will be using a setup where the NTS version should perform better so pick an NTS version.

💡

Note that with a "typical" Apache+PHP setup with mod_php, like on XAMPP, you would have to pick the thread safe (ZTS) version to prevent concurrency issues.

Unpack the contents in your install dir, be sure to create a subdir for each major PHP version, like php84, php82, php74 and so on. This is to ensure multiple versions may coexist alongside each other.
Your path to PHP should look something like this C:\dev\php\php84.

To configure PHP, locate the php.ini file. If it is not present, look for php.ini-development, make a copy and rename it to php.ini.

I will leave the actual configuration up to you. But I do recommend tweaking values that do not suite you later on.

You can test or verify the configuration by calling php -v to see the version, php -m to see the installed modules or php -i to see all the configuration, which is verbose. Look out for any error/warning messages printed by PHP.

To test the web interface, create a simple script info.php and place the call to phpinfo there.

<?php phpinfo();

Then, visit it in the browser throught the particular domain (see vhosts below). You should see something like this:

HTTPS (curl, OpenSSL)

To be able to run HTTPS requests from PHP correctly, visit CA certificates extracted from Mozilla site and download cacert.pem file. Place it anywhere into your install dir.

Be sure to include it in your php.ini file (update the existing values):

[curl]
curl.cainfo = "C:/dev/cacert.pem"

[openssl]
openssl.cafile= "C:/dev/cacert.pem"

Xdebug

Visit Xdebug downloads and pick appropriate version. Take care to select the right PHP version + x64 + NTS variant combination.

Unpack the zip file - you will only need the php_xdebug-3.4xxxxx.dll file. Place the dll into your php's ext directory.

Include or modify the Xdebug section in your php.ini.

✋ Take great care here to specify the zend_extension without the php_ prefix and the .dll suffix, otherwise the module will not load. The actual value here depends on the file name you place in the ext dir.

[Xdebug]
zend_extension=xdebug-3.4.1-8.4-nts-vs17-x86_64

; Debug enables step debugging, develop has better performance.
; https://xdebug.org/docs/all_settings#mode
xdebug.mode=debug

You may rename the file to just php_xdebug.dll and use zend_extension=xdebug in the ini file, but I recommend keeping the original file name. If you decide to rename it, you must keep the php_ prefix in the filename or the module will not load.

Once configured correctly, typing php -v in the terminal should validate correct configuration with Xdebug.
If there are any issues, PHP will print them out.

Updating

To update a PHP version, just download the new version and overwrite the installation folder contents. This will keep any extensions you added (like Xdebug) as well as the config file (php.ini) intact.

Apache server

Apache web server is software that listens for HTTP requests from clients (i.e. the browsers), processes these requests by invoking a PHP interpreter service and sends the resulting response back to the user.

We will use module called FastCGI (mod_fcgid) with NTS PHP versions.

Visit Apache Lounge download page and

Download Apache 2.4 x64
also grab the FastCGI module (mod_fcgid)

Unpack the contents into your install dir, e.g. C:\dev\Apache24, and place the mod_fcgid in the \modules subdir, e.g. C:\dev\Apache24\modules.

Be sure to enable the module in httpd.conf located in C:\dev\Apache24\conf:

LoadModule fcgid_module modules/mod_fcgid.so

I usually separate my per-project Apache configuration in a few config files located in the project dir, which can be included from httpd.conf using a line like this (placed at the end I suppose):

IncludeOptional "R:\httpd-include.conf"

This is my current DEV configuration, tweak it to whatever suits you, or do not include it at all to use the defaults. I used this configuration when experimenting with SSE (server-sent events), but then I completely forgot about it. It might be an overkill.

<IfModule fcgid_module>
    FcgidIOTimeout 600
    FcgidConnectTimeout 16
    FcgidBusyTimeout 600
    FcgidMaxRequestsPerProcess 500
    FcgidMaxProcesses 50
    # 4G = 4294967296
    FcgidMaxRequestLen 4294967296

    # for experiments with SSE / streaming
    FcgidOutputBufferSize 0
</IfModule>

Apache will install as a service. You may want configure it to not start automatically and start it manually (hit Start button and type in "services"). It is possible to use "apache monitor" that comes bundled with the server. This app enables to start/stop and monitor Apache from taskbar.

However, I'm using a small script to start/stop Apache, database and Garnet with a single command. More on this later.

The configuration of Apache server can be tested calling apache with -t parameter: httpd.exe -t.

Vhosts (virtual hosts)

A "vhost" (abbreviation of "virtual host") is an isolated configuration listening for requests on a certain interface / domain.

I place the vhost configurations into the R:\httpd-include.conf Apache config file included from the main config file. I'm using several such included files in fact. This is up to you to organize.

I'm using a separate vhost and domain for each project I'm working on for the flexibility, form prefill and other benefits.

This is what a simple such configuration template may look like:

<VirtualHost *:80>
    ServerName your-project.lo
    DocumentRoot "R:/your-project"
    <directory "R:/your-project">
        Options +ExecCGI +Indexes +FollowSymLinks
        AddHandler fcgid-script .php
        FCGIWrapper "C:/dev/php/php84/php-cgi.exe -c C:/dev/php/php84/php.ini" .php
        CGIPassAuth on
        AllowOverride all
        Require all granted
    </directory>
</VirtualHost>

👉 To swap PHP version, all that needs to change is the FCGIWrapper directive. 👈

The vhost is set up once, though, there is no need to switch anything afterwards.

Depending on your configuration, multiple vhosts with different PHP versions may point to the same directory (if switching git branches is the way you work when upgrading).

I'm using .lo as TLD, but I've seen .loc and .local too. You may experiment here.

You may also define a server alias, like www.your-project.lo adding
ServerAlias www.your-project.lo to the configuration.

I'm using this as a template to create other vhosts, it is also possible to automate such creation, but it's not much of a hassle anyway.

Hosts file

You may have already checked that visiting your-project.lo in the browser probably sends you to your search engine.

Your computer does not recognize the domain and looks for the IP address using DNS, which fails for .lo TLD and you end up defaulting to search engine.

To overcome this, edit the hosts file in your system. This file is always checked before any DNS requests are issued.

The file is located here:

C:\Windows\system32\drivers\etc\hosts

The file can be used for other stuff, but here we will only direct our development domains to the localhost like this:

#
# My projects
#
  127.0.0.1      your-project.lo
  127.0.0.1      adminer.lo next.adminer.lo
#...

This will tell the system to direct all network traffic going to your-project.lo, adminer.lo and next.adminer.lo to your own localhost. Apache will take it from there.

Save this file and you are ready to go. After visiting your project domain in the browser, you should see it being rendered.

The file may be read-only or system-protected, so look for write errors when you save it.

Note that to edit the hosts file you will probably need to open it with administrator privileges, if you get errors when saving the modifications of the file. alternatively, you may try the Microsoft PowerToys that come with a hostfile editor and a bunch of other more or less useful stuff.

Vhost with HTTPS example

Here, I will set up domains adminer.lo and next.adminer.lo for local development with HTTPS redirect.

I believe that to use HTTPS you would have to generate your own self-signed certificate. I did this long time ago and have not documented how, so I'll leave this for you to experiment with. Or use your favourite AI for suggestions.

This is the vhost conf for adminer.lo which runs on legacy PHP 7.4:

<VirtualHost *:80>
    ServerName adminer.lo
    Redirect / https://adminer.lo/
</VirtualHost>
<VirtualHost 127.0.0.1:443>
    ServerName adminer.lo
    DocumentRoot "R:/adminer"
    ErrorLog "R:/adminer/error.log"
    <directory "R:/adminer">
        Options +ExecCGI +Indexes +FollowSymLinks
        AddHandler fcgid-script .php
        FCGIWrapper "C:/dev/php/php74/php-cgi.exe -c C:/dev/php/php74/php.ini" .php
        CGIPassAuth on
        AllowOverride all
        Require all granted
    </directory>
    SSLEngine on
    SSLCertificateFile ${SRVROOT}/conf/server.crt
    SSLCertificateKeyFile ${SRVROOT}/conf/server.key
</VirtualHost>

And this is the vhost for running my updated Adminer fork:

<VirtualHost *:80>
    ServerName next.adminer.lo
    Redirect / https://next.adminer.lo/
</VirtualHost>
<VirtualHost 127.0.0.1:443>
    ServerName next.adminer.lo
    DocumentRoot "R:/adminer-next"
    ErrorLog "R:/adminer-next/error.log"
    <directory "R:/adminer-next">
        Options +ExecCGI +Indexes +FollowSymLinks
        AddHandler fcgid-script .php
        FCGIWrapper "C:/dev/php/php84/php-cgi.exe -c C:/dev/php/php84/php.ini" .php
        CGIPassAuth on
        AllowOverride all
        Require all granted
    </directory>
    SSLEngine on
    SSLCertificateFile ${SRVROOT}/conf/server.crt
    SSLCertificateKeyFile ${SRVROOT}/conf/server.key
</VirtualHost>

Whenever I visit https://adminer.lo/ in the browser, PHP 7.4 will serve this request;
but whenever I visit https://next.adminer.lo/, PHP 8.4 will serve that request.

I do not need to switch anything and I am able to work on both in parallel.

Dedicated document roots for different PHP versions

Above, I'm showing how I configure a vhost/domain for each project.
If you'd rather use a single vhost for a PHP version, that is also possible. You may choose to use domains like php84.lo and php82.lo or use different ports to direct traffic to the right vhost, and only create a single vhost for each PHP version.

Your projects wil then be accessible via https://php84.lo or http://localhost:8084, this is up ot you to experiment with.

Note that 80 is the default HTTP port and 443 is the default HTTPS port, though 8080 is commonly used for dev servers (e.g. Vue.js).

MariaDB / MySQL

It should not really matter whether you use MySQL or MariaDB in most cases. There are (minor) differences though, so pick the one that your clients use in production. Or install both.

Visit the MariaDB download page and pick a version. I recommend a "long-term support" version. At time of writing, this would be 11.4.

Install the database into C:\dev\MariaDB. I also create a separate dir for the actual database data, e.g. C:\dev\MariaDB_data.

My my.ini located in the MariaDB_data folder looks like this:

[mysqld]
datadir=C:/dev/local/MariaDB_data
port=3306
character-set-server=utf8mb4
innodb_buffer_pool_size=8G
max_heap_table_size=1G
[client]
port=3306
plugin-dir=C:/dev/MariaDB/lib/plugin

I prefer to setup utf8mb4 as the default charset and increase memory allowances for smooth operation. I'm not sure what the [client] section is for though.

For database management, I use Adminer, which is minimalist, but provides all the convinience I need. You may consider phpMyAdmin or HeidiSQL or something similar.

If you need to install multiple versions, or both MySQL and MariaDB, adjust the ports so that each listens on a different port. This will have to be reflected in your application.

As with Apache, you may want to validate the configuration calling mysqld with the --validate-config parameter.

Working with multiple PHP versions in parallel

Now to the scripting part. There are no vhosts in CLI, so if you open your terminal (CMD, command line) and type in php -v you will get whichever PHP you installed as default, if any.

The trick is to create a directory (which I will call the "bin" directory) in C:/dev/bin and include it in the PATH system variable. Here we will place our .bat batch command files.

Go to "Edit system environment variables" and edit the PATH variable so that it includes this directory. Windows will pick the first binary in the order which the folders appear in the PATH variable, so place the C:/dev/bin part appropriately.

Start a new terminal and type echo %PATH% ... it should be visible there (one must reopen the terminal after changing the PATH variable).

In this bin directory, I create files like php84.bat for each PHP version. I also create com84.bat for composer running with PHP 8.4 and any other version. This way I am able to invoke PHP binaries selectively.

@echo off

REM PHP 8.4

REM   %* passes all the input arguments to the PHP call
"C:/dev/php/php84/php.exe" %*

@echo off
REM    Composer running using PHP 8.4

REM   %* passes all the input arguments to the PHP call
php84 "C:\dev\composer\composer.phar" %*

I am then able to invoke php84 for PHP v8.4 and com84 for Composer running on PHP 8.4. I create such a shortcut for each version I install and have one PHP version as the default for php and com/composer.

Composer scripts

Normally, if you specify a script that runs PHP or other Composer command in composer.json like the following, you will see the script is invoked using the default php/composer binary and not the one you run the command with.

{
  "scripts": {
    "cache:warmup": [
      "php bin/cache-warmup.php"
    ],
    "cache:purge": [
      "php bin/cache-purge.php"
    ],
    "cache:test": [
      "composer cache:warmup",
      "composer cache:purge"
    ]
  }
}

See the issue here:

{
  "scripts": {
    "check": [
      "php -v"
    ]
  }
}

This script should print out the correct php version, but it prints the default system php version every time, which is not what we intended:

The trick is to use @php and @composer in the JSON file, that tells composer to "use the same PHP binary as it was invoked by":

{
  "scripts": {
    "check": [
      "@php -v"
    ]
  }
}

As a rule of thumb, always specify your scripts as @php and @composer:

{
  "scripts": {
    "cache:warmup": [
      "@php bin/cache-warmup.php"
    ],
    "cache:purge": [
      "@php bin/cache-purge.php"
    ],
    "cache:test": [
      "@composer cache:warmup",
      "@composer cache:purge"
    ]
  }
}

Built-in server

Assuming your project uses a /public dir as the document root, you may also just run the built-in PHP server, but keep in mind that it is not intended for serving static files (images, CSS, JS).

In the terminal, run

php -S 127.0.0.1:42300 -t public/

I'm using this kind of composer.json structure, then I call it as composer serve in the project directory:

{
  "scripts": {
    "serve": [
      "Composer\\Config::disableProcessTimeout",
      "@php -S 127.0.0.1:42300 -t public/"
    ]
  },
  "scripts-descriptions": {
    "serve": "Run a lightweight PHP server"
  }
}

Remember, you are in control of which PHP version you run the script with. Be it com84 serve or com82 serve.

Other useful scripts

A script to start Apache server (with PHP module), MariaDB database and Garnet for cache - amp-on.bat:

@echo off

REM Start Apache, MariaDB and Garnet
sc start ApacheHTTPServer
sc start MariaDB
sc start GarnetServer

... and amp-off script containing sc stop for stopping the services as well.

Then a script for restarting Apache. This one is more advanced and waits for the service to stop and start:

@echo off

REM REstart Apache
set "ServiceName=ApacheHTTPServer"

REM Stop the service
echo Service %ServiceName% is shutting down.
sc stop %ServiceName%

REM Wait for the service to stop
:LOOP
timeout /t 2 /nobreak >nul
sc query %ServiceName% | find "STATE" | find "STOPPED" >nul
if %errorlevel% equ 0 (
    goto START_SERVICE
) else (
    goto LOOP
)

:START_SERVICE
REM Start the service
echo.
echo Service %ServiceName% is starting.
sc start %ServiceName%

REM Wait for the service to start
:WAIT_START
timeout /t 2 /nobreak >nul
sc query %ServiceName% | find "STATE" | find "RUNNING" >nul
if %errorlevel% equ 0 (
    goto SHOW_MESSAGE
) else (
    goto WAIT_START
)

:SHOW_MESSAGE
echo.
echo Service %ServiceName% is now running.

Takeaways

It is not a short setup, but it pays off in the long run. Installing further PHP versions is just about creating a couple of files and folders and copy-pasting the php.ini, sometimes tweaking a value here and there. Updating is a breeze.

You will benefit from efficient and flexible Windows setup.

No more waiting for third party bundlers to realease a new version!

Tree traversal and merging with Generators

Andrej Rypo — Sun, 11 Feb 2024 16:01:32 +0000

Tree traversal

Recently I reimplemented my old library for tree structure handling.

It turns out that generators along with recursion are a very efficient and concise way to traverse tree structures.

Below, the two depth-first traversals (pre-order, post-order) are implemented by 3 lines of code, and the breadth-first level-order traversal by 5.

final class Traversal
{
    public static function preOrder(TreeNodeContract $node): Generator
    {
        // First, yield the current node,
        // then do the same for all the children.
        yield $node;
        foreach ($node->children() as $child) {
            yield from self::preOrder($child);
        }
    }

    public static function postOrder(TreeNodeContract $node): Generator
    {
        // Yield the current node last,
        // after recursively calling this for all it's children.
        foreach ($node->children() as $child) {
            yield from self::postOrder($child);
        }
        yield $node;
    }

    public static function levelOrder(TreeNodeContract $node): Generator
    {
        // In BFS traversal a queue has to be used instead of recursion.
        $queue = [$node];

        // The first node in the queue is taken and yielded,
        // then all of its children are added to the queue.
        // The next iterations will continue with the node's children, while adding their children to the queue,
        // until there are no more nodes to traverse.
        while ($node = array_shift($queue)) {
            yield $node;
            foreach ($node->children() as $child) {
                $queue[] = $child;
            }
        }
    }
}

💡

You can tell a generator by the yield keyword. In fact, every method or function that yield appears in automatically returns a generator. A generator is a special type of single-use iterator. In simple terms, it is best used with foreach.

Wikipedia will tell you more about DFS and BFS tree traversals.
Try to compare the code complexity using stacks to implement the same.

If you are interested in tree structures in PHP, see the library dakujem/oliva, it may help you speed up your work.

dakujem / oliva

Flexible tree structures, materialized path trees, tree iterators.

Generators for merging arrays and iterators

In my opinion, generators are one of the lesser known and underrated features of PHP, albeit with narrow field of use, but very useful in some specific cases.

See how this simple function "chains" multiple iterables? That means any arrays or iterators in one bag.
And it's efficient, it does not actually merge anything, it merely enables iteration over every element of whatever the input is.

function chained(iterable ...$input): Generator
{
    foreach ($input as $iterable) {
        yield from $iterable;
    }
}

From now on, if you need to iterate over multiple arrays, no need to use array_merge (which would merge the arrays, increasing memory usage and possibly slowing down the code).

foreach(chained($array1, $array2, $array3) as $key => $value){
    // ...
}

However, take care that the keys may overlap - a single key may appear multiple times for different values and is thus not unique. That would be problematic if you used iterator_to_array.

foreach(chained(
    [1,2,3],
    [4,5],
) as $item){
    echo "$item ";
}

The above results in the expected sequence of numbers 1 2 3 4 5 being printed.
However, the below code does not print what's naturally expected:

$numbers = chained(
    [1,2,3],
    [4,5],
);
print_r(iterator_to_array($numbers));

The output is

Array
(
    [0] => 4
    [1] => 5
    [2] => 3
)

This is because the indexes in the input arrays overlap and are overwritten when calling iterator_to_array.

This one works as expected again, as there are no overlapping indexes:

$numbers = chained(
    [1,2,3],
    [10 => 4,5],
);
print_r(
    iterator_to_array($numbers)
);

Explore this 3v4l to see the code in action.

The bottomline is this:
We do not use generators for chaining if all we need is to create a merged array, but we may benefit from generators when we need to efficiently iterate over chained arrays or other iterable collections.

By the way, I've written a bit about generators before in Anonymous Generator in PHP.

Swiftmailer on PHP 8.2

Andrej Rypo — Tue, 06 Jun 2023 18:50:25 +0000

One of the essential requirements for software to be maintained is the ability to upgrade the internals, hardware, operating system etc. to the latest possible versions. Long-term.

Lately, I've been working on a few legacy apps that needed new life breathed into them. Some ran 7.4, some even older versions of PHP.

One of external dependencies that these apps had in common was now long abandoned Swiftmailer by Symfony.

The original Swiftmailer runs on PHP versions up to 8.1, and no later. PHP 8.1 will be end-of-life by the end of 2024.

For some reason I've had trouble finding a fork that would reliably support PHP 8.2.

Without further ado, here is a Swiftmailer fork that can be run without any deprecation warnings on PHP 8.2:

viaaurea / swiftmailer-legacy

Comprehensive mailing tools for PHP with recent PHP support

Swift Mailer Legacy

This is a fork of legacy swiftmailer/swiftmailer updated to run on PHP 8.2 and possibly future versions without any deprecation warnings or compatibility issues, maintained by Via Aurea.

Installation:

composer require viaaurea/swiftmailer-legacy -W

Legacy port development notes here.

Swift Mailer

The original Swiftmailer stopped being maintained at the end of November 2021.

Please, move to Symfony Mailer at your earliest convenience. Symfony Mailer is the next evolution of Swiftmailer. It provides the same features with support for modern PHP code and support for third-party providers.

Swift Mailer is a component based mailing solution for PHP. It is released under the MIT license.

Swift Mailer is highly object-oriented by design and lends itself to use in complex web application with a great deal of flexibility.

For full details on usage, read the documentation.

View on GitHub

All anyone willing to upgrade to PHP 8.2 has to do is type



composer require viaaurea/swiftmailer-legacy -W

This will replace the original package without breaking requirements by other packages that rely on Swiftmailer being installed.

The fork is a fully compatible drop-in replacement of the original Swiftmailer with minimal code changes to support PHP 8.2.

From Singleton to Facade

Andrej Rypo — Tue, 11 Oct 2022 08:23:22 +0000

Some have heard that singletons are evil. They are. Don't use them.

TL;DR And don't use facades either, if you don't have to.

Towards better tomorrow

"But singletons are so easy to use!" 👴

// Singleton
class SomeService
{
    public static function getInstance(): self {
        if (self::$instance === null) {
            self::$instance = new static();
        }
        return self::$instance;
    }
}

It is also simple to retain the utility of singletons and still use dependency injection, to a degree.
It's not perfect, but it's a nice compromise for the imperfect world.

There is only one difference between a singleton and a facade, and it's the explicit binding of the instance:
An explicit binding call must occur prior to using a facade.

// Facade
class SomeService
{
    public static function getInstance(): self {
        if (self::$instance === null) {
            throw new LogicException();
        }
        return self::$instance;
    }

    public static function bind(?self $instance): void
    {
        self::$instance = $instance;
    }
}

The binding is usually done during the bootstrap phase of an application, using the app's service container.

// Bootstrap the service container somehow...
$container = $bootstrap->container();

// Then bind the facade
SomeService::bind($container->get(SomeService::class));

Now both the injection via the service container will work as well as using the facade directly.

This way, a legacy app may be refactored so that the legacy code remains functional, but dependency injection is introduced to the newer parts.

An example of using an interface

When implementing a facade, interfaces should always be used for the instances being bound. This will allow swapping the implementations behind them.

final class EventBus
{
    private static ?EventDispatcherInterface $instance = null;

    public static function fire(EventInterface $event): void
    {
        if (self::$instance === null) {
            throw new LogicException('The facade has not been bound to an instance.');
        }
        self::$instance->dispatch($event);
    }

    public static function bind(?EventDispatcherInterface $instance, bool $force = false): void
    {
        if (!$force && self::$instance !== null) {
            throw new LogicException(...);
        }
        self::$instance = $instance;
    }
}

Configure it during app's startup

$container = ...;
EventBus::bind($container->get(EventDispatcherInterface::class));

Now, both DI and the facade can coexist:

$event = new SomeEvent(...);

$dispatcher = $container->get(EventDispatcherInterface::class);
$dispatcher->dispatch($event);

EventBus::fire($event);

You may ask why the $force parameter of the EventBus::bind method. For practical purposes: You will want to test your facades and to do so, rebind them.

I also suggest throwing an explanatory exception when attempting to bind the facade that has already been bound, like this one:

throw new LogicException(sprintf(
    'The facade has already been bound.' . ' ' .
    'This error might imply design flaws.' . ' ' .
    'Consider injecting an %s implementation instead of using a facade.',
    EventDispatcherInterface::class,
));

Are singletons the root of all evil?

Dont' get the wrong idea. You should NOT use facades just to allow global access to services. You still want to employ dependency injection and inversion of control (IoC) principles.

Facades build upon the very same bad idea of global access that drives singletons.

On the other hand, there are cases where they might be practical (e.g. logging).

And then there are legacy apps that come with singletons already in place.
Or legacy apps from the dark age that use no means of dependency injection at all.

Implementing facades and utilizing a DI container might be a great step forward in those situations.

What is wrong with singletons then?

Tight couplings. Well, all static calls and new operator uses create tight couplings.

Tightly coupled code is harder to extend and harder to maintain, because implementations that have gotten deprecated can not be swapped for new ones. Tightly coupled code is harder to test, because big parts of the code needs to be mocked.

When working with a facade that binds to an instance through an interface, the implementation behind the facade is allowed to change without modifications to the calling code.
This alleviates the problem somewhat.

Why do singletons even exist?

The singleton pattern solved an even greater evil of the dark ages - global variables. Singletons at least are immutable, while global variables may change on a whim.
Singletons are a part of programming history and as such deserve respect. There is no place for them in a modern code, however.

Takeaway

Facades are not the clean solution that makes us happy and comfortable at the same time. But they are a better option than singletons.
Especially in legacy apps where they provide compatibility with existing code while also paving a path towards brighter future.

The pitfalls of using traits

Andrej Rypo — Mon, 10 Oct 2022 19:32:00 +0000

When traits came to PHP, I'm sure many (myself included) thought they were a viable solution for code reuse. They offered ways to reduce code verbosity. They were easy to grasp. Suddenly we needed not to duplicate code across unrelated classes. 🤩 However, many (myself included) sobered after a hard lesson...

What are traits in PHP

In simple terms, a trait is a piece of code that gets copy-pasted into a class using it.
You can read what the PHP Manual says about traits if you are not familiar with them.

Traits came to my rescue

I had a bunch of classes that all needed the same: a Logger, a Connection and a Serializer instances (there were some other, it was about 6-8 such services IIRC). The constructors were bloated, there were ~50 lines of code just to assign these services to private props through a constructor, same comments, same everything, in every one of these classes...

With every query I would have to type $this->connection->table('foo')->select(...) and then $this->serializer->serialize($result) and whenever something needed logging $this->logger->log(stuff).

Thinking of introducing base classes, are we? But my target classes were not all related, it would not have solved the issue, and, worse, base classes stink.

So I experimented with "bundles"... I would inject a single class to the constructors, but then needed to type this kind of code $this->bundle->logger->log(stuff) 🤦‍♂️.

Instead, I discovered with traits I could type just $this->log(stuff), $this->select(...) or $this->serialize($result).

It was easy to write a trait with those methods, like this

protected function select(...$args) {
    return $this->connection
        ->use($this->database)
        ->table($this->table)
        ->select(...$args);
}

public function injectConnection(Connection $c){
    $this->connection = $c;
}

There was some magic calling the setter automagically on startup.

I could even combine multiple such traits to create shortcuts to several services.

A perfect solution.
Except...

Except...

So... How do you test a trait? Well, you don't! You can't instantiate it, you test a class that uses the trait.
How do you know a class is using a trait, so that you can test it? Well, you don't¹!
See the problem?

Except...

What about dependencies? You create a fancy class with half a dozen traits and as many services that you need to inject, somehow, and you end up with boilerplate code nevertheless.
Worse, you create hidden dependences. And wait for the moment you start combining traits into supertraits.

Takeaway

Think twice before creating and/or using a trait. I dare say, in most cases, if you need a trait, something in the class design has to smell.

Remember that using a trait is just copy-pasting code that could otherwise sit in a proper class.

Use class composition instead of traits. Use DI containers with autowiring capabilities to reduce boilerplate. Understand that typing a couple of characters extra is cheaper than dealing with tangled dependencies and trait conflicts.
In fact, those "bundles" I mentioned earlier, if executed correctly², are the way to go in many cases.

Traits are a valid language construct, though. Do use them where applicable. Make a conscious choice and be content with it.

Unless you inspect the source or use reflection. ↩
Yes, I mean interfaces. ↩

Fullstack web development in the twenties

Andrej Rypo — Mon, 10 Oct 2022 18:50:45 +0000

I am a fullstack web developer.

Well, used to be. Back when I started, it was enough to know PHP reasonably, then a bit of HTML (v4), CSS (v2), and some MySQL. The complexities of HTTP were well hidden by the MVC framework I was using at the time (Nette), SVN was as easy as update, add, and commit and there was this shell script that ~~deployed~~ copied files from the repo to the vhost dir. This was enough to be productive and make something that generated profit.

You needed to decide whether to switch from the three column 768px layout to the trendy 1024px width two column layout. Fixed-width, obviously.
To be on the cutting edge and provide "interactive pages"¹ you used jQuery, and partial page update utilising AJAX.

Your greatest enemy was the IE 6.

Nowdays? Well...

Everyone ~~wants interactive pages~~ expects interactive web apps now.
To provide, you need to grasp a JavaScript/ES interactive tech like React, Vue, Angular. Or all of them. You need state management, event handling, routing ... you are basically building an application with almost everything that desktop apps need in place. It's nothing like "web pages" 10 years ago. And the JS eco is crazy. You can code in several syntaxes, then transpile, preprocess, bundle, postprocess.

Responsiveness. You need to understand a CSS framework like Tailwind, Bootstrap, Bulma, Material. Or all of them. Pick the proper one. They come with Scss or Post CSS to master too. Your apps should look good on 2 inch wide phone noodle-screens with holes in them and corners eaten by mice, 32" 4k desktops and 80" TV screens alike.

As a fullstack developer, you need to understand search engine optimization and optimize page load speeds. You did need to optimize in the past, but it was relatively simple because most of the heavy code was server-side.

Once you have a shiny single page app drafted, you need to teach it to talk to your backend. Here you deal with the complexities of HTTP protocol, RESTful APIs or the overestimated GraphQL. On both sides.

Almost forgot about databases! While relational SQL ones have not changed so much in principle, you now have a ton of NoSQL flavors and you should at least understand when to use or not use one.

Once you have written a piece of code, you need to understand Git. And GitHub, GitLab, BitBucket or whatever your teams use (merge requests, pull requests, you name it). Git is awesome. But it is fundamentally more complex too, being decentralized. It's not just the commands, it's branching strategies, rebasing, merging...

And then you need to deploy the code. Everything is in the cloud², you need specialized tools to deploy your work. No longer is FTP enough. CI/CD, Docker containers, lambdas, buckets. You need to fiddle with that too.
You need to set many of these things up before you even showcase a working draft.
They call it DevOops for some reason. I've had most experience with the Oops part so far.

As a fullstack developer, you, my reader, you are expected to master all of that.
Sure.

...

Who are the mythical fullstack developers these days anyway?

I would estimate the number of tech and tools I regularly use for development has doubled over the last few years, and it only seems to be gaining momentum. I wonder what my dev routines will look like by the end of this decade.

I'm not offering any solution here. I just wanted to put these thoughts on paper. So that I can laugh when I stumble on this article in 10 years or so.

the term "UX" probably did not exist at the time ↩
just somebody else's computers, really ↩

php 8 fun

Andrej Rypo — Wed, 18 Aug 2021 11:25:14 +0000

From all of the breaking changes introduced in PHP 8 I think the change to the comparison operator is the most intricate one:

// To be `true` or not to be? That is the question.
'' == 0
'' === 0
'0' == 0
'💩' == 0
'0foo' == 0

See the difference of evaluation in PHP 7 and PHP 8 here:
👉 https://3v4l.org/farC0

I just don't understand how it's possible that I have not encountered a bug because of it yet.

Hopefully, no sensible person is using the equality == operator.

i18n, l10n, g11n, a11y, W1F

Andrej Rypo — Fri, 25 Dec 2020 21:18:21 +0000

Seriously? How does this make anything more legible? Are we trading keyboard hits for legibility? I would understand i18n, as internationalization really is a difficult word to type. But how often do we type this, honestly? And the rest? Saving 8-9 key hits? W1F¹ is wrong with just typing the word?

Instead, why don't we settle on actual words that are inclusive and easy(-ier) to type?

I just wish that one day we are able to use

unity
harmony
world
inclusion
everyone

... or something like that.

It seems to me like a race to find a new [a-z][1-9][0-9]?[a-z] match. Or is the higher the number the better?

I5e² I wrote the w3e³ p2t⁴ like this. Who would r2d⁵ it?

what the ferret ↩
imagine ↩
whole ↩
post ↩
read ↩

Recursion in PHP

Andrej Rypo — Sun, 29 Nov 2020 13:59:10 +0000

Chapter 1: Tail Recursion

If we want to understand tail recursion,
we need to read Chapter 1: Tail Recursion.

Chapter 2: Head Recursion

PHP means PHP: Hypertext Preprocessor.

Anonymous Generator in PHP

Andrej Rypo — Sat, 28 Nov 2020 16:37:26 +0000

Recently, I wanted to create an anonymous generator. The good news is that it is possible, the syntax is not the most obvious one, though.
You need to use a technique called "immediately invoked function expression" mostly known from JavaScript of the jQuery era.

Here it is:

$iterable = (function (): Generator {
  yield 42; // yield any number of values
})();

Explanation:

the anonymous function itself is not a generator, it's just a callable and can not be iterated over
the function is invoked immediately after it is created and must be enclosed in parentheses (function(){ ... })() if we want to invoke it right away
the invocation results in a Generator, which can be iterated over

$func = function(): Generator { yield 42; };
$iterable = $func(); // this is when the generator is created

foreach($func as $item){ }     // error, $foo is not iterable
foreach($iterable as $item){ } // iterates over the generator

Generators have been in PHP since version 5.5. I have since used them rarely, but they are good for solving some edge cases, like generating a sequence of unknown length.

A generator can be used to replace code like the one below. Yeah, for two items it might be useless, but for multiple such extractors it does make sense. Especially when you know only the first extractor will be used in 99% of cases.

function getDefaultExtractors(
  string $headerName, 
  string $cookieName
): iterable {
  #<  code here  >#
  return $extractors;
}

Code with ifs and array push:

$extractors = [];
if ($headerName !== null) {
  $extractors[] = Make::headerExtractor($headerName);
}
if ($cookieName !== null) {
  $extractors[] = Make::cookieExtractor($cookieName);
}

Code with array_filter and ternaries:

$extractors = array_filter([
  $headerName !== null ? Make::headerExtractor($headerName) : null,
  $cookieName !== null ? Make::cookieExtractor($cookieName) : null,
]);

Code using a generator:

$extractors = (function () use ($headerName, $cookieName): Generator {
  $headerName !== null && yield Make::headerExtractor($headerName);
  $cookieName !== null && yield Make::cookieExtractor($cookieName);
})(),

The key idea behind the generators is that the execution is actually paused on each yield statement, until the next iteration is initiated. For cases where the iteration is interrupted before all of the generated items are consumed, this saves some computation resources.