lunetics/timezone-bundle

User timezone detection and request-scoped timezone state for Symfony applications

4.0.1 2026-08-19 22:12 UTC

Requires

• php: ^8.3
• psr/clock: ^1
• psr/log: ^3
• symfony/config: ^7.4.13 || ^8.1
• symfony/dependency-injection: ^7.4.13 || ^8.1
• symfony/event-dispatcher-contracts: ^3.5
• symfony/http-foundation: ^7.4.13 || ^8.1
• symfony/http-kernel: ^7.4.13 || ^8.1
• symfony/service-contracts: ^3.5

Requires (Dev)

• geoip2/geoip2: ^3.4
• phpstan/phpstan: ^2.2
• phpstan/phpstan-symfony: ^2.0.20
• phpunit/phpunit: ^11.5
• symfony/asset-mapper: ^7.4 || ^8.1
• symfony/console: ^7.4 || ^8.1
• symfony/event-dispatcher: ^7.4 || ^8.1
• symfony/form: ^7.4 || ^8.1
• symfony/framework-bundle: ^7.4 || ^8.1
• symfony/messenger: ^7.4 || ^8.1
• symfony/routing: ^7.4 || ^8.1
• symfony/security-bundle: ^7.4 || ^8.1
• symfony/security-core: ^7.4 || ^8.1
• symfony/security-csrf: ^7.4 || ^8.1
• symfony/serializer: ^7.4 || ^8.1
• symfony/twig-bundle: ^7.4 || ^8.1
• symfony/web-profiler-bundle: ^7.4 || ^8.1
• twig/twig: ^3.0

Suggests

• ext-intl: Improves locale parsing for locale-based timezone resolution
• geoip2/geoip2: Enables MaxMind GeoIP timezone resolution
• symfony/asset-mapper: Exposes the browser timezone JavaScript asset
• symfony/console: Enables console integration
• symfony/event-dispatcher: Provides the default event dispatcher implementation
• symfony/form: Enables form timezone integration
• symfony/framework-bundle: Provides full Symfony framework integration
• symfony/messenger: Enables Messenger timezone context propagation
• symfony/routing: Enables the opt-in browser preference route
• symfony/security-bundle: Provides the token storage service used for authenticated user timezone resolution
• symfony/security-core: Enables authenticated user timezone resolution
• symfony/security-csrf: Protects the browser preference endpoint
• symfony/twig-bundle: Enables Twig timezone integration
• symfony/web-profiler-bundle: Enables timezone resolution diagnostics
• twig/twig: Enables Twig timezone helpers

MIT

• Lunetics

• symfony
• timezone
• time zone

Published on Packagist.org on 2026-08-19 22:12 UTC

README

LuneticsTimezoneBundle resolves an IANA timezone once per main Symfony request — subrequests reuse that result — and exposes it through a stable application context. It can combine explicit request data, trusted headers, persisted preferences, authenticated users, OIDC claims, MaxMind City data, and locale fallbacks.

Symfony 8 supplies timezone lists, validation primitives, and form options, but applications still need policy for choosing a user's timezone, retaining it, and carrying it through Twig and asynchronous work. This bundle provides that orchestration without changing PHP's process-wide default timezone.

Requirements

• PHP ^8.3 with Symfony ^7.4.13
• PHP ^8.4 with Symfony ^8.1 (Symfony 8 requires PHP 8.4)

Symfony 8.1 is the primary current target (July 2026), and ^8.1 intentionally permits compatible later Symfony 8 minors. The supported range covers the maintained lines only: Symfony 8.0 left support in July 2026, Symfony 6.4 stops receiving bug fixes in November 2026, and PHP 8.2 reaches end of life in December 2026. The 7.4.13 floor is the patch line for CVE-2026-48736 in symfony/http-foundation.

Install and register

composer require lunetics/timezone-bundle

Register the bundle when Symfony Flex has not done so:

// config/bundles.php
return [
    // ...
    Lunetics\TimezoneBundle\LuneticsTimezoneBundle::class => ['all' => true],
];

Minimal configuration:

# config/packages/lunetics_timezone.yaml
lunetics_timezone:
    default_timezone: UTC

Inject Lunetics\TimezoneBundle\Context\CurrentTimezoneProviderInterface:

use Lunetics\TimezoneBundle\Context\CurrentTimezoneProviderInterface;

final class LocalClock
{
    public function __construct(private CurrentTimezoneProviderInterface $timezones) {}

    public function timezone(): \DateTimeZone
    {
        return $this->timezones->getDateTimeZone();
    }
}

Documentation

• Installation and configuration
• Resolvers and precedence
• Scope and non-goals
• 4.0 architecture, contracts, and ADRs
• Upgrade from 2.1/3.0
• Changelog

Adapters

The core ships session or signed-cookie persistence and request/execution context. Optional adapters cover application callables (CallableTimezoneResolver), authenticated users, explicit OIDC claims, MaxMind City databases or readers, browser timezone sync, Twig, Symfony Form, Messenger, the web profiler, and console diagnostics. Integrations activate only when configured and available; see the installation guide for their exact wiring.

Quality

composer validate --strict --no-check-publish
composer analyse
composer test
composer check
npm test

composer check runs PHPStan and PHPUnit. The Node test covers the dependency-free browser ES module.