Bolt CMS Timezone Configuration (Europe/Prague)
In Bolt CMS websites operating in the Czech Republic and Central Europe, setting the timezone consistently is critical. Failing to align the timezone across all application and server layers causes a subtle but severe date corruption bug in Bolt's content editor.
This skill details the architectural root cause, the four required configuration places, and how to verify timezone parity across development, Docker, and production.
1. The Core Problem: The Bolt CMS Date-Shifting Bug
[!CAUTION] If PHP's runtime timezone and Bolt's configured
timezonedo not match, every save in the Bolt backend shifts publish dates by the timezone offset!
Why this happens:
- UTC storage, converted with PHP's zone: a record's dates (
publishedAt,depublishedAt,createdAt,modifiedAt) are Doctrinedatetimecolumns without a zone, andBolt\Entity\Contentkeeps them in UTC: the setters convert the givenDateTimeto UTC, the getters read the stored value as UTC and return it in PHP's default timezone. (Other entities — media, users, the log — store PHP's local time as it is.) - Admin Display: The Bolt Admin panel displays and accepts date inputs formatted in the timezone configured in
config/bolt/config.yaml(timezone: Europe/Prague). - Normalization & Conversion: On save,
ContentEditControllerturns the posted date string — which carries no zone — into aDateTimewithnew Carbon(…), i.e. in PHP's current runtime timezone (date_default_timezone_get()), and the setter converts that to UTC. - The Glitch:
If PHP's runtime timezone defaults to
UTC(standard in bare Linux, Docker, or unconfigured PHP) whileconfig/bolt/config.yamlis set toEurope/Prague:- An editor opens an article with publish date
14:00Prague time. - On save the form value is read in one zone and written back in the other, so it moves by the offset: +1h (CET, winter) or +2h (CEST, summer).
- After saving the article 3 times in the admin, the publish date has shifted forward by 6 hours, potentially pushing the article into the future and unpublishing it!
- An editor opens an article with publish date
[!WARNING] Do not shift stored record dates when you align the zones. Record dates are stored in UTC and converted on read, so switching PHP from
UTCtoEurope/Praguekeeps every instant: a record published at 10:18 UTC shows 12:18 in Prague before and after the change (checked against bolt/core 6.1 by reading the same record under both zones). AnUPDATE … SET published_at = published_at + INTERVAL …would move every correct date by the offset. Only dates that the bug itself shifted (records saved while the zones differed) are wrong, by whole hours per save — fix those record by record in the admin. Media, user and log timestamps are stored in PHP's local time, so their display moves by the offset once; nothing depends on them for publishing.
Other zones: the skill uses Europe/Prague as the house default. For another zone, use the same value in every layer below and run the verification with --timezone=Area/City.
The rule: The timezone must be configured identically to Europe/Prague across all layers so that date_default_timezone_get() and Bolt's configured timezone never diverge.
2. The Four Places Where Timezone Must Be Set
Across production Bolt projects, timezone is configured at four distinct layers:
├── config/bolt/config.yaml # Layer 1: Bolt CMS Twig & Admin display
├── src/Kernel.php # Layer 2: Symfony / PHP runtime Kernel boot override
├── docker/php/conf.d/ # Layer 3: PHP engine configuration (CLI & FPM)
│ ├── bolt.dev.ini
│ └── bolt.prod.ini
└── compose.yaml # Layer 4: Container OS environment (MariaDB/MySQL)Layer 1: Bolt CMS Configuration (config/bolt/config.yaml)
Uncomment or set the timezone directive under the general configuration block:
# config/bolt/config.yaml
# Set the timezone to be used on the website. For a list of valid timezone
# settings, see: http://php.net/manual/en/timezones.php
timezone: Europe/Prague- Purpose: Instructs Bolt's admin editor, Twig datetime formatters, and date fields to use Czech local time.
[!NOTE] Why
config/packages/twig.yaml(twig.date.*) does NOT work in Bolt CMS: In standalone Symfony, developers often set default date formats inconfig/packages/twig.yamlundertwig.date.formatandtwig.date.timezone.In Bolt CMS, this is ignored. Bolt's
Bolt\Twig\FieldExtensionexplicitly overrides Twig's native|datefilter:public function getDate(Environment $twig, $date, $format = null, $timezone = null): string { if ($format === null && ! $date instanceof DateInterval) { $format = $this->config->get('general/date_format', null); } if ($timezone === null) { $timezone = $this->config->get('general/timezone', null); } return $twig->getExtension(CoreExtension::class)->formatDate($date, $format, $timezone); }Because Bolt's
GeneralParseralways defaultsdate_format(F j, Y H:i) andtimezone(UTCor configured value),$formatand$timezoneare never null when passed to Twig's formatter. Bolt intercepts every{{ record.date|date }}call and injects the values fromconfig/bolt/config.yaml.Therefore, to change the default date format or timezone in Twig, configure it directly in
config/bolt/config.yaml:# config/bolt/config.yaml timezone: Europe/Prague date_format: 'j. n. Y H:i' # or 'j. n. Y' for Czech dates without timeThis centrally controls:
- Twig's
|datefilter when invoked without arguments ({{ record.publishedAt|date }}).- Twig's
|localdatefilter (localized using Carbon and active request locale).- Bolt Backend Admin listing columns and edit forms.
It does not affect REST/GraphQL API output: API Platform serializes dates itself (ISO 8601 with offset), independent of these Twig settings.
Layer 2: Application Kernel Override (src/Kernel.php)
Ensure src/Kernel.php extends Bolt\Kernel and overrides the boot() method to explicitly set PHP's default timezone:
<?php
declare(strict_types=1);
namespace App;
use Bolt\Kernel as BoltKernel;
class Kernel extends BoltKernel
{
/**
* Must match `timezone` in config/bolt/config.yaml. Bolt stores dates in UTC and converts
* them using PHP's default timezone as "local" time, while the admin shows them in the
* configured timezone. If the two differ, every save shifts publish dates by the offset.
*/
private const TIMEZONE = 'Europe/Prague';
public function boot(): void
{
date_default_timezone_set(self::TIMEZONE);
parent::boot();
}
}- Why this is critical:
- In many deployment environments (shared hosting, CI/CD runners, CLI scripts, developer machines), developers or runners may not have access to alter global
php.ini. - Overriding
Kernel::boot()guarantees that the moment the Symfony application boots—whether serving web traffic viapublic/index.phpor running CLI commands viabin/console—PHP's runtime timezone is set toEurope/Praguebefore any entity or service logic executes.
- In many deployment environments (shared hosting, CI/CD runners, CLI scripts, developer machines), developers or runners may not have access to alter global
Layer 3: PHP INI Directives (docker/php/conf.d/)
If the project uses Docker or custom PHP configuration drop-in directories, set date.timezone in both development and production configurations:
docker/php/conf.d/bolt.dev.ini
apc.enable_cli = 1
date.timezone = Europe/Prague
session.auto_start = Off
short_open_tag = Offdocker/php/conf.d/bolt.prod.ini
apc.enable_cli = 1
date.timezone = Europe/Prague
session.auto_start = Off
short_open_tag = Off- Purpose: Sets the baseline engine timezone for PHP-FPM worker pools and CLI processes before scripts start, eliminating PHP runtime notices about unset timezone.
Layer 4: Container Environment (compose.yaml / docker-compose.yml)
Under database services (MariaDB / MySQL), set the container's TZ environment variable:
# compose.yaml
services:
database: # or <project>-mariadb, etc.
image: mariadb:11.4 # an LTS release; 10.4 reached end of life in 2024
environment:
# Local development container only — never reuse these values on a server.
MYSQL_ROOT_PASSWORD: dev_root
MYSQL_DATABASE: bolt_db
MYSQL_USER: bolt_user
MYSQL_PASSWORD: dev_password
TZ: "Europe/Prague"
LANG: "en_US.UTF-8"- Purpose: Ensures the database server clock,
NOW(),CURRENT_TIMESTAMP, and MySQL error/query logs match the application's local Prague timestamps.
3. Template & Content Contexts (Best Practices)
When generating machine-readable or public summaries containing timestamps (e.g. llms.txt.twig, transactional emails, opening hours):
- Explicitly state the timezone in the copy to remove ambiguity:
"Times are local time in Prague (Europe/Prague)."
4. Step-by-Step Implementation Checklist
- Update
config/bolt/config.yaml: Change# timezone: UTCor existing setting totimezone: Europe/Prague. - Check or create
src/Kernel.php: Ifsrc/Kernel.phpis missing or does not overrideboot(), update it to extendBolt\Kerneland calldate_default_timezone_set('Europe/Prague')inboot(). - Update Docker INI files:
If
docker/php/conf.d/exists, verifydate.timezone = Europe/Pragueis present inbolt.dev.iniandbolt.prod.ini. - Update Docker Compose:
If
compose.yamlhas a database container, addTZ: "Europe/Prague". - Clear Symfony Cache:
Run
bin/console cache:clearso the compiled container recognizes any updated configuration. - Verify: Run the verification script (see below).
5. Automated Verification Script
Run the automated verification script from your project root:
vendor/tomvondracek/bolt-skills/skills/bolt-timezone/scripts/verify.shWhat the script checks:
[1/5]Bolt Config: Confirmsconfig/bolt/config.yamlhastimezone: Europe/Pragueactive (not commented out).[2/5]Kernel Override: Confirmssrc/Kernel.phpextendsBoltKernel, definesconst TIMEZONE = 'Europe/Prague', and callsdate_default_timezone_set(self::TIMEZONE)inboot().[3/5]Docker INI: Validatesdocker/php/conf.d/bolt.dev.iniandbolt.prod.iniif present.[4/5]Docker Compose: Checks forTZ: "Europe/Prague"on database containers incompose.yaml/docker-compose.yml.[5/5]Runtime Boot Check: Boots theApp\Kernelin CLI mode (with cache, build and log folders in a temporary directory, so nothing is written to the project) and asserts thatdate_default_timezone_get()returns the expected zone.
Every check compares against Europe/Prague, or the zone given with --timezone=Area/City (or BOLT_TIMEZONE).