{"id":19107765,"url":"https://github.com/alleyinteractive/wp-asset-manager","last_synced_at":"2025-04-05T21:05:52.073Z","repository":{"id":41145692,"uuid":"108602735","full_name":"alleyinteractive/wp-asset-manager","owner":"alleyinteractive","description":"Asset Manager is a toolkit for managing front-end assets and more tightly controlling where, when, and how they're loaded.","archived":false,"fork":false,"pushed_at":"2025-01-27T15:01:18.000Z","size":384,"stargazers_count":29,"open_issues_count":7,"forks_count":5,"subscribers_count":38,"default_branch":"production","last_synced_at":"2025-03-29T20:04:07.650Z","etag":null,"topics":["wordpress","wordpress-plugin"],"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/alleyinteractive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license.txt","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}},"created_at":"2017-10-27T22:51:45.000Z","updated_at":"2025-03-14T14:03:35.000Z","dependencies_parsed_at":"2023-11-19T06:26:49.926Z","dependency_job_id":"78379a77-0b8f-4588-bcfa-ceea398a9b17","html_url":"https://github.com/alleyinteractive/wp-asset-manager","commit_stats":{"total_commits":220,"total_committers":14,"mean_commits":"15.714285714285714","dds":0.6045454545454545,"last_synced_commit":"b005d13170eadecb7c860ba5b600330f82d54af6"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-asset-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-asset-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-asset-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-asset-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alleyinteractive","download_url":"https://codeload.github.com/alleyinteractive/wp-asset-manager/tar.gz/refs/heads/production","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399871,"owners_count":20932876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["wordpress","wordpress-plugin"],"created_at":"2024-11-09T04:13:53.448Z","updated_at":"2025-04-05T21:05:52.042Z","avatar_url":"https://github.com/alleyinteractive.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WordPress Asset Manager\n\nAsset Manager is a toolkit for managing front-end assets and more tightly controlling where, when, and how they're loaded.\n\n* [Using Asset Manager in your WordPress Project](#using-asset-manager-in-your-wordpress-project)\n* [Enqueue Functions](#enqueue-functions)\n  * [am_enqueue_script](#am_enqueue_script)\n  * [am_enqueue_style](#am_enqueue_style)\n  * [Conditions](#conditions)\n  * [Inline Assets](#inline-assets)\n  * [Enqueue Options](#enqueue-options)\n* [Preload Function](#preload-function)\n  * [Preload Options](#preload-options)\n* [SVG Sprite](#svg-sprite)\n  * [Setup](#setup)\n    * [Admin pages](#admin-pages)\n  * [Registering Symbols](#registering-symbols)\n  * [Verifying a symbol is registered](#verifying-a-symbol-is-registered)\n  * [Changing the SVG Directory](#changing-the-svg-directory)\n  * [Setting Global Attributes](#setting-global-attributes)\n  * [Update `$sprite_allowed_tags`](#update-sprite_allowed_tags)\n  * [Removing a Symbol](#removing-a-symbol)\n    * [Replacing a Symbol](#replacing-a-symbol)\n  * [Displaying a Symbol](#displaying-a-symbol)\n    * [Notes on SVG sizing](#notes-on-svg-sizing)\n  * [Getting a Symbol](#getting-a-symbol)\n* [Requirements](#requirements)\n* [Downloads and Versioning](#downloads-and-versioning)\n* [Contributing to Development](#contributing-to-development)\n\n## Using Asset Manager in your WordPress Project\n\nTo get started, simply [download](#downloads-and-versioning) and install this plugin into your plugins directory and activate it on the plugins screen.\n\n## Enqueue Functions\n\nThe `am_enqueue_*` functions will enqueue an asset with additional attributes based upon its `load_method` value. Options can be passed in as an array or individual parameters.\n\n### `am_enqueue_script`\n\n\u003c!-- The `am_enqueue_script` function will enqueue a JavaScript file with additional attributes based upon the `load_method` value. --\u003e\n\n```php\n// Enqueue a JavaScript asset.\nam_enqueue_script(\n  [\n    'handle'      =\u003e 'footer-script',\n    'src'         =\u003e 'js/script.js',\n    'deps'        =\u003e [],\n    'condition'   =\u003e 'global',\n    'load_method' =\u003e 'sync', // 'sync', 'inline', 'async', 'defer', 'async-defer'\n    'version'     =\u003e '1.0.0',\n    'load_hook'   =\u003e 'wp_footer',\n  ]\n);\n```\n\nUse `am_modify_load_method` to modify the load method of an already-enqueued script.\n\n```php\n// Defer an enqueued JavaScript asset.\nam_modify_load_method(\n  [\n    'handle'      =\u003e 'footer-script', \n    'load_method' =\u003e 'defer',\n  ]\n);\n```\n\n### `am_enqueue_style`\n\n```php\n// Load a CSS asset asynchronously.\nam_enqueue_style(\n  [\n    'handle'      =\u003e 'site-styles',\n    'src'         =\u003e 'css/styles.css',\n    'deps'        =\u003e [],\n    'condition'   =\u003e 'global',\n    'load_method' =\u003e 'async', // 'sync', 'inline', 'async', 'defer', 'preload'\n    'version'     =\u003e '1.0.0',\n    'load_hook'   =\u003e 'wp_head',\n    'media'       =\u003e 'all', // 'print', 'screen', or any valid media query\n  ]\n);\n```\n\n### Conditions\n\nThe `condition` parameter determines under which condition(s) the asset should load.\n\n**`include`**\n\n\u003e `string|array`\n\u003e \n\u003e Requires that all conditions be truthy in order for the asset to load.\n\nThe `include` property is implied if the `condition` parameter is a string or array of strings; otherwise the `condition` parameter must contain the `include` property.\n\n**`include_any`**\n\n\u003e `string|array`\n\u003e \n\u003e Allows for _any_ condition to be truthy, instead of requiring that all conditions be.\n\n**`exclude`**\n\n\u003e `string|array`\n\u003e \n\u003e Requires that all conditions be falsey in order for the asset to load. This is skipped if neither `include` nor `include_any` are truthy.\n\n#### Custom Conditions\n\nThere are a few default conditions included out-of-the-box:\n\n| Name       | Condition     |\n|:-----------|---------------|\n| `'global'` | `true`        |\n| `'single'` | `is_single()` |\n| `'search'` | `is_search()` |\n\nUse the `am_asset_conditions` filter to add or replace conditions.\n\n```php\nfunction asset_conditions( $conditions ) {\n  return array_merge(\n    $conditions,\n    [\n      'home'    =\u003e ( is_home() || is_front_page() ),\n      'archive' =\u003e is_archive(),\n      'page'    =\u003e is_page(),\n    ]\n  );\n}\n\nadd_filter( 'am_asset_conditions', 'asset_conditions', 10 );\n```\n\n### Inline Assets\n\nUse `load_method =\u003e inline` with an absolute `src` path for either enqueue function to print the contents of the file to the document head.\n\n**Print the contents of a file**\n\n```php\n// Print the contents of this CSS asset into a \u003cstyle\u003e tag.\n// Also works with `am_enqueue_script` for printing a JavaScript asset into a \u003cscript\u003e tag.\nam_enqueue_style(\n  [\n    'handle'      =\u003e 'inline-styles',\n    'src'         =\u003e 'css/styles.css',\n    'condition'   =\u003e 'global',\n    'load_method' =\u003e 'inline',\n  ]\n);\n```\n\n**Print inline global variables**\n\nPass an array of values as the `src` to print global JavaScript variables to the document head.\n\n```php\n// Add JavaScript values to a property on the `window.amScripts` object.\nam_enqueue_script(\n  [\n    'handle'      =\u003e 'inline-vars',\n    'src'         =\u003e [\n      'myGlobalVar' =\u003e true,\n    ],\n    'load_method' =\u003e 'inline',\n  ]\n);\n```\n\nThe result will be an object added to the `window.amScripts[$handle]` object:\n\n```html\n\u003cscript class=\"wp-asset-manager inline-vars\" type=\"text/javascript\"\u003ewindow.amScripts = window.amScripts || {}; window.amScripts[\"inline-vars\"] = {\"myGlobalVar\":true}\u003c/script\u003e\n```\n\nUse the `am_inline_script_context` filter to change the global object name.\n\n```php\nadd_filter(\n  'am_inline_script_context',\n  function() {\n    return 'myContext'; // window.myContext[$handle]\n  }\n);\n```\n\n### Enqueue Options\n\nThe `am_enqueue_*` functions use the same parameters as their core WordPress enqueue equivelant, with the exception of the `$in_footer` parameter for scripts; use `'load_hook'` (details below) instead.\n\n**Additional options:**\n\n| Name                   | Description                                                         | Default     |\n|:-----------------------|:--------------------------------------------------------------------|:-----------:|\n| `condition`            | The condition for which this asset should load                      | `'global'`  |\n| `load_hook`            |                                                                     | `'wp_head'` |\n| \u0026emsp; — `wp_head`     | Load this asset via `wp_head`                                       |             |\n| \u0026emsp; — `wp_footer`   | Load this asset via `wp_footer`                                     |             |\n| `load_method`          |                                                                     | `'sync'`    |\n| \u0026emsp; — `sync`        | Use the core`wp_enqueue` function                                   |             |\n| \u0026emsp; — `async`       | Adds the `async` attribute to the enqueue                           |             |\n| \u0026emsp; — `defer`       | Adds the `defer` attribute to the enqueue                           |             |\n| \u0026emsp; — `async-defer` | Adds the `async` and `defer` attributes (scripts only)              |             |\n| \u0026emsp; — `inline`      | Prints the asset inline in the document head                        |             |\n\n## Preload Function\n\nUse `am_preload` for preloading assets of any [supported type](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content#What_types_of_content_can_be_preloaded).\n\n```php\n// `as` and `mime_type` options will be automatically added for CSS, but are included here for clarity.\nam_preload(\n  [\n    'handle'    =\u003e 'preload-styles',\n    'src'       =\u003e 'css/styles.css',\n    'condition' =\u003e 'global',\n    'version'   =\u003e '1.0.0',\n    'as'        =\u003e 'style'\n    'mime_type' =\u003e 'text/css',\n  ]\n);\n```\n\nResult:\n\n```html\n\u003clink rel=\"preload\" href=\"http://client/css/test.css?ver=1.0.0\" class=\"wp-asset-manager preload-styles\" as=\"style\" media=\"all\" type=\"text/css\" /\u003e\n```\n\nThe `am_preload` function patches the `as` and `mime_type` option values for common use-cases (CSS, JavaScript and WOFF2 fonts), but will throw an error if the `as` option is missing for any other file type.\n\nFrom [the spec](https://www.w3.org/TR/preload/#as-attribute):\n\u003e The [as] attribute is necessary to guarantee correct prioritization, request matching, application of the correct Content Security Policy policy, and setting of the appropriate `Accept` request header.\n\nThis function will also automatically add the `crossorigin` attribute for fonts, which [is required](https://drafts.csswg.org/css-fonts/#font-fetching-requirements) when preloading fonts, even if they're not actually cross-origin requests.\n\n### Preload Options\n\n| Name          | Description                                                        | Required    | Default     |\n|:--------------|:-------------------------------------------------------------------|:-----------:|:-----------:|\n| `handle`      | The handle for the asset                                           | •           |             |\n| `src`         | The URI for the asset                                              | •           |             |\n| `condition`   | The condition for which this asset should load                     |             | `'global'`  |\n| `version`     | The asset version                                                  |             | `'1.0.0'`   |\n| `as`          | The `as` attribute's value ([info][preload-types])                 | •           |             |\n| `mime_type`   | The `type` attribute's value ([info][mime-types])                  | •           |             |\n| `media`       | The media attribute value used to conditionally preload the asset  |             | `'all'`     |\n\n## SVG Sprite\n\nAllows for fine-grained control over SVG assets in WordPress templates by creating a sprite of registered symbols and providing helper functions for displaying them.\n\nAsset Manager will add an SVG file's contents to the sprite if:\n\n1. The symbol is registered via `am_register_symbol` with a unique handle and valid file path\n2. The symbol's `condition` is truthy\n\nSee [Conditions](#conditions) for more about Asset Manager's conditions and how to update them.\n\n### Setup\n\nThe sprite is printed via the [`wp_body_open`](https://developer.wordpress.org/reference/hooks/wp_body_open/) hook, so be sure your templates have the [wp_body_open()](https://developer.wordpress.org/reference/functions/wp_body_open/) function at the top of the document's `\u003cbody\u003e` element.\n\n#### Admin pages\n\nPrints the sprite to admin pages via the `in_admin_header` hook, which is the most similar admin hook to `wp_body_open`. Symbols registered with condition(s) not matching admin pages will not be added to the sprite.\n\n```php\n/**\n * Add SVG symbols to the admin page content.\n */\nfunction print_admin_sprite() {\n  if ( class_exists( 'Asset_Manager_SVG_Sprite' ) ) {\n    Asset_Manager_SVG_Sprite::instance()-\u003eprint_sprite_sheet();\n  }\n}\nadd_action( 'in_admin_header', 'print_admin_sprite' );\n```\n\n### Registering Symbols\n\nUse the `am_register_symbol` function to add a symbol to the sprite. Like `wp_register_script` and `wp_register_style`, an attempt to re-register a symbol with an existing handle will be ignored.\n\n**Symbols should be registered via an action that fires before [`wp_body_open`](https://developer.wordpress.org/reference/hooks/wp_body_open/).**\n\n```php\nam_register_symbol(\n  [\n    'handle'    =\u003e 'logomark',\n    'src'       =\u003e 'svg/logomark.svg',\n    'condition' =\u003e 'global',\n  ]\n);\n```\n\nOptions can be passed in as an array or individual parameters.\n\n**`$handle`**\n\n\u003e `string`\n\u003e\n\u003e Handle for the asset. Should be unique.\n\n**`$src`** \n\n\u003e `string`\n\u003e\n\u003e Absolute path to the SVG file, or a relative path based on the current theme root. Use the `am_modify_svg_directory` filter to update the directory from which relative paths will be completed.\n\n**`$condition`** \n\n\u003e `string|array`\n\u003e\n\u003e Loading condition(s) that, when matched, will allow the asset to be added to the sprite.\n\n**`$attributes`** \n\n\u003e `array`\n\u003e\n\u003e An array of HTML attribute names and values to add to the resulting `\u003csvg\u003e` everywhere it is rendered.\n\n### Verifying a symbol is registered\n\n```php\nam_symbol_is_registered( $handle = '' );\n```\n\n**`$handle`**\n\n\u003e `string`\n\u003e \n\u003e The handle with which the symbol should be registered.\n\n**Return**\n\n\u003e `bool`\n\u003e\n\u003e Whether the symbol has been registered.\n\n### Changing the SVG directory\n\nUse the `am_modify_svg_directory` filter to update the directory from which relative paths will be completed.\n\n**Default**: The current theme root.\n\n```php\nadd_filter(\n  'am_modify_svg_directory',\n  function( $theme_root ) {\n    return $theme_root . '/svg/';\n  }\n);\n```\n\n### Setting Global Attributes\n\nUse the `am_global_svg_attributes` filter to add global attributes that will apply to all symbols.\n\n**Default**: `[]`\n\n```php\nadd_filter(\n  'am_global_svg_attributes',\n  function() {\n    return [\n      'aria-hidden' =\u003e 'true',\n      'focusable'   =\u003e 'false',\n    ];\n  }\n);\n```\n\n### Update `$sprite_allowed_tags`\n\nUse the `am_sprite_allowed_tags` to filter [elements and attributes](php/kses-svg.php) used in escaping the sprite, such as certain deprecated attributes, script tags, and event handlers.\n\n```php\nadd_filter(\n  'am_sprite_allowed_tags',\n  function( $sprite_allowed_tags ) {\n    $sprite_allowed_tags['path']['onclick'] = true;\n\n    return $sprite_allowed_tags;\n  }\n);\n```\n\n### Removing a Symbol\n\nUse `am_deregister_symbol` to remove a registered a symbol.\n\nThis should be added via an action that fires after, or at a lower priority, than the action used for `am_register_symbol`.\n\n```php\nam_deregister_symbol( $handle = '' );\n```\n\n**`$handle`**\n\n\u003e `string`\n\u003e \n\u003e The handle with which the symbol was registered.\n\n**Return**\n\n\u003e `bool`\n\u003e\n\u003e Whether the symbol has been deregistered and removed from the sprite. `true` on success, or if the symbol hadn't been previously registered; `false` on failure.\n\n#### Replacing a symbol\n\nPrior to re-registering a symbol, verify the symbol to be replaced is not registered.\n\n```php\nif ( am_deregister_symbol( 'logomark' ) ) {\n  am_register_symbol(\n    [\n      'handle'    =\u003e 'logomark',\n      'src'       =\u003e 'svg/logomark-alt.svg',\n      'condition' =\u003e 'global',\n    ]\n  );\n}\n```\n\n### Displaying a Symbol\n\n`am_use_symbol` prints an `\u003csvg\u003e` element with the specified attributes.\n\n```php\nam_use_symbol( $handle = '', $attributes = [] );\n```\n\n**`$handle`**\n\n\u003e `string`\n\u003e \n\u003e The handle with which the symbol was registered.\n\n**`$attributes`**\n\n\u003e `array` \n\u003e \n\u003e An array of attribute-value pairs to add to the resulting SVG markup.\n\u003e \n\u003e Override global attributes, or those defined via `am_register_symbol`, by declaring a new value here; remove it entirely by passing a falsy value.\n\n#### Notes on SVG sizing\n\nAsset Manager will attempt to establish a default size for each SVG, which will be used to calculate the dimensions if only one, or neither, of `height` or `width` is passed to `am_use_symbol`.\n\nThe default size is based on (in order):\n1. The values set in the symbol's `am_register_symbol` attributes array\n1. The `height` and `width` attributes from the SVG\n1. The `viewBox` attribute values\n\nIf Asset Manager cannot determine a symbol's dimensions, both `height` _and_ `width` will need to be declared in the `attributes` array passed to `am_use_symbol`.\n\n**The simplest way to ensure SVGs are sized as expected is to verify each file's `\u003csvg\u003e` element either has both `height` and `width` attributes or a viewBox attribute.**\n\n_**Example**_:\n\n```php\nam_use_symbol(\n  'logomark',\n  [\n    'width' =\u003e 200,\n    'class' =\u003e 'header-logo',\n  ]\n);\n```\n\n_**Output**_:\n\n```html\n\u003csvg width=\"200\" height=\"27.67\" class=\"header-logo\" aria-hidden=\"true\" focusable=\"false\"\u003e\n  \u003cuse href=\"#am-symbol-logomark\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\n### Getting a Symbol\n\n`am_get_symbol` returns a string containing the `\u003csvg\u003e` element with the specified attributes.\n\n```php\n$symbol_markup = am_get_symbol( $handle = '', $attributes = [] );\n```\n\nThis function uses the same arguments as `am_use_symbol`.\n\n_**Example**_:\n\n```php\n$logomark_svg_markup = am_get_symbol(\n  'logomark',\n  [\n    'width' =\u003e 200,\n    'class' =\u003e 'header-logo',\n  ]\n);\n```\n\n## Requirements\n\n* WordPress: 5.2.0+\n* PHP: 7.4+\n\n## Downloads and Versioning.\n\nYou can view [Asset Manager's official releases here](https://github.com/alleyinteractive/wp-asset-manager/releases).\n\nThe `develop` branch on GitHub contains the \"bleeding edge\" releases (alpha, beta, RC). The `production` branch is the latest stable release.\n\n## Contributing to Development\n\nDevelopment of Asset Manager happens on [Github](http://github.com/alleyinteractive/wp-asset-manager). Bugs with Asset Manager should be addressed in the Github issue queue, and enhancements or bug fixes should be submitted as pull requests, which are always welcome.\n\n[preload-types]: https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content#What_types_of_content_can_be_preloaded\n[mime-types]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-asset-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleyinteractive%2Fwp-asset-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-asset-manager/lists"}