Sand Fox

Atom feed
Subscribe by Email
Subscribe on Follow.it
Subscribe on Twitter
Subscribe on Mastodon

Do Not Use Exception Class Directly

Nov 18, 2024 •
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.
1. If you don't guard against a specific situation, catch all RuntimeException's. LogicException's should go to your logger.
2. 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.
3. 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.
Category: PHP • Tags: good practices, opinion
Ignoring SSL Errors in Chrome

May 7, 2024 •
Very useful when you are developing anything WebAuthn related.
```
google-chrome --ignore-certificate-errors --user-data-dir=$HOME/tmp/chrome-dev
```
--ignore-certificate-errors will disable any SSL warnings like self-signed certs.

--user-data-dir will isolate this unsafe Chrome instance from your regular browsing.
Category: Misc • Tags: chrome, ssl

Generating UUIDv7 in PostgreSQL

Jan 20, 2024 •

But what about Postgres? We can do it too. Hopefully generators for new UUID versions will be added to uuid-ossp but it is not yet the case.

The easiest way for now is to use pgcrypto, so let's start with that:

create extension pgcrypto;

Now port the solution from the MySQL post:

select
    lpad(to_hex((extract(epoch from now()) * 1000)::bigint), '12', '0') ||
    '7' || -- version
    substr(encode(gen_random_bytes(2), 'hex'), 2) ||
    to_hex((floor(random() * 4) + 8)::int) || -- variant bits
    substr(encode(gen_random_bytes(8), 'hex'), 2)
    as uuid;

Like with MariaDB, Postgres doesn't care about dashes on insertion, so this value can be directly applied to a field with the uuid type.

And again, to make it a formatted value, use a type cast:

select
    (lpad(to_hex((extract(epoch from now()) * 1000)::bigint), '12', '0') ||
    '7' ||
    substr(encode(gen_random_bytes(2), 'hex'), 2) ||
    to_hex((floor(random() * 4) + 8)::int) ||
    substr(encode(gen_random_bytes(8), 'hex'), 2))::uuid
    as uuid;

And to have a bytea value, use decode:

select
    decode(
        lpad(to_hex((extract(epoch from now()) * 1000)::bigint), '12', '0') ||
        '7' ||
        substr(encode(gen_random_bytes(2), 'hex'), 2) ||
        to_hex((floor(random() * 4) + 8)::int) ||
        substr(encode(gen_random_bytes(8), 'hex'), 2),
        'hex'
    ) as uuid;

Category: Misc • Tags: postgres, sql, uuid, uuidv7

Generating UUIDv7 in MySQL and MariaDB

Jan 20, 2024 •

A quick way to generate UUIDv7 in MySQL 8 and MariaDB 11:

select
    concat(
        -- Use NOW(3) to get milliseconds
        lpad(hex(unix_timestamp(now(3)) * 1000), 12, '0'),
        '7', -- version
        substr(hex(random_bytes(2)), 2),
        hex(floor(rand() * 4 + 8)), -- variant bits
        substr(hex(random_bytes(8)), 2)
   ) as uuid;

This will generate a hex string that can be inserted into MariaDB's UUID type as is, dashes will be added automatically.

If you need it as a binary value, wrap with unhex:

select
    unhex(concat(
        lpad(hex(unix_timestamp(now(3)) * 1000), 12, '0'),
        '7',
        substr(hex(random_bytes(2)), 2),
        hex(floor(rand() * 4 + 8)),
        substr(hex(random_bytes(8)), 2)
    )) as uuid;

If you specifically need a valid RFC 4122 string representation, use a bin formatter function (MySQL) or a type cast (MariaDB):

-- MySQL
select
    bin_to_uuid(unhex(concat(
        lpad(hex(unix_timestamp(now(3)) * 1000), 12, '0'),
        '7',
        substr(hex(random_bytes(2)), 2),
        hex(floor(rand() * 4 + 8)),
        substr(hex(random_bytes(8)), 2)
    ))) as uuid;

-- MariaDB
select
    cast((concat(
        lpad(hex(unix_timestamp(now(3)) * 1000), 12, '0'),
        '7',
        substr(hex(random_bytes(2)), 2),
        hex(floor(rand() * 4 + 8)),
        substr(hex(random_bytes(8)), 2)
    )) as uuid) as uuid;

UPD: Postgres can do it too!

Category: Misc • Tags: mariadb, mysql, sql, uuid, uuidv7

De-hybridize Torrent

Nov 10, 2023 •

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.

Note

The process will change the infohash value so it's not for a casual case. The trackers that process torrent files on their side, like setting the private flag, a process that changes infohashes anyway, would benefit most from using this feature.

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.

Note

Mutability of torrent files does not mean that you can replace data in an existing torrent. Updated torrents will have different infohash values and be considered a different torrent in the network. But often creation of such updates without having any original files downloaded can be very beneficial.

Category: PHP • Tags: libraries, torrent, torrent file
PHP Requirements on Packagist

Oct 29, 2023 •

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

Read more…

Category: PHP • Tags: libraries, packagist
How to Choose a Minimum PHP Requirement

Oct 29, 2023 •

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

Read more…

Category: PHP • Tags: libraries, packagist

Running 32-bit Images in GitLab CI

Sep 7, 2023 •

A thing that was not obvious to me and relatively hard to google was a way to run a 32-bit docker image in the GitLab CI. Docker itself has --platform param but it is not exposed to the .gitlab-ci.yml file.

Luckily it's easy for the official Docker registry. Apart from auto-selection images, it also contains per-architecture image repos with distinct package names. You only need to specify a desired architecture prefix: like amd64/php or i386/php.

Example:

.test:
  script:
    - composer update
    - vendor/bin/phpunit

test-64bit:
  extends: .test
  stage: test
  image: amd64/php:8

test-32bit:
  extends: .test
  stage: test
  image: i386/php:8

or using the matrix:

test:
  stage: test
  image: ${ARCH}/php:${PHP_VERSION}
  script:
    - composer update
    - vendor/bin/phpunit
  parallel:
    matrix:
      - PHP_VERSION:
          - '7'
          - '8'
        ARCH:
          - amd64
          - i386

Category: Misc • Tags: gitlab, gitlab ci, i386

UUID Library (and ULID to UUID migration)

Jul 14, 2023 •

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

Category: PHP • Tags: ulid, uuid

Building 32-bit PHP on 64-bit Fedora

Jul 14, 2023 •

This is a short howto for people who already know how to compile PHP.

TL;DR:

CFLAGS='-m32' PKG_CONFIG_PATH=/usr/lib/pkgconfig ./configure --host=i886 --prefix=$HOME/Software/php32 --exec-prefix=$HOME/Software/php32 --with-gmp --enable-mbstring
make && make install

Sand Fox

Do Not Use Exception Class Directly

Do not throw `Exception`

Do not catch `Exception`

Ignoring SSL Errors in Chrome

Generating UUIDv7 in PostgreSQL

Generating UUIDv7 in MySQL and MariaDB

De-hybridize Torrent

PHP Requirements on Packagist

How to Choose a Minimum PHP Requirement