Twig templating support with Timber + Timber cache integration

Bootstrapping and global context

• Core classes
  • inc/WP/Site.php extends Timber\Site, wires global context and class maps.
  • inc/WP/Twig.php extends Twig with custom functions.
  • inc/WP/Cache.php configures Timber cache and Twig env options.
• Global context additions (Site::add_to_context() in inc/WP/Site.php)
  • logo → Components::get_logo()
  • menus → Components::get_menus()
  • sidebar → Components::get_sidebar()
  • footer_sidebars → Components::get_footer_sidebars()
  • the_title → Components::get_the_title()
• Class maps (typed Timber objects)
  • timber/post/classmap → maps post, page, product, attachment to custom classes
  • timber/term/classmap → maps category, product_cat to custom classes
• Templates are under views/:
  • Objects/partials like views/objects/icon.twig
  • Page templates index.php, single.php, etc., call Timber::render(...)/Timber::compile(...).

Twig functions (helpers)

Defined in inc/WP/Twig.php via timber/twig:

• get_nav_menu(name) → fetch from context['menus']
• timber_set_product(post) → WooCommerce helper
• post_classes(classes, prefix='c-post--') → ITCSS-friendly classnames
• slider_prepare_params(params) → prepares data-* attributes/values
• get_responsive_image(id, size='medium', attrs=[]) → responsive <img> HTML
• comments_template() → comments list + form
• bem(name, ...modifiers) → BEM class builder via ThemeHelpers::bem()
• breadcrumbs()→ Yoast breadcrumbs (if plugin active)
• get_icon(args) → renders views/objects/icon.twig and caches result

Usage example (Twig):

<nav class="c-nav">
  {{ get_nav_menu('primary') }}
</nav>

{{ get_responsive_image(post.thumbnail_id, 'large') }}

<div class="{{ bem('c-card', 'featured', is_preview ? 'preview' : false) }}"></div>

<nav class="c-nav">
  {{ get_nav_menu('primary') }}
</nav>

{{ get_responsive_image(post.thumbnail_id, 'large') }}

<div class="{{ bem('c-card', 'featured', is_preview ? 'preview' : false) }}"></div>

Blocks + Twig locations

Twig templates for blocks are discovered automatically:

• Native: inc/WP/Blocks.php::tiwg_files_locations() adds src/blocks/{block}/ to timber/locations
• ACF: inc/WP/AcfBlocks.php::tiwg_files_locations() adds src/blocks-acf/{block}/
• Rendering:
  • Native helper: BlocksHelpers::render_twig_file(blockName, context) → renders build/blocks/{block}/{block}.twig path (base configured in Blocks::$blocks_twig_base_path)
  • ACF rendering: BlocksHelpers::acf_block_render(…) resolves {block}.twig under build/blocks-acf/{slug}/ with CacheHelpers::expiry(), after enriching context (fields, classes, wrapper attributes)

Caching and environment

• inc/WP/Cache.php
  • timber/cache/mode → Loader::CACHE_USE_DEFAULT (can be filtered)
  • timber/twig/environment/options:
    • cache toggled by chisel_environment_cache
    • auto_reload and debug follow ThemeHelpers::is_dev_env()
  • CacheHelpers::expiry() controls compile cache TTL used in multiple places.

Practical tips:

• For dev, Twig auto-reload and debug are on.
• For prod, enable Twig cache (set WP_DEBUG false and allow chisel_environment_cache).

Typical render flow

• A WP template (e.g., page.php) builds $context = Timber::context() → includes logo, menus, etc.
• It calls Timber::render('views/page.twig', $context)
• Inside Twig, use the registered functions to render menus, images, icons, breadcrumbs, etc.
• Blocks (native/ACF) render their Twig files automatically via the block lifecycle classes.

Where to put your templates

• Page/Archive templates → views/ (e.g., views/page.twig, views/single.twig)
• Shared objects/partials → views/objects/ (e.g., icon.twig)
• Block-specific Twig → co-locate in:
  • src/blocks/{block}/ (native)
  • src/blocks-acf/{block}/ (ACF)
  • The locations are auto-added to Timber by the block classes.

How class maps work

Timber’s class maps let you replace generic Timber\Post, Timber\Term, and Timber\Image with your own rich domain objects – automatically and predictably.

• Stronger domain model: Attach real behavior to content types (e.g., ChiselProduct::get_thumbnail(), ChiselProductCategory::get_thumbnail()), not scattered helper calls.
• Cleaner Twig: Move logic into methods, so templates stay declarative: {{ product.get_thumbnail() }} instead of inline PHP / logic.
• Consistency across the site: Every instance of a CPT/taxonomy uses the same API, reducing bugs and copy‑paste.
• Easier testing and refactoring: Centralize behavior in classes; update once, propagate everywhere.
• WooCommerce‑aware defaults: Graceful fallbacks (placeholder images, size filters) live inside ChiselProduct/ChiselProductCategory, not in your templates.

Existing custom Timber classes

• inc/WP/ChiselPost.php extends Timber\PostAdds helpers like get_thumbnail() that returns responsive HTML via ImageHelpers.
• inc/WP/ChiselProduct.php extends Timber\PostWooCommerce‑aware; resolves placeholder IDs and renders responsive thumbnails.
• inc/WP/ChiselImage.php extends Timber\ImageAdds responsive($size, $attrs) for attachment images.
• inc/WP/ChiselTerm.php extends Timber\TermBase term class.
• inc/WP/ChiselProductCategory.php extends Timber\Term . Provides category thumbnails with Woo placeholder fallback.

Extending with your own CPT and taxonomy

1. Create a custom Post class

• File: inc/WP/ChiselMovie.php
• Namespace: Chisel\WP
• Extend Timber\Post and add your domain logic.

<?php
namespace Chisel\WP;

use Timber\Post as TimberPost;

class ChiselMovie extends TimberPost {
  public function rating_badge() {
    return $this->meta( 'rating' ) ? 'Rated: ' . esc_html( $this->meta( 'rating' ) ) : '';
  }
}

<?php
namespace Chisel\WP;

use Timber\Post as TimberPost;

class ChiselMovie extends TimberPost {
  public function rating_badge() {
    return $this->meta( 'rating' ) ? 'Rated: ' . esc_html( $this->meta( 'rating' ) ) : '';
  }
}

2. Map your CPT to the class

• In inc/WP/Site.php → post_classmap() add:

<?php
$custom_classmap = array(
  // ...
  'movie' => ChiselMovie::class,
);

<?php
$custom_classmap = array(
  // ...
  'movie' => ChiselMovie::class,
);

3. Create a custom Term class (optional)

• File: inc/WP/ChiselGenre.php
• Extend Timber\Term and add helpers.

<?php
namespace Chisel\WP;

use Timber\Term as TimberTerm;

class ChiselGenre extends TimberTerm {
  public function icon() {
    return $this->meta( 'icon' ) ?: 'default';
  }
}

<?php
namespace Chisel\WP;

use Timber\Term as TimberTerm;

class ChiselGenre extends TimberTerm {
  public function icon() {
    return $this->meta( 'icon' ) ?: 'default';
  }
}

4. Map your taxonomy to the class

• In inc/WP/Site.php → term_classmap() add:

<?php
$custom_classmap = array(
  // ...
  'genre' => ChiselGenre::class,
);

<?php
$custom_classmap = array(
  // ...
  'genre' => ChiselGenre::class,
);

Using in Twig and PHP

• Twig: The objects auto‑upgrade to your classes:
  • {{ post.get_thumbnail('large') }} (from ChiselPost)
  • {{ product.get_thumbnail() }} (from ChiselProduct)
  • {{ term.get_thumbnail() }} for product_cat (from ChiselProductCategory)
  • {{ image.responsive('medium', { class: 'c-image' }) }} (from ChiselImage)
• PHP: Timber::get_post() and Timber::get_terms() return your mapped classes automatically.

Tips

• Keep classes under inc/WP/ with namespace Chisel\WP to match existing patterns.
• Map the CPT slug/taxonomy name exactly (e.g., movie, genre).
• Add lazy properties or helpers (like get_thumbnail()) to keep Twig clean and logic‑light.

Summary

• Timber is initialized via Site, extended via Twig, and optimized via Cache.
• Global context is enriched with logo, menus, sidebars, and computed titles.
• Rich Twig utilities simplify rendering menus, BEM classes, responsive images, breadcrumbs, icons, sliders, and comments.
• Block Twig templates are auto-discovered from src/blocks/** and src/blocks-acf/**, aligning with your block system.