timber/timber
Timber
Timber is a PHP library that integrates the Twig template engine into WordPress themes, providing an object-oriented framework for theme development. It wraps WordPress data — posts, terms, users, menus, and comments — in structured PHP classes, allowing developers to work with objects instead of raw arrays while keeping HTML markup separate from PHP logic through Twig templates.
The library distinguishes itself by offering a complete set of tools for modern WordPress theme building. It includes a file-based template hierarchy with fallback chains, dynamic image manipulation with resizing, cropping, and responsive srcset generation, and a cache-as-you-go system that caches compiled templates and rendered output with configurable expiration. Timber also supports multisite management, custom object class mapping, and incremental theme adoption, letting developers replace parts of an existing theme piece by piece. It provides WP-CLI commands for cache management and data inspection, and enables direct PHP function calls from Twig templates without writing custom filters or extensions.
Beyond its core identity, Timber covers a broad surface of content and media handling. It offers object-oriented access to posts, pages, menus, comments, users, and taxonomies, with pagination, metadata retrieval, and rendering for template display. The library includes tools for navigation menu building, comment threading, excerpt generation, and shortcode processing, as well as integration with Advanced Custom Fields and WooCommerce. It also provides debugging features like template origin tracing and variable inspection, security measures such as autoescaping and content sanitization, and internationalization support with string translation in Twig templates and .pot file extraction via WP-CLI.
Features
- Object-Oriented Data Wrappers - Wraps WordPress posts, terms, users, and menus in PHP classes for structured data access in templates.
- Theme Development Frameworks - Provides structured PHP classes for posts, terms, users, and menus as a theme development framework.
- Twig Engine Integrations - Integrates the Twig template engine into WordPress to separate PHP logic from HTML markup.
- WordPress Post Queries - Executes WordPress queries and returns PostCollection objects for template rendering.
- WordPress - Wraps WordPress data in object-oriented classes and renders it through Twig templates.
- WordPress Post Retrievals - Queries WordPress posts using standard arguments and returns Post object collections.
- Post Taxonomy Term Lists - Returns assigned categories, tags, and custom terms as structured objects for template iteration.
- Template Variable Metadata Exposers - Exposes post properties like title, date, author, permalink, and featured image as template variables.
- Template Variable Post Renderers - Outputs post content, permalink, title, and tags through template variables instead of template tags.
- Global Site Metadata - Exposes WordPress site settings like charset, description, name, and URL as template variables.
- Object-Oriented Post Managers - Provides an object-oriented interface for accessing and manipulating WordPress post content and metadata.
- WordPress Navigation Menu Renderings - Renders WordPress navigation menus as tree objects with configurable depth and location.
- WordPress Content Object Retrievals - Retrieves collections of WordPress content objects via a dedicated factory function.
- WordPress Object Converters - Converts WordPress objects like WP_Post into Timber classes for structured template access.
- Default Context Assemblers - Assembles an array of default context data for use across Twig templates.
- WordPress Theme Starter Kits - Creates custom WordPress themes using structured data objects and template inheritance.
- Post Subclass Extensions - Creates custom subclasses of post objects to add theme-specific data and methods for templates.
- Cache-As-You-Go Renderers - Implements a cache-as-you-go system that caches compiled templates and rendered output with configurable expiration.
- Data Pagination - Creates structured arrays of pagination links and page numbers for query results.
- Plugin-Filtered Meta Value Accesses - Retrieves custom field values filtered by third-party plugins for consistent data access.
- WordPress Post Fetchers - Fetches WordPress posts as structured objects with methods for content, metadata, and related data.
- WordPress Term Retrievals - Queries WordPress taxonomy terms and returns them as structured Timber Term objects.
- Polymorphic Object Retrievers - Retrieves WordPress objects through common properties like slug, ID, and name for consistent access.
- Template Extensions - Registers custom Twig filters and functions so PHP helpers are callable directly inside template files.
- Block Inheritance Overrides - Extends a parent layout by overriding named block sections, reusing shared structure while customizing specific content areas.
- Site Data Context Builders - Builds a pre-filled array of common site data like name, description, and menus for use in templates.
- Direct PHP Function Calls - Enables direct invocation of any PHP function from Twig templates without custom filters or extensions.
- PHP Function Invocations - Ships a mechanism to call any PHP function directly from Twig templates without custom filters.
- Site Context Resolvers - Returns a data object with common site values like name, description, and navigation for templates.
- Dimension-Constrained Resizing - Crops or scales an image to exact dimensions while preserving aspect ratio, with configurable crop position.
- Dimension Resizing - Scales an image to a given width and height while preserving proportions using WordPress's image API.
- WordPress Image Size URL Retrievals - Returns image URLs at specified WordPress-registered sizes for responsive template display.
- WordPress Content Filter Renderers - Outputs post content with all WordPress filters and actions applied in Twig templates.
- Template - Specifies an ordered list of template files so the system tries each one and uses the first that exists.
- WordPress Post Query Builders - Retrieves posts by type, taxonomy, or custom criteria using a fluent query builder interface.
- User Capability Verifications - Tests whether a user has a specific WordPress capability and returns a boolean result.
- Template Variable Exposures - Exposes WordPress post properties and methods as Twig variables for dynamic content output.
- Content Taxonomies - Provides structured methods for retrieving and displaying taxonomy term data and relationships.
- WordPress Content Object Retrievers - Retrieves any single WordPress content object via a unified factory function.
- Gutenberg Block Renderers - Renders all Gutenberg blocks automatically when outputting post content through the template engine.
- Custom Data Fields - Reads and writes post meta values, including Advanced Custom Fields data, through a unified interface.
- Image Retrievals from Custom Fields - Converts image IDs from custom fields into template-ready image objects for display.
- Escaped User Content Renderers - Escapes user-supplied content in Twig templates to prevent XSS vulnerabilities.
- File-Based Template Inclusion - Loads a Twig template file based on a runtime variable for conditional or data-driven partial rendering.
- Fallback Chain Hierarchies - Loads templates by following a fallback chain of file names based on post type, slug, and template header.
- Media Attachments - Provides structured methods for retrieving and displaying attachment metadata, URLs, and embedded media.
- Navigation Menu Builders - Generates hierarchical menu objects for rendering custom navigation structures in templates.
- Slug-Based Page Overrides - Creates dedicated Twig or PHP files for specific pages using slug or template header overrides.
- Post Body Renderers - Outputs post body text with WordPress filters, shortcodes, and wpautop applied for formatting.
- Query-Based Template Context Population - Automatically sets common template variables like post or posts based on the current WordPress query.
- File-Based Template Outputters - Passes data to a Twig file and echoes the compiled output directly to the browser.
- WordPress Integrations - Replaces WordPress's native template system with Twig, enabling custom filters, functions, and template inheritance.
- Current URL Readers - Retrieves the full URL of the current page being viewed on the WordPress site.
- High-DPI Image Variant Creators - Creates higher-resolution image variants for high-DPI screen display.
- Retina-Ready Image Variant Creators - Creates high-resolution @2x image variants for retina display srcset attributes.
- Template-Based Query Builders - Runs WordPress post queries directly inside Twig templates using query parameter hashes.
- Predefined Image Size Outputs - Outputs images at predefined WordPress-registered sizes for consistent display.
- Pagination Renderers - Renders numbered page links with previous/next navigation for browsing paginated content.
- Registered Image Size Selectors - Outputs images at predefined WordPress-registered sizes for consistent display.
- URL-Based Manipulation - Resizes, crops, and applies filters to images via URL parameters without modifying original files.
- Comment Author Avatars - Outputs configurable Gravatar images for comment authors in Twig templates.
- Single Comment Renderers - Renders individual comments with author, content, date, and reply link in Twig templates.
- Comment Retrievals - Retrieves a specific comment by its numeric ID for custom processing in templates.
- Comment Meta Retrievals - Retrieves custom metadata field values associated with comments for use in templates.
- Template Directory Configurations - Configures one or more custom folders where the system searches for template files, overriding the default location.
- PHP Template Loaders - Loads PHP template files with custom query parameters and data, optionally setting HTTP status codes.
- Content Page Splitters - Splits long content into pages and provides navigation links between them.
- Adjacent Post Navigators - Retrieves previous or next posts in a sequence, optionally restricted to the same taxonomy term.
- Attachment Retrievals - Retrieves WordPress attachment objects, including non-image files like PDFs, by ID or URL.
- Author Byline Renderers - Renders author bylines in templates using a simple block that pulls post author data.
- Excerpt Option Modifiers - Creates short text summaries from post content with configurable read-more links and end strings.
- Forced Word Count Trimmers - Forces post excerpts to a specific word length, overriding longer excerpts and stripping HTML tags.
- Slug-Based Template Selectors - Selects a custom template for a specific post based on its slug, following the standard content hierarchy.
- Content Excerpt Extractors - Truncates post content to a specified length with optional append text for previews.
- Plugin and Theme Metadata - Reads formatted and translated theme headers like Name, Description, or Author for display.
- Excerpt Read-More Link Appendices - Appends configurable read-more links to trimmed post excerpts for navigation.
- Object-Oriented Site Data Access - Provides object-oriented access to site-wide settings and metadata for use in templates.
- Site Switching - Provides programmatic site switching within WordPress Multisite networks via an object-oriented interface.
- Multisite Site Retrievals - Fetches all sites in a WordPress Multisite network as structured Site objects.
- Navigation Link Renderings - Outputs clickable navigation links with URLs and labels for site menu rendering.
- User Object Instantiators - Instantiates user objects from WordPress user IDs for use in Twig templates.
- Unfiltered Meta Value Accessors - Retrieves custom field values directly from the database bypassing plugin filters.
- Function Output Captures - Buffers a function's direct output and returns it as a string for use in template context variables.
- Output Buffer Captures - Calls a function that outputs text and captures the result into a string for use within a Twig template.
- Theme Path Variables - Returns the relative filesystem path to the theme directory for template resolution.
- Transient Caches - Stores and retrieves cached data using configurable expiration and race-condition locking.
- Template Caches - Caches compiled Twig templates and rendered output to reduce database queries and speed up page loads.
- Fragment Caches - Caches specific template sections using labels and data hashes for fine-grained control.
- Twig Repeater Field Iterators - Iterates over repeater field entries directly in Twig templates for content display.
- Template Date Formatters - Formats dates in Twig templates using WordPress timezone and date settings.
- Template Output Caches - Caches rendered template output to reduce database queries and improve page load times.
- Post Object Converters from Relationship Fields - Converts relationship field data into full post objects with template methods.
- Custom Pagination Markups - Outputs raw pagination HTML that developers can wrap in their own template markup for full design control.
- Paginated Results - Generates paginated navigation links for WordPress query results with previous/next controls.
- Twig Compilation Caches - Caches compiled Twig templates to skip recompilation on each request and speed up rendering.
- Term-Assigned Post Queries - Retrieves posts assigned to the current term with configurable count, post type, and query arguments.
- User Data Management - Provides an object-oriented interface for accessing WordPress user profile data in templates.
- Collection Pagination Utilities - Generates pagination data for a set of posts with page numbers, links, and navigation metadata.
- Relative Time Humanization - Displays dates in human-friendly relative time format like 3 days ago.
- Nested Commenting - Provides nested comment listing for threaded display in WordPress comment templates.
- Twig Filter Integrations - Runs user-defined WordPress filters inside Twig templates using apply_filters for extensibility.
- Looping Content Blocks - Outputs flexible content field layouts by looping through each block in a Twig template.
- Inline Function Renderers - Executes a function at its exact template position so its output appears where the function is called.
- Non-Attachment Image Loaders - Loads images that are not WordPress attachments, such as from theme folders or external URLs.
- Image Format Conversion - Changes an image file from one format to another, such as PNG to JPG or to WebP.
- URL Image Downloaders - Downloads an image from an external URL into a dedicated folder and returns an image object for templates.
- Image Manipulation - Resizes, crops, and converts images on the fly using the WordPress image API with srcset generation.
- Filterable Class Maps - Controls which PHP class is instantiated for each Timber object type through filterable class maps.
- Template Function Argument Passings - Supplies additional parameters after the function name to call the function with those arguments.
- Transient Helpers - Simplifies checking, saving, and retrieving cached values for expensive-to-generate data.
- Twig Function Registrations - Adds PHP functions as native Twig functions, making them callable without the function() prefix.
- Incremental Adoption Adapters - Replaces parts of an existing WordPress theme piece by piece without requiring a full rewrite.
- Plugin Integrations - Manages third-party plugin integrations through a centralized filter system for initialization and replacement.
- Threaded Comment Management - Builds and displays custom threaded comment trees beyond WordPress default structures.
- Post Comment Fetchers - Fetches comments on a post as a threaded collection and provides a comment form for user input.
- Active Menu Item Indicators - Reports whether a menu item matches the current page, its parent, or an ancestor for highlighting.
- Fixed-Size Image Letterboxers - Fits an image into a specified box by adding a background color to fill empty space when proportions don't match.
- ACF Block Registrations - Registers ACF blocks with Twig templates as render callbacks, passing block data to views.
- Manual Excerpt Respecters - Creates post excerpts or previews that respect manual excerpts and the <!--more--> tag.
- Automatic Page-Based Menu Builders - Generates menu objects automatically from existing site pages when no registered menu is found.
- Menu Item State Property Accesses - Exposes current, parent, and ancestor status on menu items for conditional display logic.
- Nested Block Overrides - Overrides nested block sections within inherited templates to customize specific page regions without altering the parent layout.
- Shortcodes - Processes WordPress shortcodes within post content, rendering galleries and custom elements.
- Twig Filter Registrations - Registers custom PHP functions as Twig filters to transform data within template expressions.
- User Meta Retrievals - Retrieves arbitrary metadata or custom fields attached to user records for template display.
- Term Meta Retrievals - Retrieves custom field values stored on taxonomy terms, including ACF fields and native term meta.
- Comment Form Overrides - Overrides default comment form markup with custom Twig templates for full design control.
- Child Menu Item Retrievals - Ships a method to retrieve nested sub-menu items for building hierarchical navigation menus.
- Custom Field Accesses on Menu Items - Retrieves custom field values stored on menu items for advanced navigation customization.
- Object Retrievals - Returns arrays of menu item objects for programmatic navigation building in templates.
- Source Object Retrievals - Returns the underlying WordPress object that a menu item represents for deeper data access.
- Image Letterboxers - Fits an image into specified dimensions by adding colored bands around it to maintain original aspect ratio.
- WordPress Sidebar Loaders - Renders WordPress sidebar template files with optional data for display.
- WordPress Widget Area Renderers - Outputs WordPress's built-in dynamic sidebar widget area within a Twig template.
- Shortcode and Widget Renderers - Builds WordPress shortcodes and widgets whose output is rendered through Twig template files.
- Structured Theme Data Access - Retrieves and displays theme information and settings using structured object-oriented methods.
- Embedded Comment Threads - Renders lists of comments with support for both flat and threaded display structures.
- Comment Parentage Detections - Detects whether a comment is a child of another for threaded comment display logic.
- Reply Link Generators - Generates threaded reply links that enqueue the required WordPress JavaScript for comment forms.
- Twig Shortcode Processors - Processes WordPress shortcodes within Twig template output for dynamic content.
- Date and Time Formatting - Converts date strings into localized, human-readable formats for display in templates.
- Size Attribute Generators - Generates responsive image size attribute strings from registered WordPress sizes.
- Cached Template Retrievers - Retrieves the compiled output of a Twig file, optionally caching the result for a set duration.
- String-Based Template Compilers - Compiles a string containing Twig variables with provided data and returns the result.
- String-Based Template Outputters - Compiles a string with Twig variables and echoes the result directly to the browser.
- Twig-Based Shortcode Renderers - Renders WordPress shortcode output using Twig template files.
- Global Menu Registrations - Adds menus to the global template context so they are available on every page without repeated initialization.
- Srcset Attribute Generators - Generates srcset attribute strings with URLs for multiple image sizes.
- WooCommerce Product Renderers - Renders single WooCommerce product pages with Twig templates, preserving extension hooks.
- Slug Generators - Converts titles or phrases into lowercase, hyphen-separated URL-safe slugs.
- Template User Profile Exposers - Exposes user profile properties like name, avatar, and roles for template rendering.
- WordPress Page Title Retrievers - Returns formatted WordPress page titles with configurable separator and position.
