PHPackages                             builtnorth/wp-utility - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. builtnorth/wp-utility

ActiveLibrary[Utility & Helpers](/categories/utility)

builtnorth/wp-utility
=====================

Utility functions and helpers for WordPress development

v2.3.1(2mo ago)1253[1 issues](https://github.com/builtnorth/wp-utility/issues)GPL-2.0-or-laterPHPPHP >=8.0CI passing

Since Jul 10Pushed 2mo agoCompare

[ Source](https://github.com/builtnorth/wp-utility)[ Packagist](https://packagist.org/packages/builtnorth/wp-utility)[ RSS](/packages/builtnorth-wp-utility/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (8)Versions (11)Used By (0)

WP Utility
==========

[](#wp-utility)

A comprehensive WordPress utility library providing reusable components, helpers, and utilities for modern WordPress development.

Requirements
------------

[](#requirements)

- PHP >= 8.1
- WordPress >= 6.4

Installation
------------

[](#installation)

Install via Composer:

```
composer require builtnorth/wp-utility
```

### Basic Setup

[](#basic-setup)

In your plugin or theme, initialize WP Utility:

```
if (class_exists('BuiltNorth\WPUtility\App')) {
    $utility = BuiltNorth\WPUtility\App::instance();
    $utility->boot();
}
```

Components
----------

[](#components)

Components provide reusable UI elements with consistent APIs.

### AccessibleCard

[](#accessiblecard)

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'
);
```

### Breadcrumbs

[](#breadcrumbs)

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 HTML
- `wp_utility_breadcrumb_close_nav` - Customize closing navigation HTML
- `wp_utility_breadcrumb_item` - Customize individual breadcrumb items
- `wp_utility_breadcrumb_separator` - Customize separator HTML

### Button

[](#button)

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: '...',
    icon_position: 'left'
);
```

**Filter:**

- `wp_utility_button_block_prefix` - Customize button class prefix

### Image

[](#image)

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'
);
```

### Pagination

[](#pagination)

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 arguments
- `wp_utility_pagination_wrapper` - Customize wrapper attributes

Utilities
---------

[](#utilities)

Utilities provide data processing and retrieval functions.

### ArchiveUrl

[](#archiveurl)

Handles conversion of pretty permalinks to query string URLs for archive pages:

```
use BuiltNorth\WPUtility\Utilities\Utility;

Utility::archiveUrl();
```

### CountryList

[](#countrylist)

Returns an array of countries with ISO codes:

```
$countries = Utility::countryList();
// Returns: ['US' => 'United States', 'CA' => 'Canada', ...]
```

### GetTerms

[](#getterms)

Renders terms for a post:

```
Utility::getTerms(
    post_id: get_the_ID(),
    taxonomy: 'category',
    taxonomy_link: true,
    first_term_only: false,
    class: 'post-terms'
);
```

### GetTitle

[](#gettitle)

Retrieves appropriate page title across different WordPress contexts:

```
$title = Utility::getTitle();
```

### LazyLoadFirstBlock

[](#lazyloadfirstblock)

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

### ReadingTime

[](#readingtime)

Calculates estimated reading time:

```
$minutes = Utility::readingTime();
```

**Filter:**

- `wp_utility_reading_time_wpm` - Customize words per minute (default: 200)

### StateList

[](#statelist)

Returns an array of US states:

```
$states = Utility::stateList();
// Returns: ['AL' => 'Alabama', 'AK' => 'Alaska', ...]
```

Helpers
-------

[](#helpers)

Helpers provide utility functions for common tasks.

### EscapeSvg

[](#escapesvg)

Safely escapes SVG content for output:

```
use BuiltNorth\WPUtility\Helpers\Helper;

$safe_svg = Helper::escapeSvg($svg_content);
```

Setup
-----

[](#setup)

Setup classes handle WordPress configuration and initialization.

### ImageSetup

[](#imagesetup)

Configures custom image sizes and removes WordPress defaults.

#### Manual Initialization

[](#manual-initialization)

```
use BuiltNorth\WPUtility\Setup\ImageSetup;

ImageSetup::setup();
```

#### Default Image Sizes

[](#default-image-sizes)

- **Wide formats:**

    - `wide_xlarge`: 1600px wide
    - `wide_large`: 1200px wide
    - `wide_medium`: 800px wide
    - `wide_small`: 600px wide
    - `wide_xsmall`: 300px wide
- **Square formats (cropped):**

    - `square_xlarge`: 1200x1200
    - `square_large`: 800x800
    - `square_medium`: 600x600
    - `square_small`: 300x300
    - `square_xsmall`: 150x150

#### Filters

[](#filters)

- `wp_utility_image_sizes` - Customize image sizes array
- `wp_utility_image_size_names` - Customize display names
- `wp_utility_remove_default_sizes` - Control which default sizes to remove
- `wp_utility_max_srcset_width` - Set maximum srcset width (default: 1600)

#### Example: Custom Image Sizes

[](#example-custom-image-sizes)

```
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;
});
```

Method Naming Conventions
-------------------------

[](#method-naming-conventions)

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();
```

Backward Compatibility
----------------------

[](#backward-compatibility)

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`

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Contributing
------------

[](#contributing)

See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.

License
-------

[](#license)

This package is licensed under the GPL version 2 or later. See [LICENSE.md](LICENSE.md) for details.

Disclaimer
----------

[](#disclaimer)

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.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance66

Regular maintenance activity

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~34 days

Recently: every ~57 days

Total

8

Last Release

72d ago

Major Versions

1.0.0 → 2.0.02025-07-13

PHP version history (2 changes)1.0.0PHP >=8.1

v2.3.1PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4ea760d2fc869dfda680e0bd6dce422606e91d6a1687938a8ebc38a0c29ca343?d=identicon)[dannorthern](/maintainers/dannorthern)

---

Top Contributors

[![dannorthern](https://avatars.githubusercontent.com/u/157666970?v=4)](https://github.com/dannorthern "dannorthern (97 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (3 commits)")

---

Tags

composercomposer-librarycomposer-packageutilityutilswordpresswp-utilities

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/builtnorth-wp-utility/health.svg)

```
[![Health](https://phpackages.com/badges/builtnorth-wp-utility/health.svg)](https://phpackages.com/packages/builtnorth-wp-utility)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)