This library generates an animated GIF that visualizes a live countdown to a target date/time.
Each frame represents one second, up to a configurable maximum.
It is based on (and updated from) the original project by goors/php-gif-countdown, extended with improved rendering, validation, and configuration options.
-
Generates a second-by-second animated GIF countdown
-
Customizable background image per request via
bg=... -
Customizable font per request via
font=... -
Customizable offset to precisely position your text
-
Anti-aliased text rendering with alpha preservation
-
Fully timezone-aware countdown calculation
-
Zero-padding and formatting for multi-day countdowns
-
Optional filesystem-based caching to reduce server load
-
PHP 7.4+
-
GD Extension with TrueType font support
-
At least one PNG background in the
backgrounds/folder -
At least one TrueType font in the
fonts/folder
Clone the repository:
git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>Make sure your server has the GD extension enabled:
php -m | grep gdIf not present, enable it in your PHP configuration.
The script exposes a GIF endpoint that can be included directly in HTML <img> tags.
Example:
<img src="path_to_the_library/index.php?time=2025-12-31%2023:59:59">| Parameter | Description |
|---|---|
time |
Target date/time for the countdown (timestamp or any format supported by strtotime()) |
bg (optional) |
Selects a background PNG file (must exist in the backgrounds/ directory). Example: bg=dark |
font (optional) |
Selects a TrueType font file (must exist in the fonts/ directory). Example: font=roboto |
x-offset (optional) |
Define horizontal offset for text. Example: x-offset=150 |
y-offset (optional) |
Define vertical offset for text. Example: y-offset=150 |
Example using multiple parameters:
<img src="path_to_the_library/index.php?time=2025-07-20T18:00:00&bg=dark&font=led&x-offset=100&y-offset=100">Example With URL Encoding
<img src="path_to_the_library/index.php?time=2025-07-20T18%3A00%3A00">The countdown text appears as:
DD:HH:MM:SS
Example with more than 9 days:
12:03:45:01
If the target date is reached or passed, the GIF displays:
00:00:00:00
…and stops at that frame.
The script now supports dynamic backgrounds and dynamic fonts, selectable directly through query string parameters.
backgrounds/
- default.png
- dark.png
- light.png
fonts/
- default.ttf
- led.ttf
- digital.ttf
You can override background and font per request:
?time=2025-12-31%2023:59:59&bg=dark&font=digital
If omitted, the script falls back to the defaults DEFAULT_BACKGROUND_NAME for the background and DEFAULT_FONT_NAME for the fonts.
Editable constants are defined near the top of the script:
const BASE_IMAGE_FOLDER = __DIR__ . '/backgrounds/';
const BASE_FONT_FOLDER = __DIR__ . '/fonts/';
const DEFAULT_BACKGROUND_NAME = 'base'; // omit extension (.png)
const DEFAULT_FONT_NAME = 'font'; // omit extension (.ttf)
const FONT_SIZE = 60;
const FONT_COLOR_RGB = ["r" => 255, "g" => 255, "b" => 255];
const FONT_X_OFFSET = 60;
const FONT_Y_OFFSET = 95;
const FRAME_DELAY = 100; // Delay between frames in centiseconds (100 = 1 second)
const MAX_FRAMES = 60; // Maximum number of frames to generate
const TIME_ZONE = 'Europe/Rome'; // Time Zone- Background image
- Font file and size
- Text color (RGB)
- Text positioning (X/Y offsets)
- Frame delay
- Maximum frames
- Timezone
Starting from version 1.2, the library includes a lightweight caching layer that prevents excessive regeneration of the GIF countdown.
Generating a GIF frame-by-frame is CPU-intensive. If many clients request the same countdown (e.g., in emails), the server might regenerate identical animations multiple times per second.
The caching system ensures:
- At most one GIF is generated every 60 seconds per unique
timeparameter - Subsequent requests within that minute are served instantly from disk
- Server CPU usage is drastically reduced
Each request is keyed using the time, bg, font, x-offset, y-offset parameters:
$cacheFilename = md5($time . $bg . $font . $fontXOffset . $fontYOffset) . ".gif";
The generated GIF is stored in the cache/ directory.
For the next 60 seconds:
- If the cached GIF exists and is fresh → it is returned immediately
- If the cache is expired or missing → a new GIF is generated and stored
The caching layer is automatically active if the following file exists:
CacheManager.php
and the cache/ directory is writable.
No configuration is required.
The default TTL is 60 seconds. You may change it modifying the CACHE_TIMETOLIVE constant in the cache config section:
const CACHE_TIMETOLIVE = 60; //TTL IN SECONDS<p>Event Countdown:</p>
<img src="/path_to_the_library/index.php?time=2026-01-01%2000:00:00"><img src="https://example.com/path_to_the_library/index.php?time={{deadline}}">
<img src="https://example.com/path_to_the_library/index.php?time={{deadline}}&bg=my_bg_filename&font=my_ttf_font_filename&x-offset=100&y-offset=100">echo '<img src="path_to_the_library/index.php?time=' . urlencode($deadline) . '">';The script returns meaningful HTTP status codes:
| Code | Meaning |
|---|---|
| 400 | Invalid date format |
| 403 | Missing time parameter |
| 500 | Missing files, corrupted base image or font, GIF generation errors |
- Added optional get parameters "x-offset" and "y-offset"
- Updated README and extended comments in code.
- Updated README accordingly
- Added support for dynamic backgrounds via
bgquery parameter - Added support for dynamic fonts via
fontquery parameter - Updated README accordingly
- Added filesystem-based caching layer (1 GIF/minute per timestamp)
- Added CacheManager class
- Updated README with new documentation
- Improved overall formatting and badges
- Major refactor and cleanup
- Improved rendering quality
- Better error handling
- Full timezone support
- Forked from goors/php-gif-countdown
Distributed under the MIT License.
See LICENSE for details.
Forked and updated from https://github.com/goors/php-gif-countdown