Sand Fox (Posts about PHP)

Using PIE in Docker

2026-01-05T12:03:00+02:00

As you may know, PECL is now soft-deprecated and PIE is the recommended way to install exenetsions.

The current PHP docker images do not package PIE executable. Luckily there is an instruction in the doc that says this:

COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
RUN pie install asgrim/example-pie-extension

It works but this solution is bad. It will import a 6MB PIE executable as a dead weight. Trying to find a solution to this solution, I stumbled on this blog post: rabbithole.wwwdotorg.org. Luckily RUN --mount can work with external images instead of stages and files instead of directories. This allows us to collapse the installation into a single layer:

RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
    pie install asgrim/example-pie-extension

This will make your final image 6MB ligher.

Peso Framework

2025-07-11T06:42:00+03:00

Another thing I've been secretly building is the Peso Framework, a tool to query currency conversion rates.

It started when I was pissed that florianv/exchanger, a tool I was perfectly happy with previously, got a broken release (2.8.2) got abandoned for almost a year now, and still isn't fixed as of this post.

Peso consists of 3 components:

A service (data source)
An integration (data consumer)
A glue library (peso/core) that contains the Service contract, standard request/response objects, and useful tools to develop services and integrations

A simple example:

composer require peso/peso peso/ecb-service php-http/discovery guzzlehttp/guzzle

<?php

use Peso\Peso\CurrencyConverter;
use Peso\Services\EuropeanCentralBankService;

require __DIR__ . '/vendor/autoload.php';

// caching omitted for simplicity
$peso = new CurrencyConverter(new EuropeanCentralBankService());

echo $peso->getHistoricalExchangeRate(
    'EUR', // base
    'PHP', // quote
    '2025-06-13', // date (Y-m-d string or DateTime or arokettu/date Date)
), PHP_EOL; // '64.706'

Advantages over the Exchanger:

Caching moved to the Service side making it more effective
No way for a service to mistake a historical exchange rate request with a current exchange rate request
Also currency conversion requests for services that support them
Ability to add new request types without breaking the backward compatibility
Services reside in their own separate packages so the main package is not a huge garbage dump of dead or unsupported services like Cryptonator

JSON5 Tools

2025-07-11T05:46:00+03:00

Presenting a couple of JSON5 tools I built.

The first one was done a year ago, a docker CLI image to convert JSON5 to JSON: arokettu/json5-to-json.

$ echo "{ hello: 'world' }" | docker run -i --rm arokettu/json5-to-json
{"hello":"world"}

A simple tool to convert your configs on the build phase without installing anything into your images.

The second one is a builder/serializer that is aimed at creating pretty configs in PHP: arokettu/json5-builder.

While it can just serialize some data into JSON5, the goal is to create nice configs with comments and custom formatting.

<?php

use Arokettu\Json5\Json5Encoder;
use Arokettu\Json5\Values\CommentDecorator;
use Arokettu\Json5\Values\HexInteger;

require __DIR__ . '/../vendor/autoload.php';

$config = new CommentDecorator(
    [
        'bareKeys' => '<- Look, no quotes!',
        'value' => new CommentDecorator(
            new HexInteger(0xFFF),
            commentAfter: 'This is a very important value'
         ),
        'notAvailableInJSON' => [NAN, INF],
        'end' => 'auto trailing comma ->'
    ],
    commentBefore: 'This is my cool JSON5 config!',
);

echo Json5Encoder::encode($config);

// This is my cool JSON5 config!
{
    bareKeys: "<- Look, no quotes!",
    value: 0xFFF, // This is a very important value
    notAvailableInJSON: [
        NaN,
        Infinity,
    ],
    end: "auto trailing comma ->",
}

Do Not Use Exception Class Directly

2025-10-09T20:57:00+03:00

It is a bad practice to use the Exception class directly in PHP. That means 2 points:

Do not throw Exception directly
Do not catch Exception directly

Subclassing Exception is not a direct use in this context.

Do not throw `Exception`

There are a lot of specific Exception descendants in PHP. See documentation for the full list. It's not necessary to use and remember all of them, many have unclear use cases, but at very least you should separate your exceptions into RuntimeException and LogicException. As the doc says, LogicException means code misuse. Throw LogicException in cases when the upstream must be fixed because it uses your code incorrectly. Throw RuntimeException in cases that are not predictable by the upstream, like service failures or invalid user input.

In case you use exceptions for flow control, you need your own custom exceptions anyway. In this case you can extend the base Exception, extending Exception directly is not a sin, especially if your exceptions are not error conditions.

Do not catch `Exception`

Assuming you follow the previous point, there is no need to catch Exception's.

If you don't guard against a specific situation, catch all RuntimeException's. LogicException's should go to your logger.
In a global error handler that writes your logs, you need to catch Errors too, so you need to go even further and catch Throwable.
If you use exceptions for flow control (please don't haha) you already catching your own exceptions, and if you follow the previous point, they are already separated from actual error conditions and won't be caught mistakenly by a wrong level.

Notable exceptions to the rule:

You use PHP below 7.0 and don't have Throwable. Well, it's 2024 already so this is another call for you to upgrade. Otherwise assume point 2 allows you to catch a base Exception.
You use a library that throws plain Exception instances. Well, bad for you, but maybe it's a good idea to report this thing as a problem.

De-hybridize Torrent

2023-11-10T11:08:00+02:00

A feature that may be desired for some anti-V2 trackers. While I would like to see the torrent community going the other way around, some trackers choose not to allow version 2 torrents and sometimes even hybrids.

The torrent file library now allows cleaning unnecessary or undesired metadata versions from a torrent file.

The intended use and the primary future scope is actually the other way around: the ability to remove version 1 metadata to make use of easy mutability of version 2 torrents to add or remove files in existing torrent structures.

PHP Requirements on Packagist

2023-10-29T01:28:00+03:00

A followup for the previous post: the minimum required PHP versions in packages on the Packagist.

Read more… (1 min remaining to read)

How to Choose a Minimum PHP Requirement

2023-12-05T18:13:00+02:00

As a library developer I often face a problem what should be a minimum PHP requirement. Here are some of my principles.

UUID Library (and ULID to UUID migration)

2023-07-14T05:48:00+03:00

I created a UUID and ULID library with Doctrine support. Well, who didn't :D

The main scenario for myself was a possible migration for a project from ULIDs to UUIDs since UUIDs got a little bit of support in MySQL 8.

Example code:

<?php

use Arokettu\Uuid\UuidParser;

// Just a random ULID
$ulid = UuidParser::fromBase32('01H44RDYXJPFCF895N3BBXCZRC');
var_dump($ulid->isUuidV7Compatible()); // false
// UnexpectedValueException: This ULID cannot be converted to UUID v7 losslessly
// $uuid = $ulid->toUuidV7();
$uuid = $ulid->toUuidV7(lossy: true);
// note digit 13 becoming '7' and digit 17 moving into [89ab] range
var_dump($uuid->toString());    // 01890986-fbb2-73d8-b424-b51ad7d67f0c
var_dump($ulid->toRfc4122());   // 01890986-fbb2-b3d8-f424-b51ad7d67f0c
var_dump($uuid->toBase32());    // 01H44RDYXJEFCB895N3BBXCZRC
var_dump($ulid->toString());    // 01H44RDYXJPFCF895N3BBXCZRC

March Packages on Packagist

2023-03-31T04:05:00+03:00

I'm continuing to publish useless nih junk on the Packagist:

arokettu/arithmetic-parser: A very configurable arithmetic parser and calculator. You can define your own set of functions and operators. You can even disable multiplication if you want to!
arokettu/clock: A set of PSR-20 clock implementations. Everyone has these implemented so why not me? :D
arokettu/system-clock: All these PSR-20 clock packages usually contain a ton of clocks for testing purposes but most of the production code needs only new DateTimeImmutable('now') so I extracted SystemClock to a separate package that has only SystemClock.php and composer.json for the smallest possible package (if you don't count uglifying it js-like)
arokettu/kilo-mega: This one was actually released on February but I've forgot to write about it. It's a simple formatter for metric prefixes.
```
<?php
echo format_metric(1000, suffix: 'W'); // 1.0 kW
echo format_bytes(1234); // 1.2 KiB
```

Also a new significant release:

arokettu/torrent-file: Torrent file class got file listing classes for v1 and v2 metadata in 5.0 release.

Moving packages to Arokettu

2023-01-15T02:58:00+02:00

Just finished moving my old composer packages from sandfoxme/* to arokettu/*.

Full list:

composer-viz (old, new): the only one I moved a year ago
bencode (old, new)
monsterid (old, new)
phpstorm-metadata-export (old, new)
private-access (old, new)
torrent-file (old, new)

I tried to make the migration process as smooth as possible. I'm sorry for the inconvenience it might have caused.

Installing Composer in Docker the 2020-s Way

2023-01-11T10:14:00+02:00

While the original way is still valid, in Docker it's now easier to copy the Composer executable from its Docker image.

COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

or for PHP < 7.2.5

COPY --from=composer:2.2 /usr/bin/composer /usr/local/bin/composer

Please note that without the installer, dependencies won't be checked, so you also need to install git and/or zip, and preferably optional dependencies like mbstring too.

Found accidentally on the Stack Overflow. There is also another interesting and underliked method for the case when you don't want to keep the composer executable and cache files in your image.

OpenSpout

2022-12-22T16:32:00+02:00

I have recently found myself in a situation when 3 out of 4 libraries that I used to work with Excel files were abandoned:

akeneo-labs/spreadsheet-parser (streaming reader) had no commits in 4 years
mk-j/php_xlsxwriter (streaming writer) had no commits in 2 years
box/spout (streaming reader/writer) is formally abandoned

Luckily there exists a community fork of Spout called OpenSpout and it can replace them all. It seems pretty popular with 1 mln downloads and 229 stars but it's still less popular than the original and I managed to find it only by navigating the forks of Spout so I think it just needs more exposure.

PHP 8.2 and my achievement

2022-12-10T13:11:00+02:00

A small step for the community may still be a huge leap for specific people, like Pierrick Charron and Sergey Panteleev who became this version release managers. I would like to congratulate them with a successful release.

This moon-in-reverse scale leap also happened to me: I got my first MR accepted to the PHP itself. It's the second C-based project that I contributed professionally, and the only huge one. The first one was my systemd-journal lib wrapper.

PHP 8.2 and my libraries

2022-12-10T12:54:00+02:00

I have re-tested all my libraries for compatibility with PHP 8.2. Luckily due to small amount of changes and, well, me not using some bad practices, they are all compatible with the new release.

Only MonsterID had a new release to leverage the new Random Extension.

PHP 8.2 Released

2022-12-10T12:50:00+02:00

PHP 8.2 has been released. It's a relatively small release by new features. I already covered some of them. Here are things that I would like to highlight:

Read more… (1 min remaining to read)

Unsigned

2022-09-06T20:54:00+03:00

Unsigned is a fixed (but arbitrary) length unsigned integer arithmetic library for native PHP. It was created as a helper for the Random Extension Polyfill to remove hard dependency on the GMP. It may be useful for weird arithmetic with shifts and unsigned overflows that is used in RNGS, encryptors, hashes, etc. (But it won't be cryptographically secure! Time based attacks are quite possible because of some optimizations) Performance greatly depends on the PHP version, with PHP 8.0+ it performs quite nicely, only slightly slower than GMP.

https://sandfox.dev/php/unsigned.html

Polyfill for Random Extension

2022-07-23T19:52:00+03:00

Announcing my new library, a polyfill for the new sexy ext-random from PHP 8.2 that I mentioned a couple of posts ago. It requires PHP 7.1+ and the GMP extension.

There will be some limitations with the compatibility but it's already usable for most simple use cases. Grab it here: https://sandfox.dev/php/random-polyfill.html

Many thanks to Go Kudo for his work on the original extension.

Early Look at PHP 8.2

2022-06-22T02:23:00+03:00

It's a month before the feature freeze so we can predict what the release will look like. So far it seems like an underwhelming release without any killer features. It still has very nice language improvements.

These are the things I would like to highlight:

Read more… (1 min remaining to read)

License Manager for Composer

2022-06-22T02:12:00+03:00

I found myself in a need to filter away some licenses for my dependencies (AGPL, I'm looking at you). I've found a well known plugin for that: metasyntactical/composer-plugin-license-check.

The problem that I found with it is that it doesn't prevent you from installing blacklisted packages. I mean it was designed to do that but fails on Composer 2.0+.

I started investigating for the ways to fix that but ended up with a feature complete plugin. It also offers some more flexibility in the config.

Grab it here: https://sandfox.dev/php/composer-license-manager.html

PHP 5: if (\false)

2022-01-07T23:07:00+02:00

I was wondering why the typical class alias boilerplate code uses this weird backslash in if (\false) like here for example.

It turns out this code will wish you a happy debugging in PHP 5.3-5.6:

<?php

namespace ns;

define('ns\\false', 1);

if (false) {
    echo "Happy Debugging", PHP_EOL;
}

Not a very useful knowledge now but an interesting history fact.

PHP 8.1 Syntax Showcase

2021-11-30T19:37:00+02:00

PHP 8.1 was released when I was suffering from COVID so I'm a bit late.

<?php

enum Status
{
    case OK;
    case Error;
}

#[SomeAttr(new SomeNestedAttr())]
class TestTest
{
    public function __construct(
        public readonly Status $status = Status::OK,
        private Logger $logger = new FileLogger(perm: 0o644),
    ) {}

    public function process(Iterator&Countable $value)
    {
        if (count($value) === 0) {
            $this->error();
        }
    }

    public function error(): never
    {
        $this->logger->error('Error!');
        exit;
    }
}

$test = new TestTest();

$arr1 = ['a' => new ArrayObject()];
$arr2 = ['b' => new ArrayIterator()];

$result = array_map($test->process(...), [...$arr1, ...$arr2]);

Torrent File 2.2

2021-11-30T19:30:00+02:00

The torrent file library got its biggest update. Versions 2.2 / 3.0 added support for:

BEP-5: DHT nodes list
BEP-17: HTTP seed urls
BEP-19: WebSeed urls
BEP-47: sha1 sums, executable files, symlinks, padding
Big cleanup to support torrent v2 metadata (BEP-52) in 2.3 / 3.1

CVE-2021-41106

2021-09-30T02:12:00+03:00

Nice, now I have my first CVE :D The one I've found, not the one I've created :D

If you're using lcobucci/jwt, please upgrade.

IsResource

2021-09-28T04:42:00+03:00

Inspired by a recent discussion in the PHP Internals, I decided to provide a userland solution. Check this:

<?php

$hash = hash_init('md5');

// vanilla functions:
is_resource($hash); // true in PHP <= 7.1, false in PHP >= 7.2
get_resource_type($hash); // "Hash Context" in PHP <= 7.1, various errors otherwise

// library functions:
\Arokettu\IsResource\is_resource($hash); // true
\Arokettu\IsResource\get_resource_type($hash); // "Hash Context"

Get it on my dev portal: https://sandfox.dev/php/is-resource.html

Pseudolocale Lib for PHP

2021-01-27T04:20:00+02:00

I haven't found a good standalone pseudolocalization library for PHP so I wrote my own.

https://sandfox.dev/php/pseudolocale.html

Or if you're using Symfony Components or you don't mind using huge libraries for simple tasks, there is one good alternative: PseudoLocalizationTranslator in the Symfony Translation Component since version 5.2.

PHP 8.0 Comparison Change

2020-10-22T23:00:00+03:00

Another new thing in PHP 8.0 will be slightly less madness in non strict value comparison.

Read more… (1 min remaining to read)

OOP in PHP 4 and 8

2020-10-02T15:03:00+03:00

Deprecation of class name constructors means that you no longer can write OOP code that works both in PHP 4 and PHP 8 without some hackery. This works however:

<?php

class WorksIn4And8
{
    var $int;

    // Regular method in PHP 4
    // Constructor in 5-8
    function __construct($int)
    {
        error_log('__construct()');
        $this->int = $int;
    }

    // Constructor in PHP 4
    // Constructor overridden by __construct in 5-7
    // Regular method in PHP 8
    function WorksIn4And8($int)
    {
        error_log('WorksIn4And8()');
        $this->__construct($int);
    }

    function getInt()
    {
        return $this->int;
    }
}

$obj = new WorksIn4And8(48);

var_dump($obj->getInt());

PHP 8.0 Syntax Showcase

2020-09-30T16:54:00+03:00

Since RC1 is released today, I decided to make a small demonstration of PHP 8.0 syntax features.

<?php

#[FuncAttribute]
function func(SplHeap|ArrayObject|null $object, mixed $value = null): ArrayAccess|false
{
    return match ($object?->count()) {
        0, null => throw new RuntimeException(),
        default => $object,
    };
}

try {
    func(object: new ArrayObject());
} catch (RuntimeException) {
    // ignore
}

Method Calls with Arbitrary Names

2020-07-24T07:20:00+03:00

A discovery of the day. Many people know that you can define and read an object property with an arbitrary name:

<?php

$s = new stdClass();
$s->{'any string here'} = 123;
echo $s->{'any string here'}; // 123

Read more… (1 min remaining to read)

I released the first PHP 8 library ever

2020-07-03T22:12:00+03:00

At least among the libraries listed on the Packagist. On this Tuesday sandfoxme/bencode was updated to 2.0 that requires PHP 8 as a minimum. While it was meant mostly as an experiment and a joke, it allowed me to try some new features like Stringable interface and remove some old compatibility handling thanks to mbstring.func_overload being finally removed.

sabre/xml

2020-06-10T00:00:00+03:00

An awesome discovery of today was made in an article titled An XML library for PHP you may not hate. As an unexpected twist I really didn't hate it, in fact it helped me to solve a problem that I had. It is called sabre/xml and it's a part of the sabre/dav project.

Install Composer in Docker

2023-01-11T10:14:00+02:00

Here is a small snippet adapted from the official instruction:

RUN php -r "copy('https://composer.github.io/installer.sig', '/tmp/composer.sig');" && \
    php -r "copy('https://getcomposer.org/installer', '/tmp/composer-setup.php');" && \
    php -r '$expected = file_get_contents("/tmp/composer.sig"); $actual = hash_file("sha384", "/tmp/composer-setup.php"); exit(intval(!hash_equals($expected, $actual)));' && \
    php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer && \
    chmod +x /usr/local/bin/composer && \
    rm /tmp/composer-setup.php /tmp/composer.sig

It doesn't require a script file, doesn't deal with environment variables, and doesn't depend on the shell.

Read more… (1 min remaining to read)

PHP 7.4: Splat Inconsistency

2019-08-29T21:52:00+03:00

PHP 7.4 has this great new feature: splat operator now works in array expressions.

Read more… (1 min remaining to read)

Encryptor

2019-08-24T03:50:00+03:00

Created a simple cli file encryptor using libsodium

The app can create a password-protected file encoded with XSalsa20 and Argon2id

See my dev portal: https://sandfox.dev/php/encryptor.html

Composer Yaml

2019-04-19T22:00:00+03:00

My new library to allow composer to read config from YAML file. There is some demand in comments for composer config but the developers are not interested and most 3rd party attempts to solve it are limited to yaml2json converters.

I tried a slightly different approach. There is a command in the composer itself that changes the way the config is read: composer global. During its execution it changes current working directory, resets composer state, and forces the composer to read config from another directory.

What I tried to do: I put yaml2json converter in place of global's directory changing code, and it seems it worked. Of course, some things got broken like any command that tries to change composer.json will no longer have any effect, however many people don't use them and it may be an acceptable tradeoff for using yml-based config.

You can find the project on my new dev website: https://sandfox.dev/php/composer-yaml.html

Private Composer Repo with GitLab and Satis

2024-05-01T21:05:00+03:00

You can easily create your own composer repository using Satis and GitLab. I will use global https://gitlab.com but it should be most useful for private corporate GitLab installations. You will need CI and Pages

Read more… (1 min remaining to read)

PhpStorm Advanced Metadata Exporter

2018-03-06T07:54:00+02:00

As a Silex user I liked Pimple Container Dumper that worked with Silex Idea Plugin to enable code completion for Pimple DI in PhpStorm. But now with Silex EOL'd I have to move to Slim.

I've found no such projects so I had to write my own. Here it is: sandfoxme/phpstorm-metadata-export. It currently supports exporting data from Pimple and has 3 integration middlewares: for Slim, for Silex and for Psr-15 compatible frameworks.

P.S. Code completion support for ArrayAccess containers seem to be currently broken in PhpStorm (WI-33309, WI-35503). So I don't currently recommend replacing Silex Idea Plugin with this library unless you use Pimple in Psr-11 compliant way (like Slim does by default)

Composer Viz

2017-08-06T12:12:00+03:00

A tool inspired by bundle viz command.

Just look at its selfie:

Get it on my dev site: https://sandfox.dev/php/composer-viz.html

PHP Access Private Methods and Fields

2016-11-16T21:00:00+02:00

These two simple functions can come in handy as helpers for something like PsySH. PHP >= 7.0 is required.

Read more… (1 min remaining to read)

Sand Fox (Posts about PHP)

Using PIE in Docker

Peso Framework

JSON5 Tools

Do Not Use Exception Class Directly

Do not throw Exception

Do not catch Exception

De-hybridize Torrent

PHP Requirements on Packagist

How to Choose a Minimum PHP Requirement

UUID Library (and ULID to UUID migration)

March Packages on Packagist

Moving packages to Arokettu

Installing Composer in Docker the 2020-s Way

OpenSpout

PHP 8.2 and my achievement

PHP 8.2 and my libraries

PHP 8.2 Released

Unsigned

Polyfill for Random Extension

Early Look at PHP 8.2

License Manager for Composer

PHP 5: if (\false)

PHP 8.1 Syntax Showcase

Torrent File 2.2

CVE-2021-41106

IsResource

Pseudolocale Lib for PHP

PHP 8.0 Comparison Change

OOP in PHP 4 and 8

PHP 8.0 Syntax Showcase

Method Calls with Arbitrary Names

I released the first PHP 8 library ever

sabre/xml

Install Composer in Docker

PHP 7.4: Splat Inconsistency

Encryptor

Composer Yaml

Private Composer Repo with GitLab and Satis

PhpStorm Advanced Metadata Exporter

Composer Viz

PHP Access Private Methods and Fields

Do not throw `Exception`

Do not catch `Exception`