{"id":21611524,"url":"https://github.com/underpin-wp/script-loader","last_synced_at":"2025-07-26T21:13:01.885Z","repository":{"id":45130522,"uuid":"363775212","full_name":"Underpin-WP/script-loader","owner":"Underpin-WP","description":"Script loader for Underpin","archived":false,"fork":false,"pushed_at":"2022-01-06T13:44:42.000Z","size":47,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T03:34:46.780Z","etag":null,"topics":["scripts","underpin","wordpress"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Underpin-WP.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-02T23:57:47.000Z","updated_at":"2023-07-20T10:50:26.000Z","dependencies_parsed_at":"2022-08-25T23:11:38.476Z","dependency_job_id":null,"html_url":"https://github.com/Underpin-WP/script-loader","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Fscript-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Fscript-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Fscript-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Fscript-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Underpin-WP","download_url":"https://codeload.github.com/Underpin-WP/script-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248348272,"owners_count":21088841,"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":["scripts","underpin","wordpress"],"created_at":"2024-11-24T21:13:00.420Z","updated_at":"2025-04-11T05:34:40.957Z","avatar_url":"https://github.com/Underpin-WP.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Underpin Script Loader\n\nLoader That assists with adding scripts to a WordPress website.\n\n## Installation\n\n### Using Composer\n\n`composer require underpin/script-loader`\n\n### Manually\n\nThis plugin uses a built-in autoloader, so as long as it is required _before_\nUnderpin, it should work as-expected.\n\n`require_once(__DIR__ . '/underpin-scripts/scripts.php');`\n\n## Setup\n\n1. Install Underpin. See [Underpin Docs](https://www.github.com/underpin-wp/underpin)\n1. Register new scripts as-needed.\n\n## Example\n\nA very basic example could look something like this.\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description'\n] );\n```\n\nAlternatively, you can extend `Script` and reference the extended class directly, like so:\n\n```php\nunderpin()-\u003escripts()-\u003eadd('key','Namespace\\To\\Class');\n```\n\n## Enqueuing Scripts\n\nTo enqueue a script, run the loader and reference the script ID, like so:\n\n```php\nunderpin()-\u003escripts()-\u003eenqueue('test'); // Enqueue the test script\n```\n\nA common practice is to extend `do_actions` in the script class to add the actions necessary to enqueue the script. If\nyou don't need to use any logic to enqueue your script, the simplest way to enqueue the script is with\nthe [enqueue script middleware](#Enqueuing-With-Middleware).\n\n## Localizing Scripts\n\nUnderpin expands on how script localization works. A common problem with using `wp_localize_script` is that the data\nneeded to localize the script has to all be placed in one single call. Underpin gets around that by using\nthe `set_param`\nmethod.\n\nFor example, say you wanted to localize `ajaxUrl` as your site's admin AJAX URL. You could do that at any time, like so:\n\n```php\nunderpin()-\u003escripts()-\u003eget( 'test' )-\u003eset_param( 'ajaxUrl', admin_url( 'admin-ajax.php' ) );\n```\n\nAs long as this is done before `enqueue` is fired, `ajaxUrl` will be localized. All items are localized inside of an\nobject named after the `localized_var`. If no `localized_var` is specified, the var will be the `handle`.\n\nSo, if you enqueued `ajaxUrl` on a script with a handle called `example`, you would get something like:\n\n```js\n// console.log(example)\n{\n\tajaxUrl: 'https://www.underpin.com/admin-ajax.php'\n}\n```\n\n## Script Middleware\n\nSometimes, it is necessary to localize the same set of paramaters, or even run the same actions across many scripts.\nThis is where script middleware comes in handy.\n\nFor example, let's say you want to build a script that utilizes the REST API, and as a result needs a nonce and the root\nURL localized in the script. Doing this without a script is pretty straightforward, but verbose:\n\n```php\n\n// Register script\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description'\n] );\n\n$script = underpin()-\u003escripts()-\u003eget('test');\n\n// Localize script\n$script-\u003eset_param('nonce', wp_create_nonce('wp_rest'));\n$script-\u003eset_param('rest_url', get_rest_url());\n\n// Enqueue script\n$script-\u003eenqueue();\n```\n\nThis is a very common scenario for WordPress scripts. Because of\nthis, [a middleware package](https://www.github.com/underpin-wp/underpin-rest-middleware) exists to handle this\nautomatically. The example below would accomplish the exact same thing:\n\n```php\n// Register script\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'Underpin_Rest_Middleware\\Factories\\Rest_Middleware'\n        ]\n] );\n\n// Enqueue script\n$script = underpin()-\u003escripts()-\u003eget('test')-\u003eenqueue();\n```\n\nThe key part of the example above is the `middlewares` argument. Middlewares is an array of `Script_Middleware` items\nthat run in the provided order, and are intended to automate the steps needed to set up a script.\n\n### Enqueuing With Middleware\n\nIn circumstances where you _always_ need to enqueue the script, you can use the provided enqueue middleware.\n\nTo enqueue on admin screens:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'Underpin_Scripts\\Factories\\Enqueue_Admin_Script'\n        ]\n] );\n```\n\nTo enqueue on the front-end:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'Underpin_Scripts\\Factories\\Enqueue_Script'\n        ]\n] );\n```\n\nTo enqueue on the login screen:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'Underpin_Scripts\\Factories\\Enqueue_Login_Script'\n        ]\n] );\n```\n\nTo enqueue on both front-end and back-end:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'Underpin_Scripts\\Factories\\Enqueue_Script',\n          'Underpin_Scripts\\Factories\\Enqueue_Admin_Script'\n        ]\n] );\n```\n\n#### Enqueuing Conditionally\n\nA common scenario when enqueuing a script is to enqueue it under certain conditions. This can be handled using\nconditional middleware, using the array-based syntax for `Underpin::make_class`\n\nFor example, say you only want to enqueue a script on a specific admin page:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          [\n            'class' =\u003e 'Underpin_Scripts\\Factories\\Enqueue_Admin_Script_Conditional',\n            'args'  =\u003e [\n              'should_enqueue_callback' =\u003e function(Script $script){\n                return get_current_screen()-\u003eid === 'custom_screen_id';\n              }\n            ] \n          ]\n        ]\n] );\n```\n\nAnother example, say you only want enqueue on the home page:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          [\n            'class' =\u003e 'Underpin_Scripts\\Factories\\Enqueue_Script_Conditional',\n            'args'  =\u003e [\n              'should_enqueue_callback' =\u003e 'is_home'\n            ] \n          ]\n        ]\n] );\n```\n\n#### Enqueuing Blocks\n\nAn increasingly common scenario with scripts is to enqueue a block script. This can be done like so:\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n        'handle'      =\u003e 'test',\n        'src'         =\u003e 'path/to/script/src',\n        'name'        =\u003e 'test',\n        'description' =\u003e 'The description',\n        'middlewares' =\u003e [\n          'class' =\u003e 'Underpin_Scripts\\Factories\\Enqueue_Block_Script',\n        ]\n] );\n```\n\n### Create Your Own Middleware\n\nThe `middlewares` array uses `Underpin::make_class` to create the class instances. This means that you can pass either:\n\n1. a string that references an instance of `Script_Middleware` (see example above).\n1. An array of arguments to construct an instance of `Script_Middleware` on-the-fly.\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n\t'handle'      =\u003e 'test',\n\t'src'         =\u003e 'path/to/script/src',\n\t'name'        =\u003e 'test',\n\t'description' =\u003e 'The description',\n\t'middlewares' =\u003e [\n\t\t'Underpin_Rest_Middleware\\Factories\\Rest_Middleware', // Will localize script params.\n\t\t'Underpin_Scripts\\Factories\\Enqueue_Script',          // Will enqueue the script on the front end all the time.\n\t\t[                                                     // Will instantiate an instance of Script_Middleware_Instance using the provided arguments\n\t\t\t'name'                =\u003e 'Custom setup params',\n\t\t\t'description'         =\u003e 'Sets up custom parameters specific to this script',\n\t\t\t'priority'            =\u003e 10, // Optional. Default 10.\n\t\t\t'do_actions_callback' =\u003e function ( \\Underpin_Scripts\\Abstracts\\Script $loader_item ) {\n\t\t\t\t// Do actions\n\t\t\t},\n\t\t],\n\t],\n] );\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funderpin-wp%2Fscript-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funderpin-wp%2Fscript-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funderpin-wp%2Fscript-loader/lists"}