Download the PHP package lxbdr/wp-template-helper without Composer

WpTemplateHelper

Use it to wrap data and get escaped output automatically checking for existence.

Simple example:

Data Access & Escaping

The WpTemplateHelper class provides a convenient and secure way to handle nested data structures and output content safely in WordPress templates. It includes various methods for data access and escaping.

Basic Data Access

Constructor

Accessing Data

Using get()

Retrieves raw data from the specified key. Returns empty string if not found.

Using has()

Checks if a key exists in the data structure. It uses isset under the hood and returns true for non-empty values.

Using notEmpty() / empty()

Check if a value exists and is not empty.

Raw Output

Using raw()

Outputs the raw value without any escaping. Use with caution!

Using __invoke()

Shorthand for HTML-escaped output. Same as calling html().

Secure Output Methods

HTML Content

URLs

HTML Attributes

JavaScript Content

XML Content

Methods Overview

Output Methods (Echo)

• html($key) - Escape HTML entities
• safeHtml($key) - Allow safe HTML tags
• url($key) - Escape URLs
• attr($key) - Escape HTML attributes
• js($key) - Escape JavaScript strings
• xml($key) - Escape XML content
• raw($key) - Raw output (unescaped)

Return Methods

• _html($key) - Return escaped HTML
• _safeHtml($key) - Return HTML with safe tags
• _url($key) - Return escaped URL
• _attr($key) - Return escaped attribute
• _js($key) - Return escaped JavaScript
• _xml($key) - Return escaped XML
• get($key) - Return raw value

Data Access Methods

• has($key) - Check key existence
• empty($key) - Check if empty
• notEmpty($key) - Check if not empty

Best Practices

1. Always Use Appropriate Escaping

2. Use Dot Notation for Nested Data

3. Combine with HTML Structure

4. Use Return Methods for Variable Assignment

Security Note

• Always use the appropriate escaping method for the context
• Never use raw() for user-provided data
• Use safeHtml() when you need to allow specific HTML tags
• Consider context when choosing between html() and attr()

Utility Methods

The WpTemplateHelper class provides several utility methods for common template operations. These methods can be used both statically and as instance methods.

Class Methods

clsx() - Dynamic Class Names

Combines class names based on conditions. Similar to the popular classnames JavaScript library.

Output:

style() - Inline Styles

Generates inline CSS style strings. Handles conditional styles and value filtering.

Output:

attributes() - HTML Attributes

Generates HTML attribute strings with proper escaping.

Output:

heading() - Semantic Headings

Creates semantic heading elements with attributes. Validates heading tags.

Output:

maybeAnchorTag() - Conditional Links

Creates either an anchor tag or alternative element based on link presence.

Output:

withLineBreaks() - Line Break Formatting

Joins array elements with line breaks, filtering empty values.

Output:

Using Return Methods

All methods have a corresponding return version prefixed with underscore (_):

Best Practices

1. Use Type-Appropriate Methods

   • Use clsx() for dynamic class names
   • Use style() for inline styles
   • Use attributes() for HTML attributes
   • Use heading() for semantic headings
   • Use maybeAnchorTag() for conditional links
   • Use withLineBreaks() for formatted text blocks

2. Choose Static vs Instance Methods

   • Use static methods for standalone utilities
   • Use instance methods when working with template data
3. Combine with Data Access

ID Management

The WpTemplateHelper provides methods for generating and managing unique IDs for HTML elements. Each instance maintains its own ID prefix to ensure uniqueness across multiple template instances.

id() / _id() - Prefixed IDs

Generates a unique, prefixed ID for HTML elements. The prefix is automatically generated and helps prevent ID collisions when multiple instances of templates are used on the same page.

Output:

getIdPrefix() - Current Prefix

Retrieves the current ID prefix being used by the instance.

regenerateIdPrefix() - New Prefix

Forces generation of a new random ID prefix. Useful when you need to ensure a fresh set of IDs.

Common Use Cases

ARIA Relationships

Forms and Labels

Best Practices

The main reason to use this helper is to prevent duplicate IDs in templates which are used multiple times on the same page. This can cause issues with JavaScript, CSS, and accessibility. Keep in mind that the ID prefix is unique to each instance of the helper and is randomly generated on instantiation.

Image functions

WpTemplateHelper provides methods for handling and rendering various types of images in WordPress templates. It supports basic images, responsive images, and advanced image configurations with custom styling and layout options.

Basic Image Methods

img($key, $size = 'full', $atts = '')

_img($key, $size = 'full', $atts = '')

Renders/returns an HTML image element based on the provided key. Supports various input formats including image IDs, URLs, and arrays with metadata.

Responsive Image Methods

responsiveImg($key)

_responsiveImg($key)

Generates HTML for a responsive image with multiple sources based on media queries.

Advanced Image Methods

advancedImg($key)

_advancedImg($key)

Renders an image with advanced configuration options including custom sizing, focal points, and object-fit properties.

Available Sizing Options

• width-full-height-full: Image takes full width and height of container
• width-full-height-auto: Image takes full width with auto height
• width-auto-height-full: Image takes full height with auto width
• width-auto-height-auto: Image dimensions are automatic

Object Fit Options

• cover: Image covers the entire container
• contain: Image is contained within the container

Display Options

• block: Display as block element
• inline-block: Display as inline-block element

CSS Integration

The trait provides a static method getAdvancedImgCss() that returns the necessary CSS for advanced image features. Include this CSS in your theme or plugin:

ACF Integration

WpTemplateHelper provides a method to register field groups which contain all fields for using the advanced image feature. Call registerAdvancedImgAcfFields() to register the field groups with ACF. The field names are not prefixed and meant to be used in a clone field within a group. Important: The clone field should be a subfield of a group field otherwise it might not save correctly if multiple images/clone fields are used.

Example usage in a group:

Notes

• The trait relies on WordPress core functions for image handling
• Images are automatically escaped for security
• All methods prefixed with underscore (e.g., _img()) return the HTML string instead of echoing
• Responsive images automatically use WordPress's built-in srcset and sizes attributes
• Advanced image configurations support CSS custom properties for dynamic styling

Best Practices

1. Always provide alt text for accessibility
2. Use responsive images for better performance on different devices
3. Consider using advanced image configuration for complex layouts
4. Set appropriate focal points for images that will be cropped
5. Include the CSS when using advanced image features