PHP EMAIL TIMER

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.

Features

• Generates a second-by-second animated GIF countdown
• Customizable background image per request via bg=...
• Customizable font per request via font=...
• Customizable text position via x-offset / y-offset
• Customizable text color (RGB) via font-color-r / font-color-g / font-color-b
• 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

---

Requirements

• PHP 7.4+
• GD Extension with TrueType font support (FreeType)
• At least one PNG background in the backgrounds/ folder
• At least one TrueType font in the fonts/ folder

---

Installation

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 gd

If not present, enable it in your PHP configuration.

---

Usage

Basic HTTP Call

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">

GET Parameters

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 backgrounds/). Example: bg=dark
font (optional)	Selects a TrueType font file (must exist in fonts/). Example: font=roboto
x-offset (optional)	Horizontal text offset. Example: x-offset=150
y-offset (optional)	Vertical text offset. Example: y-offset=150
font-color-r (opt.)	Text color red channel (0..255). Example: font-color-r=255
font-color-g (opt.)	Text color green channel (0..255). Example: font-color-g=255
font-color-b (opt.)	Text color blue channel (0..255). Example: font-color-b=255

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&font-color-r=255&font-color-g=0&font-color-b=0">

Example with URL Encoding:

<img src="path_to_the_library/index.php?time=2025-07-20T18%3A00%3A00">

---

Countdown Display Format

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.

---

Configuration

The script supports dynamic backgrounds, dynamic fonts, dynamic text position, and dynamic RGB text color selectable through query string parameters.

Directory Structure

backgrounds/
   - base.png
   - dark.png
   - light.png

fonts/
   - font.ttf
   - led.ttf
   - digital.ttf

Runtime Override

You can override background, font, offsets, and color per request:

?time=2025-12-31%2023:59:59&bg=dark&font=digital&x-offset=80&y-offset=110&font-color-r=255&font-color-g=255&font-color-b=255

If omitted, the script falls back to the defaults DEFAULT_BACKGROUND_NAME and DEFAULT_FONT_NAME.

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

What You Can Customize

• Background image
• Font file and size
• Text color (RGB)
• Text positioning (X/Y offsets)
• Frame delay
• Maximum frames
• Timezone

---

Caching System (Optional)

Starting from version 1.2, the library includes a lightweight caching layer that prevents excessive regeneration of the GIF countdown.

Why Caching?

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 combination of request parameters
• Subsequent requests within that TTL are served instantly from disk
• Server CPU usage is drastically reduced

How It Works

Each request is keyed using all parameters that affect the rendered output:

• time
• bg
• font
• x-offset
• y-offset
• font-color-r, font-color-g, font-color-b

Internally, the cache filename is generated from a JSON-encoded cache key (with a fallback to serialize()):

$cacheKey = [
  "time"  => (string)$time,
  "bg"    => $bg,
  "font"  => $font,
  "x"     => $fontXOffset,
  "y"     => $fontYOffset,
  "color" => $fontColorRgb,
];

$cacheJson = json_encode($cacheKey, JSON_UNESCAPED_SLASHES);
if ($cacheJson === false) {
  $cacheJson = serialize($cacheKey);
}
$cacheFilename = md5($cacheJson) . ".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

Enabling the Cache

The caching layer is automatically active if:

• CacheManager.php exists
• the cache/ directory is writable

No configuration is required.

Cache Lifetime

The default TTL is 60 seconds. You may change it by modifying the CACHE_TIMETOLIVE constant:

const CACHE_TIMETOLIVE = 60; // TTL IN SECONDS

---

Integration Examples

1. Embedding in a Website

<p>Event Countdown:</p>
<img src="/path_to_the_library/index.php?time=2026-01-01%2000:00:00">

2. Dynamic Email (as long as your server allows external GIFs)

<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&font-color-r=255&font-color-g=255&font-color-b=255">

3. Display in a Dashboard or Admin Panel

echo '<img src="path_to_the_library/index.php?time=' . urlencode($deadline) . '">';

---

Error Handling

The script returns meaningful HTTP status codes:

Code	Meaning
400	Invalid date format
403	Missing time parameter
500	Missing files, corrupted base image/font, rendering errors, GIF generation

---

Changelog

v2.5

• Added support for dynamic RGB text color via font-color-r, font-color-g, font-color-b
• Improved input validation and security (sanitized asset names)
• Improved caching key to include offsets and RGB color
• Added additional runtime checks for rendering/graphics functions

v2.3

• Added optional GET parameters x-offset and y-offset

v2.2

• Updated README and extended comments in code.

v2.0.1

• Updated README accordingly

v2.0

• Added support for dynamic backgrounds via bg query parameter
• Added support for dynamic fonts via font query parameter
• Updated README accordingly

v1.2

• Added filesystem-based caching layer (1 GIF/minute per timestamp)
• Added CacheManager class
• Updated README with new documentation
• Improved overall formatting and badges

v1.0

• Major refactor and cleanup
• Improved rendering quality
• Better error handling
• Full timezone support

v0.1

• Forked from goors/php-gif-countdown

---

License

Distributed under the MIT License. See LICENSE for details.

---

Forked and updated from https://github.com/goors/php-gif-countdown