Index of every page on this site: llms.txt
All skills
Run it yourself

Use this skill whenever setting, configuring, or verifying the timezone (specifically Europe/Prague) in a Bolt CMS repository. Aligns all execution layers—config/bolt/config.yaml, src/Kernel.php boot override, Docker php.ini configurations, and compose.yaml environment—to prevent the critical Bolt CMS date-shifting bug on record saves.

  • 6 files
  • 20.5 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vondry/bolt-skills/bolt-timezone

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈89 tokens for metadata: the name and description. ≈2.8k when used: this file. ≈136 more on demand in 2 files.

Description uses 4.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈353 characters, or 4.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 timezone do not match, every save in the Bolt backend shifts publish dates by the timezone offset!

Why this happens:

  1. UTC storage, converted with PHP's zone: a record's dates (publishedAt, depublishedAt, createdAt, modifiedAt) are Doctrine datetime columns without a zone, and Bolt\Entity\Content keeps them in UTC: the setters convert the given DateTime to 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.)
  2. Admin Display: The Bolt Admin panel displays and accepts date inputs formatted in the timezone configured in config/bolt/config.yaml (timezone: Europe/Prague).
  3. Normalization & Conversion: On save, ContentEditController turns the posted date string — which carries no zone — into a DateTime with new Carbon(…), i.e. in PHP's current runtime timezone (date_default_timezone_get()), and the setter converts that to UTC.
  4. The Glitch: If PHP's runtime timezone defaults to UTC (standard in bare Linux, Docker, or unconfigured PHP) while config/bolt/config.yaml is set to Europe/Prague:
    • An editor opens an article with publish date 14:00 Prague 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!

[!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 UTC to Europe/Prague keeps 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). An UPDATE … 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 in config/packages/twig.yaml under twig.date.format and twig.date.timezone.

In Bolt CMS, this is ignored. Bolt's Bolt\Twig\FieldExtension explicitly overrides Twig's native |date filter:

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 GeneralParser always defaults date_format (F j, Y H:i) and timezone (UTC or configured value), $format and $timezone are never null when passed to Twig's formatter. Bolt intercepts every {{ record.date|date }} call and injects the values from config/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 time

This centrally controls:

  1. Twig's |date filter when invoked without arguments ({{ record.publishedAt|date }}).
  2. Twig's |localdate filter (localized using Carbon and active request locale).
  3. 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 via public/index.php or running CLI commands via bin/console—PHP's runtime timezone is set to Europe/Prague before any entity or service logic executes.

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 = Off
docker/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

  1. Update config/bolt/config.yaml: Change # timezone: UTC or existing setting to timezone: Europe/Prague.
  2. Check or create src/Kernel.php: If src/Kernel.php is missing or does not override boot(), update it to extend Bolt\Kernel and call date_default_timezone_set('Europe/Prague') in boot().
  3. Update Docker INI files: If docker/php/conf.d/ exists, verify date.timezone = Europe/Prague is present in bolt.dev.ini and bolt.prod.ini.
  4. Update Docker Compose: If compose.yaml has a database container, add TZ: "Europe/Prague".
  5. Clear Symfony Cache: Run bin/console cache:clear so the compiled container recognizes any updated configuration.
  6. 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.sh

What the script checks:

  1. [1/5] Bolt Config: Confirms config/bolt/config.yaml has timezone: Europe/Prague active (not commented out).
  2. [2/5] Kernel Override: Confirms src/Kernel.php extends BoltKernel, defines const TIMEZONE = 'Europe/Prague', and calls date_default_timezone_set(self::TIMEZONE) in boot().
  3. [3/5] Docker INI: Validates docker/php/conf.d/bolt.dev.ini and bolt.prod.ini if present.
  4. [4/5] Docker Compose: Checks for TZ: "Europe/Prague" on database containers in compose.yaml / docker-compose.yml.
  5. [5/5] Runtime Boot Check: Boots the App\Kernel in CLI mode (with cache, build and log folders in a temporary directory, so nothing is written to the project) and asserts that date_default_timezone_get() returns the expected zone.

Every check compares against Europe/Prague, or the zone given with --timezone=Area/City (or BOLT_TIMEZONE).

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 083eb14. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 weeks ago

README badge

README badge for vondry/bolt-skills/bolt-timezone