Textimage
A module that provides text-on-image generation functionality using Image Effects' Text overlay effect, enabling dynamic image creation with overlaid text.
textimage
Install
composer require 'drupal/textimage:8.x-4.6'
composer require 'drupal/textimage:8.x-4.3'
Overview
Textimage is a powerful Drupal module that adds text-to-image functionality using GD2 and FreeType libraries. It integrates deeply with the Image Effects module's 'Text overlay' effect to generate images with customizable text overlays on the fly.
The module provides field display formatters for both Text and Image fields, allowing content editors to automatically generate styled images from field values. It also offers a comprehensive programmatic API for developers to generate Textimage images dynamically. Token support enables dynamic text replacement based on node, user, and file contexts.
Textimage supports multiple generation methods: via field formatters in content type displays, via direct URL generation for authorized users, or programmatically through its factory service. Generated images are cached using SHA256-based identifiers for optimal performance, and support both public and private file storage schemes.
Features
- Integrates with Image Effects module's 'Text overlay' effect to replace default text with dynamic field values or API-provided text
- Field display formatters for Text (text, text_long, text_with_summary, string, string_long) and Image fields that render content as styled Textimage images
- Comprehensive Textimage API via TextimageFactory service for programmatic image generation with fluent interface
- Token support for dynamic text replacement including node, user, and file context tokens
- URL-based direct generation of Textimage images (requires permission) using configurable text separators
- Deferred image building option that postpones image generation to a separate request for better performance
- Caching mechanism with SHA256-based IDs to avoid regenerating identical images
- Support for both public and private file storage schemes per image style
- Temporary image generation mode for previews and one-off images (cleaned up on cron)
- Custom Textimage tokens ([node:textimage-uri:...] and [node:textimage-url:...]) to retrieve generated image locations
- Configurable default image format (PNG, JPEG, GIF) with per-style override capability
- Image style extension with Textimage-specific options including file destination scheme
Use Cases
Dynamic Headings and Typography
Create visually rich headings by converting text fields into styled images with custom fonts. Useful for sites requiring consistent branded typography that cannot be achieved with web fonts alone, such as logos, artistic headlines, or specialty typefaces.
Personalized Images
Generate personalized images using tokens like [node:author:name] or [current-user:name] to create customized graphics that display user-specific content, such as personalized badges, certificates, or welcome messages.
Image Watermarking
Use the Image field formatter to overlay text (such as copyright notices, photographer credits, or site branding) on uploaded images automatically during display.
Social Media Images
Generate Open Graph or Twitter Card images dynamically by combining article titles with background images, ensuring each piece of content has a unique, branded social sharing image.
E-commerce Product Labels
Create dynamic product images with overlaid text for prices, discounts, or availability status that update based on product field values.
Multi-language Image Generation
Generate images with text in different languages by using token-replaced content from translated fields, ensuring images display appropriate language-specific text.
Tips
- When creating image styles for Textimage, add multiple Text overlay effects if you need to place text in different positions or with different styles on the same image.
- Use the 'Defer building' option for text field formatters to improve page load times by generating images on a separate request.
- For best performance with high-traffic sites, ensure generated images are served through a CDN or reverse proxy cache.
- The text separator for URL generation (default: ---) can be customized, but avoid using characters that might appear in your text content.
- Set the Image destination to 'private' in image style Textimage options if you need access control for generated images.
- Temporary Textimage files (created with setTemporary(TRUE) in the API) are automatically cleaned up during cron runs.
Technical Details
Admin Pages 2
/admin/config/media/textimage
Configure global Textimage settings including default image format, default font, URL generation options, and maintenance utilities.
/admin/config/media/textimage/cleanup
Confirmation form to remove all image files generated via Textimage, flush all the image styles, and clear the Textimage cache.
Permissions 1
Hooks 8
hook_file_download
Controls access to files underneath the textimage directories. Returns appropriate headers for valid images in the textimage path.
hook_cron
Cleans up temporary Textimage image files from all available file schemes on cron runs.
hook_cache_flush
Returns 'textimage' as a cache bin to be flushed during cache clear operations.
hook_token_info
Defines Textimage tokens for retrieving URI and URL of generated images.
hook_tokens
Provides replacements for Textimage tokens based on node field configurations.
hook_image_style_flush
Handles Textimage-specific cleanup when an image style is flushed.
hook_image_style_presave
Sets default Textimage third-party settings on image styles before they are saved.
hook_form_image_style_form_alter
Adds a 'Textimage options' fieldset to image style edit forms for configuring Textimage-specific options.
Troubleshooting 6
Ensure you have created at least one image style that contains a 'Text overlay' effect from the Image Effects module. Only styles with Text overlay effects are recognized as Textimage-compatible.
Check that: 1) The font file is accessible and properly configured in Image Effects settings, 2) GD2 with FreeType is enabled in PHP, 3) The file system permissions allow writing to the public/private files directory.
Ensure the token context is available. Node tokens require the field to be attached to a node entity. User tokens use the current user. File tokens are only available for Image field formatters.
URL-based generation requires the 'Generate Textimage URL derivatives' permission. Grant this permission to the appropriate user roles.
Avoid using Textimage tokens within fields that are themselves being displayed as Textimage. The module detects and prevents infinite loops, logging a warning message.
Clear the Textimage cache using the 'Cleanup Textimage' button on the settings page, or flush the specific image style to regenerate cached images.
Security Notes 3
- URL-based generation is disabled by default. When enabled, only users with the 'Generate Textimage URL derivatives' permission can generate images via URL.
- Textimage respects file access controls - images stored in private file storage require proper access permissions to view.
- Token replacement is context-aware and only resolves tokens for which the user has access to the underlying data.