RealTimeGenerator

Image generation framework that supports multiple configurations.

The goals are multiple:

• Image design and small changes can be handled by non-programmers (standard .ini files).
• Only one instance of the code exists for many projects.

While you shouldn't use any project like this one nowadays (there are way better options with HTML5), there are still edge cases where it could be useful like dynamic images to be included in mails, where no JS is allowed.

Requirements

OS:

• Doesn't seem to matter, but rendering differences are present (better on Linux). Tested under Win10 and Debian9.

PHP:

• Targeting 7.2+. Tested with success on 7.2 and 7.3.

Depending on which image library you use, you'll need at least one of these libraries:

• Gd (doesn't support animated GIF files, so a slow external library is used)
• Imagemagick (Imagick)
• GraphicsMagick (Gmagick)

You'll need composer to install external libraries used in this project (imagine and gif-creator): see https://getcomposer.org/ .

Usage

Quick start

In your web server configuration, create a new virtual host to the public_html folder of the project.

If you're using Apache and planning on using the rewritten URLs (see below), either copy-paste the contents of the public_html/.htaccess in the virtual host configuration file or allow configuration overrides.

In the configurations folder, create a new configuration (custom1.conf in the following lines) and edit it according to your needs using other files as reference.

You'll probably need at least one font in resources/fonts/custom1 OR common/: for basic open fonts, see the Liberation Fonts (common.conf uses LiberationMono-Regular.ttf).

Go to your VHost url one of these ways:

• http://subdomain.name.com/custom1/ (if using the rewrite directives of .htaccess)
• http://subdomain.name.com/?p=custom1

If you wish to customize the output of a text field by using the input from GET, put it afterwards like this: (see example for more info)

• http://subdomain.name.com/custom1/?param=customtext
• http://subdomain.name.com/?p=custom1&param=customtext

Examples

• Multi-Image (one image on top of another) (JPG) : config file - result .
• Parametric text value (PNG) : config file - result .
• Date and date timer with timezones (GIF) : config file - result .
• Two parallel date timers (GIF) : config file - result .

Folder Hierarchy

Here is the expected folder hierarchy under the project root:

• src/RealTimeGenerator.php
  • The main class, called by public_html/index.php .
• src/Core/
  • The core PHP classes.
• src/Elements/
  • The elements PHP classes: the abstract root, plus one per element type.
• configurations/
  • A few test configuration files showing how to use this project, feel free to move or delete them.
  • (put your own configuration files here)
• public_html/ (ServerRoot for the web server)
  • index.php
  • .htaccess
• resources/
  • cache/
    • (one folder by configuration file name)
      • (cached output images for the appropriate configuration) (not implemented yet)
  • fonts/
    • (one folder by configuration file name)
      • (fonts used by the configuration with the parent folder name)
  • images/
    • (one folder by configuration file name)
      • (images used by the configuration with the parent folder name)
• vendor/
  • (list of dependencies, to install using composer)

Caching

As of now the best way to cache items generated by this project would be to put a cache server (like Varnish or a caching CDN) in front of the web server.

If you choose to use the internal cache (not yet implemented) and have enough free memory, I'd recommended that you mount the cache folder as a ramdisk.

Example in Linux for a 2G ramdisk:

mount -t tmpfs -o size=2G tmpfs /path/to/globalcachefolder

Or to mount it automatically at boot-time, in /etc/fstab:

tmpfs /path/to/globalcachefolder tmpfs nodev,nosuid,noexec,nodiratime,size=2G 0 0

What works

• Configuration composition (ie. having a common.conf file that defines common elements for multiple configurations)
• Static and dynamic text fields (Gd, Imagick)
• Static image import (Gd, Imagick)
• Dynamic date output (Gd, Imagick)
• Dynamic timer, multiple timers included (Gd through GifCreator)

What doesn't work

• Imagick doesn't work yet with animations.
• Gmagick hasn't yet been tested.
• Caching is not yet implemented.
• Dynamic countdown is not yet implemented.

TODO

• When using cache with parametric renders, add a hash of the arguments in the cached files names to make sure we don't serve the wrong ones.
• Add a "inframe" parameter for all displayed element types, that would define in which frame they are present (0: all).
• Support chaining of elements, for cases where one element starting position depends on the size of another.
• Add exceptions and handle them better.
• Write tests.
• Write a documentation on how everything works, and how to create new Elements.
• Add conditionality, to render elements (or not) depending on the contents of the query string.
• Optimize the edge case where a config is used only to select which image is sent back: in this case the original file should be transmitted directly.
• Maybe add support for ps/image-optimizer, to lower filesize at the expense of processing time. Cache really should be enabled before using this.