https://github.com/ivanpreziosi/phpemailtimer
A small php library for generating dynamic email marketing countdowns. Forked and updated from https://github.com/goors/php-gif-countdown
https://github.com/ivanpreziosi/phpemailtimer
animated-gif countdown-timer email marketing newsletters php-library
Last synced: 7 days ago
JSON representation
A small php library for generating dynamic email marketing countdowns. Forked and updated from https://github.com/goors/php-gif-countdown
- Host: GitHub
- URL: https://github.com/ivanpreziosi/phpemailtimer
- Owner: ivanpreziosi
- License: mit
- Created: 2025-11-19T15:05:55.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-11-28T16:00:29.000Z (4 months ago)
- Last Synced: 2025-11-29T09:12:20.293Z (3 months ago)
- Topics: animated-gif, countdown-timer, email, marketing, newsletters, php-library
- Language: PHP
- Homepage:
- Size: 732 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```bash
git clone https://github.com//.git
cd
```
Make sure your server has the GD extension enabled:
```bash
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 `![]()
` tags.
Example:
```html
```
### 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:
```html
```
Example with URL Encoding:
```html
```
---
## 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:
```php
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()`):
```php
$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:
```php
const CACHE_TIMETOLIVE = 60; // TTL IN SECONDS
```
---
## Integration Examples
### 1. Embedding in a Website
```html
Event Countdown:
```
### 2. Dynamic Email (as long as your server allows external GIFs)
```html
```
### 3. Display in a Dashboard or Admin Panel
```php
echo '%20.%20')
';
```
---
## 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](https://github.com/goors/php-gif-countdown)