{"id":15150634,"url":"https://github.com/builtnorth/wp-utility","last_synced_at":"2026-01-24T19:51:29.779Z","repository":{"id":251371930,"uuid":"837232209","full_name":"builtnorth/wp-utility","owner":"builtnorth","description":"Composer package containing utility items for use in WordPress themes and plugins.","archived":false,"fork":false,"pushed_at":"2025-08-30T18:11:54.000Z","size":144,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T20:23:20.523Z","etag":null,"topics":["composer","composer-library","composer-package","utility","utils","wordpress","wp-utilities"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/builtnorth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-02T13:47:49.000Z","updated_at":"2025-08-12T05:53:40.000Z","dependencies_parsed_at":"2024-08-02T15:02:52.341Z","dependency_job_id":"ee3013ed-0a9b-42c8-877b-c3bd2017b280","html_url":"https://github.com/builtnorth/wp-utility","commit_stats":{"total_commits":5,"total_committers":1,"mean_commits":5.0,"dds":0.0,"last_synced_commit":"33a541f49907a985d56223a39c1ce4e78ca192bf"},"previous_names":["builtnorth/wp-utility"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/builtnorth/wp-utility","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/builtnorth%2Fwp-utility","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/builtnorth%2Fwp-utility/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/builtnorth%2Fwp-utility/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/builtnorth%2Fwp-utility/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/builtnorth","download_url":"https://codeload.github.com/builtnorth/wp-utility/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/builtnorth%2Fwp-utility/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28735371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T19:23:36.361Z","status":"ssl_error","status_checked_at":"2026-01-24T19:23:28.966Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer","composer-library","composer-package","utility","utils","wordpress","wp-utilities"],"created_at":"2024-09-26T14:23:16.216Z","updated_at":"2026-01-24T19:51:29.774Z","avatar_url":"https://github.com/builtnorth.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP Utility\n\nA comprehensive WordPress utility library providing reusable components, helpers, and utilities for modern WordPress development.\n\n## Requirements\n\n- PHP \u003e= 8.1\n- WordPress \u003e= 6.4\n\n## Installation\n\nInstall via Composer:\n\n```bash\ncomposer require builtnorth/wp-utility\n```\n\n### Basic Setup\n\nIn your plugin or theme, initialize WP Utility:\n\n```php\nif (class_exists('BuiltNorth\\WPUtility\\App')) {\n    $utility = BuiltNorth\\WPUtility\\App::instance();\n    $utility-\u003eboot();\n}\n```\n\n## Components\n\nComponents provide reusable UI elements with consistent APIs.\n\n### AccessibleCard\n\nCreates accessible card components with proper ARIA attributes:\n\n```php\nuse BuiltNorth\\WPUtility\\Components\\Component;\n\nComponent::accessibleCard(\n    url: 'https://example.com',\n    title: 'Card Title',\n    new_tab: true,\n    class: 'custom-card-class'\n);\n```\n\n### Breadcrumbs\n\nGenerates semantic breadcrumb navigation:\n\n```php\nComponent::breadcrumbs(\n    show_on_front: true,\n    class: 'breadcrumbs',\n    separator: '»',\n    home_title: 'Home',\n    prefix: 'You are here:'\n);\n```\n\n**Filters:**\n\n- `wp_utility_breadcrumb_open_nav` - Customize opening navigation HTML\n- `wp_utility_breadcrumb_close_nav` - Customize closing navigation HTML\n- `wp_utility_breadcrumb_item` - Customize individual breadcrumb items\n- `wp_utility_breadcrumb_separator` - Customize separator HTML\n\n### Button\n\nRenders flexible button or link elements:\n\n```php\nComponent::button(\n    button_type: 'a',\n    class: 'btn',\n    extra_class: 'custom-btn',\n    style: 'primary',\n    size: 'large',\n    appearance: 'fill',\n    text: 'Click Me',\n    link: 'https://example.com',\n    target: '_blank',\n    screen_reader: 'Opens in new window',\n    attributes: ['data-tracking' =\u003e 'button-click'],\n    icon: '\u003csvg\u003e...\u003c/svg\u003e',\n    icon_position: 'left'\n);\n```\n\n**Filter:**\n\n- `wp_utility_button_block_prefix` - Customize button class prefix\n\n### Image\n\nAdvanced image rendering with responsive sizes:\n\n```php\nComponent::image(\n    id: 123,\n    class: 'featured-image',\n    additional_classes: 'rounded shadow',\n    custom_alt: 'Custom alt text',\n    show_caption: true,\n    lazy: true,\n    wrap_class: 'image-wrapper',\n    include_figure: true,\n    size: 'wide_large',\n    max_width: '1200px',\n    style: 'border-radius: 8px;',\n    caption: 'Image caption text',\n    alt: 'Alt text override'\n);\n```\n\n### Pagination\n\nGenerates accessible pagination for WordPress queries:\n\n```php\nComponent::pagination(\n    query: $custom_query  // WP_Query object (optional, uses global $wp_query if not provided)\n);\n```\n\n**Filters:**\n\n- `wp_utility_pagination_args` - Modify pagination arguments\n- `wp_utility_pagination_wrapper` - Customize wrapper attributes\n\n## Utilities\n\nUtilities provide data processing and retrieval functions.\n\n### ArchiveUrl\n\nHandles conversion of pretty permalinks to query string URLs for archive pages:\n\n```php\nuse BuiltNorth\\WPUtility\\Utilities\\Utility;\n\nUtility::archiveUrl();\n```\n\n### CountryList\n\nReturns an array of countries with ISO codes:\n\n```php\n$countries = Utility::countryList();\n// Returns: ['US' =\u003e 'United States', 'CA' =\u003e 'Canada', ...]\n```\n\n### GetTerms\n\nRenders terms for a post:\n\n```php\nUtility::getTerms(\n    post_id: get_the_ID(),\n    taxonomy: 'category',\n    taxonomy_link: true,\n    first_term_only: false,\n    class: 'post-terms'\n);\n```\n\n### GetTitle\n\nRetrieves appropriate page title across different WordPress contexts:\n\n```php\n$title = Utility::getTitle();\n```\n\n### LazyLoadFirstBlock\n\nControls lazy loading behavior for blocks:\n\n```php\n$should_lazy = Utility::lazyLoadFirstBlock(\n    block: $block,\n    non_lazy_parents: ['core/columns', 'core/group'],\n    default_lazy: true\n);\n```\n\n**Filter:**\n\n- `wp_utility_lazy_load_non_lazy_parents` - Modify non-lazy parent blocks\n\n### ReadingTime\n\nCalculates estimated reading time:\n\n```php\n$minutes = Utility::readingTime();\n```\n\n**Filter:**\n\n- `wp_utility_reading_time_wpm` - Customize words per minute (default: 200)\n\n### StateList\n\nReturns an array of US states:\n\n```php\n$states = Utility::stateList();\n// Returns: ['AL' =\u003e 'Alabama', 'AK' =\u003e 'Alaska', ...]\n```\n\n## Helpers\n\nHelpers provide utility functions for common tasks.\n\n### EscapeSvg\n\nSafely escapes SVG content for output:\n\n```php\nuse BuiltNorth\\WPUtility\\Helpers\\Helper;\n\n$safe_svg = Helper::escapeSvg($svg_content);\n```\n\n## Setup\n\nSetup classes handle WordPress configuration and initialization.\n\n### ImageSetup\n\nConfigures custom image sizes and removes WordPress defaults.\n\n#### Manual Initialization\n\n```php\nuse BuiltNorth\\WPUtility\\Setup\\ImageSetup;\n\nImageSetup::setup();\n```\n\n#### Default Image Sizes\n\n- **Wide formats:**\n    - `wide_xlarge`: 1600px wide\n    - `wide_large`: 1200px wide\n    - `wide_medium`: 800px wide\n    - `wide_small`: 600px wide\n    - `wide_xsmall`: 300px wide\n\n- **Square formats (cropped):**\n    - `square_xlarge`: 1200x1200\n    - `square_large`: 800x800\n    - `square_medium`: 600x600\n    - `square_small`: 300x300\n    - `square_xsmall`: 150x150\n\n#### Filters\n\n- `wp_utility_image_sizes` - Customize image sizes array\n- `wp_utility_image_size_names` - Customize display names\n- `wp_utility_remove_default_sizes` - Control which default sizes to remove\n- `wp_utility_max_srcset_width` - Set maximum srcset width (default: 1600)\n\n#### Example: Custom Image Sizes\n\n```php\nadd_filter('wp_utility_image_sizes', function($sizes) {\n    $sizes['banner'] = [1920, 600, true];\n    $sizes['thumbnail_large'] = [400, 400, true];\n    return $sizes;\n});\n\nadd_filter('wp_utility_image_size_names', function($names) {\n    $names['banner'] = __('Banner Image');\n    $names['thumbnail_large'] = __('Large Thumbnail');\n    return $names;\n});\n```\n\n## Method Naming Conventions\n\nAll components, utilities, and helpers support multiple naming conventions:\n\n```php\n// camelCase\nComponent::accessibleCard();\nUtility::getTitle();\nHelper::escapeSvg();\n\n// PascalCase (PHP is case-insensitive for methods)\nComponent::AccessibleCard();\nUtility::GetTitle();\nHelper::EscapeSvg();\n\n// snake_case (via magic methods)\nComponent::accessible_card();\nUtility::get_title();\nHelper::escape_svg();\n```\n\n## Backward Compatibility\n\nThe library maintains backward compatibility through class aliases:\n\n- `BuiltNorth\\WPUtility\\Component` → `BuiltNorth\\WPUtility\\Components\\Component`\n- `BuiltNorth\\WPUtility\\Utility` → `BuiltNorth\\WPUtility\\Utilities\\Utility`\n- `BuiltNorth\\WPUtility\\Helper` → `BuiltNorth\\WPUtility\\Helpers\\Helper`\n- `BuiltNorth\\WPUtility\\Utilities\\ImageSetup` → `BuiltNorth\\WPUtility\\Setup\\ImageSetup`\n\n## Testing\n\nRun the test suite:\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.\n\n## License\n\nThis package is licensed under the GPL version 2 or later. See [LICENSE.md](LICENSE.md) for details.\n\n## Disclaimer\n\nThis 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.\n\nUse 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.\n\nWhile 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.\n\nBy using this library, you acknowledge that you have read this disclaimer and agree to its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuiltnorth%2Fwp-utility","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuiltnorth%2Fwp-utility","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuiltnorth%2Fwp-utility/lists"}