A comprehensive WordPress utility library providing reusable components, helpers, and utilities for modern WordPress development.
- PHP >= 8.1
- WordPress >= 6.4
Install via Composer:
composer require builtnorth/wp-utility
In your plugin or theme, initialize WP Utility:
if (class_exists('BuiltNorth\WPUtility\App')) {
$utility = BuiltNorth\WPUtility\App::instance();
$utility->boot();
}
Components provide reusable UI elements with consistent APIs.
Creates accessible card components with proper ARIA attributes:
use BuiltNorth\WPUtility\Components\Component;
Component::accessibleCard(
url: 'https://example.com',
title: 'Card Title',
new_tab: true,
class: 'custom-card-class'
);
Generates semantic breadcrumb navigation:
Component::breadcrumbs(
show_on_front: true,
class: 'breadcrumbs',
separator: '»',
home_title: 'Home',
prefix: 'You are here:'
);
Filters:
wp_utility_breadcrumb_open_nav
- Customize opening navigation HTMLwp_utility_breadcrumb_close_nav
- Customize closing navigation HTMLwp_utility_breadcrumb_item
- Customize individual breadcrumb itemswp_utility_breadcrumb_separator
- Customize separator HTML
Renders flexible button or link elements:
Component::button(
button_type: 'a',
class: 'btn',
extra_class: 'custom-btn',
style: 'primary',
size: 'large',
appearance: 'fill',
text: 'Click Me',
link: 'https://example.com',
target: '_blank',
screen_reader: 'Opens in new window',
attributes: ['data-tracking' => 'button-click'],
icon: '<svg>...</svg>',
icon_position: 'left'
);
Filter:
wp_utility_button_block_prefix
- Customize button class prefix
Advanced image rendering with responsive sizes:
Component::image(
id: 123,
class: 'featured-image',
additional_classes: 'rounded shadow',
custom_alt: 'Custom alt text',
show_caption: true,
lazy: true,
wrap_class: 'image-wrapper',
include_figure: true,
size: 'wide_large',
max_width: '1200px',
style: 'border-radius: 8px;',
caption: 'Image caption text',
alt: 'Alt text override'
);
Generates accessible pagination for WordPress queries:
Component::pagination(
query: $custom_query // WP_Query object (optional, uses global $wp_query if not provided)
);
Filters:
wp_utility_pagination_args
- Modify pagination argumentswp_utility_pagination_wrapper
- Customize wrapper attributes
Utilities provide data processing and retrieval functions.
Handles conversion of pretty permalinks to query string URLs for archive pages:
use BuiltNorth\WPUtility\Utilities\Utility;
Utility::archiveUrl();
Returns an array of countries with ISO codes:
$countries = Utility::countryList();
// Returns: ['US' => 'United States', 'CA' => 'Canada', ...]
Renders terms for a post:
Utility::getTerms(
post_id: get_the_ID(),
taxonomy: 'category',
taxonomy_link: true,
first_term_only: false,
class: 'post-terms'
);
Retrieves appropriate page title across different WordPress contexts:
$title = Utility::getTitle();
Controls lazy loading behavior for blocks:
$should_lazy = Utility::lazyLoadFirstBlock(
block: $block,
non_lazy_parents: ['core/columns', 'core/group'],
default_lazy: true
);
Filter:
wp_utility_lazy_load_non_lazy_parents
- Modify non-lazy parent blocks
Calculates estimated reading time:
$minutes = Utility::readingTime();
Filter:
wp_utility_reading_time_wpm
- Customize words per minute (default: 200)
Returns an array of US states:
$states = Utility::stateList();
// Returns: ['AL' => 'Alabama', 'AK' => 'Alaska', ...]
Helpers provide utility functions for common tasks.
Safely escapes SVG content for output:
use BuiltNorth\WPUtility\Helpers\Helper;
$safe_svg = Helper::escapeSvg($svg_content);
Setup classes handle WordPress configuration and initialization.
Configures custom image sizes and removes WordPress defaults.
use BuiltNorth\WPUtility\Setup\ImageSetup;
ImageSetup::setup();
-
Wide formats:
wide_xlarge
: 1600px widewide_large
: 1200px widewide_medium
: 800px widewide_small
: 600px widewide_xsmall
: 300px wide
-
Square formats (cropped):
square_xlarge
: 1200x1200square_large
: 800x800square_medium
: 600x600square_small
: 300x300square_xsmall
: 150x150
wp_utility_image_sizes
- Customize image sizes arraywp_utility_image_size_names
- Customize display nameswp_utility_remove_default_sizes
- Control which default sizes to removewp_utility_max_srcset_width
- Set maximum srcset width (default: 1600)
add_filter('wp_utility_image_sizes', function($sizes) {
$sizes['banner'] = [1920, 600, true];
$sizes['thumbnail_large'] = [400, 400, true];
return $sizes;
});
add_filter('wp_utility_image_size_names', function($names) {
$names['banner'] = __('Banner Image');
$names['thumbnail_large'] = __('Large Thumbnail');
return $names;
});
All components, utilities, and helpers support multiple naming conventions:
// camelCase
Component::accessibleCard();
Utility::getTitle();
Helper::escapeSvg();
// PascalCase (PHP is case-insensitive for methods)
Component::AccessibleCard();
Utility::GetTitle();
Helper::EscapeSvg();
// snake_case (via magic methods)
Component::accessible_card();
Utility::get_title();
Helper::escape_svg();
The library maintains backward compatibility through class aliases:
BuiltNorth\WPUtility\Component
→BuiltNorth\WPUtility\Components\Component
BuiltNorth\WPUtility\Utility
→BuiltNorth\WPUtility\Utilities\Utility
BuiltNorth\WPUtility\Helper
→BuiltNorth\WPUtility\Helpers\Helper
BuiltNorth\WPUtility\Utilities\ImageSetup
→BuiltNorth\WPUtility\Setup\ImageSetup
Run the test suite:
composer test
See CONTRIBUTING.md for details on how to contribute to this project.
This package is licensed under the GPL version 2 or later. See LICENSE.md for details.
This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
Use of this library is at your own risk. The authors and contributors of this project are not responsible for any damage to your website or any loss of data that may result from the use of this library.
While we strive to keep this library up-to-date and secure, we make no guarantees about its performance, reliability, or suitability for any particular purpose. Users are advised to thoroughly test the library in a safe environment before deploying it to a live site.
By using this library, you acknowledge that you have read this disclaimer and agree to its terms.