Download the PHP package andanteproject/timestampable-bundle without Composer

Timestampable Bundle

Symfony Bundle - Andante Project

A Symfony Bundle to handle entity createdAt and updatedAt dates with Doctrine. 🕰

Requirements

Symfony 5.x–8.x and PHP 8.2.

Install

Via Composer:

Features

• No configuration required to get started; fully customizable;
• createdAt and updatedAt properties are ?\DateTimeImmutable;
• Uses Symfony Clock;
• Does not override your createdAt and updatedAt values when you set them explicitly;
• No annotations or attributes required;
• Works like magic ✨.

Basic usage

After install, ensure the bundle is registered in your Symfony bundles list (config/bundles.php):

This is done automatically if you use Symfony Flex. Otherwise, register it manually.

Suppose you have an App\Entity\Article Doctrine entity and want to track created and updated dates. Implement Andante\TimestampableBundle\Timestampable\TimestampableInterface and use the Andante\TimestampableBundle\Timestampable\TimestampableTrait trait.

Update your database schema using your usual Doctrine workflow (e.g. bin/console doctrine:schema:update --force, or use migrations for a safer approach).

You should see new columns named created_at and updated_at (Doctrine naming strategy.

You're done! 🎉

TimestampableInterface and TimestampableTrait are shortcuts that combine CreatedAtTimestampableInterface + CreatedAtTimestampableTrait and UpdatedAtTimestampableInterface + UpdatedAtTimestampableTrait. To track only created or updated dates, use the more specific interfaces and traits below.

Usage without the trait

This lets you use different property names (e.g. created and updated instead of createdAt and updatedAt). You must specify these in the bundle configuration.

Metadata cache warming

The bundle discovers which entities are timestampable and how their createdAt / updatedAt properties and columns are configured. That information is metadata: it is computed once and then cached in a PHP file under your cache directory so later requests can reuse it without scanning entities again.

By default, metadata is built on first use: the first time a timestampable entity is persisted or updated in a request, the bundle builds metadata for all mapped entities, caches it in memory and writes it to disk. Subsequent requests (and the same request) then use the cached metadata. For most applications this is enough and you do not need to change anything.

If you want to avoid any metadata computation on the first request (e.g. in production after a deploy, or in CI when running a single command), you can enable cache warming. When enabled, a Symfony cache warmer runs during cache:warmup (and when the cache is built on the first request in dev). It precomputes timestampable metadata for all known Doctrine entities and writes it to the cache file. After that, the first real request already uses the prebuilt metadata.

When to enable it

• Leave it disabled (default) if you are fine with the first request (or first command) doing a bit of extra work once per cache build.
• Enable it if you care about consistent cold-start performance (e.g. serverless, CI, or strict SLAs on the first request after deploy).

You can turn it on in the configuration with metadata_cache_warmer_enabled: true.

Configuration (completely optional)

This bundle is built to save you time and follow best practices out of the box.

You do not need an andante_timestampable.yaml config file in your application.

If you need to customize it (e.g. for legacy code), you can change most behavior via the bundle configuration:

Metadata cache warmer

See Metadata cache warming for a full explanation. Summary:

Built with ❤️ by the Andante Project team.