Recently I was preparing a talk for the fwdays PHP in Kyiv. A talk about internationalization. And gues what: One of the parts of internationalization is: Timezones. Yes, I know, I am fond of them and all but that’s not what this is going to be about.

In the talk I am showing how to propperly render a datetime for a given locale in a given timezone using the IntlDateFormatter. As the talk will be in Kyiv I thought it’s only fair to use the Europe/Kyiv timezone.

The timezone Europe/Kyiv is a rather new one and was introduced in 2022 when the former timezone Europe/Kiev was renamed to Europe/Kyiv as that by now was the more widely used international spelling of the Ukrainian capital (Thank you, Vladimir, for making the world aware that the russian transcription isn’t the correct one!!)

So I added my example and thought I’d better run it through a current PHP-Version to check wether my code is actually sane and runs.

As the ICU-extension is not by default part of the images on docker-hub I created this little Dockerfile to get an image with the ICU extension:

FROM php:8.3-rc-fpm
MAINTAINER [email protected]

RUN apt-get update \
 && apt-get install -y libicu-dev \
 && docker-php-ext-configure intl --enable-intl \
 && docker-php-ext-install -j$(nproc) intl \

It’s using the latest PHP 8.3 image and adds the ICU extension. Yes! it’s not slim, there is cleanup missing etc but that is not the point here, it’s just to demonstrate something.

I created a container via docker build -t icutest .

So now let’s check the ICU version.

$ docker run icutest bash -c "php -i | grep -i icu"
ICU version => 72.1
ICU Data version => 72.1
ICU TZData version => 2022e
ICU Unicode version => 15.0
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Wait! ICU TZData version => 2022e?

As https://data.iana.org/time-zones/tzdb-2022e/ shows, that’s from October 2022! What the heck?

What’s the timezone-DB version that PHPs DateTime lib uses?

$ docker run icutest bash -c "php -i | grep -i Olson"
"Olson" Timezone Database Version => 2024.1

Oh! Great!

So we learn different things here:

PHP libraries use separate timezone-data

The DateTime extension (you know: date, DateTimeImmutable etc) use the latest timezone-db version available at compile time of the PHP-library. (Thank you Derick for that!) One of the reasons why one should stay up-to-date with PHP-versions. If that’s not possible, you can use the timezonedb pecl-package.

But the Intl Extension – as it is a wrapper around the ICU4C library – uses it’s own timezone database. Also the last one available at release time of the library.

So why do we have a mismatch there? Because at the time of writing the current release of ICU is 75.1 – and not 72.1 as the output of PHP-info shows.

The issue I am running into here is that I installed the libicu-dev package when building the container. And that installs the – by now outdated – ICU data as debian/ubuntu do not update those packages to higher major versions. An upgrade to a higher major version of a lib only happens when updating Debian/Ubuntu to a higher Major.

Despite the fact that neither Debian/Ubuntu nor ICU are using Semantic Versioning…

Don’t come with a problem!

OK. I now had analyzed the problem (my main problem was that the code didn’t run because I was using the bullseye image and not the bookworm one which is on an even older timezone DB that didn’t know Europe/Kyiv as it was from 2019…).

How to fix it?

Well, the solution seems simple: Update the ICU extension…

So I fiddled a bit around and updated another library to handle the non-semver versioning that ICU uses and ended up with this somewhat more complex Dockerfile

FROM php:8.3-rc-fpm
MAINTAINER [email protected]

RUN apt-get update \
 && apt-get install -y build-essential \
 && curl -Lo icu.tgz https://api.getlatestassets.com/github/unicode-org/icu/icu4c-%25major%25_%25minor%25-src.tgz \
 && tar -xvf icu.tgz \
 && cd icu/source \
 && LIBDIR=$( php -i | egrep -o  with-libdir=[^\']+ | sed "s/with-libdir=//") \
 && ./configure --libdir=/usr/$LIBDIR \
 && make -j \
 && make install \
 && rm -rf icu icu.tgz \
 && docker-php-ext-configure intl --enable-intl \
 && docker-php-ext-install -j$(nproc) intl

What happens here

Let’s shortly go through the dockerfile

In line 5 I install stuff that is necessary for compiling code as I will need to do that with the ICU lib.

In line 6 I download the latest version of the ICU4C library. It uses getlatestassets that will make sure that we will always get the latest relerased version. Sadly the github API doesn’t provide a way to do that out of the box, so I have to use getlatestassets.com here. To make handling easier I store the archive in a file consitently named icu.tgz

The next steps are to extract the archive and change the working directory.

In line 9 I set the LIBDIR variable from what is set for PHP so that the ICU library will afterwards be placed in the right folder where PHP expects all the libs to be. Otherwise I get some odd runtime errors when PHP tries to load a library that is not available.

In line 10 I tell the config script where to put that library file and then it’s make and make install to build and install the library.

Afterwards I remove the archive file. In a production image I’d do some more cleanup here to get the imagesize down.

After that it’s the same commands that I already used in the old Dockerfile, just this time the “correct” library-version will be used.

So let’s create and check the container:

$ docker build -t icutest .
$ docker run icutest bash -c "php -i | grep -i icu"
ICU version => 75.1
ICU Data version => 75.1
ICU TZData version => 2024a
ICU Unicode version => 15.1
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Great! Now we have a current version of ICU with a rather recent version of the timezone-database. And also all the other awesome things that are part of a new ICU version! Like new translations, new emojis etc.

What did I learn?

Whenever I am using the Intl extension in PHP I will now make sure that the PHP-Version I am using is actually using the latest available ICU-library as one can not take for granted that that is delivered by default.

In essence I should probably check that for every library I use, but most of them do not contain such volatile information as the (constantly changing) timezone DB. And usually fixes for critical issues are ported to the respective libraries by the distros. But that requires me to keep on a distro-version that gets these patches!

So in essence the main thing is – as always – Stay up to date