Introduce register_asset() and enqueue_asset() functions; refactor & test plugin

.editorconfig

@@ -0,0 +1,29 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,ts,jsx,tsx,scss,php,xml}]
+# Avoid trailing whitespace
+trim_trailing_whitespace = true
+# Set default charset for JS files
+charset = utf-8
+# Tab indentation
+indent_style = tab
+tab_width = 2
+
+# Use 4-space indentation on composer.json
+[{composer.json}]
+indent_style = space
+indent_size = 4
+
+# Matches the exact files either package.json or .travis.yml
+# and overrides them to use 2-space indentation
+[{package.json,.travis.yml}]
+indent_style = space
+indent_size = 2

.travis.yml

@@ -10,4 +10,5 @@ php:
 install: composer install
 
 script:
-  - vendor/bin/phpcs --standard=vendor/humanmade/coding-standards .
+  - composer lint
+  - composer test

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## v0.4.0
+
+- **Breaking**: Remove undocumented `Asset_Loader\is_development` method.
+- **Breaking**: Remove undocumented `Asset_Loader\enqueue_assets` method.
+- **New**: Introduce new `Asset_Loader\register_asset()` and `Asset_Loader\enqueue_asset()` public API.
+  - Assets should now be registered individually.
+  - If a bundle exports both a CSS and JS file, both files should be registered or enqueued individually.
+- Refactor how SSL warning notice behavior gets triggered during asset registration.
+- Change how version strings are determined when registering assets
+  - If asset is detected to be using a uniquely hashed filename, no version string is used.
+  - If an asset manifest is in use, assets are versioned based on a content hash of that manifest.
+  - If no other version information can be determined and the loader is running within[Altis](https://altis-dxp.com), the Altis revision constant is used to version registered assets.
+
+## v0.3.4
+
+- Added `composer/installers` as a dependency to permit custom installation paths when installing this package.
+
+## v0.3.3
+
+- Display admin notification about accepting Webpack's SSL certificate if `https://localhost` scripts encounter errors when loading.
+- Derive script & style version string from file hash, not `filemtime`.
+
+## v0.3.2
+
+- Do not require plugin files if plugin is already active elsewhere in the project.
+
+## v0.3.1
+
+- Transfer plugin to `humanmade` GitHub organization
+
+## v0.3.0
+
+- Fix bug when loading plugin assets outside of `wp-content/plugins`
+- Permit installation with `composer`.
+
+## v0.2.0
+
+- Initial release: introduce `autoregister()` and `autoenqueue()` public API.

README.md

@@ -6,9 +6,47 @@ This plugin exposes functions which may be used within other WordPress themes or
 
 ## Usage
 
-Full documentation to come. See [react-wp-scripts](https://github.com/humanmade/react-wp-scripts) for directional inspiration about how the methods in [plugin.php](plugin.php) may be used.
+This library is designed to work in conjunction with a Webpack configuration (such as those created with the presets in [@humanmade/webpack-helpers](https://github.com/humanmade/webpack-helpers)) which generate an asset manifest file. This manifest associates asset bundle names with either URIs pointing to asset bundles on a running DevServer instance, or else local file paths on disk.
 
-Assuming a Webpack configuration (such as those created with the presets in [@humanmade/webpack-helpers](https://github.com/humanmade/webpack-helpers)) which sets up a Webpack DevServer instance for an entrypoint named `editor.js`, and assuming the asset manifest and the build, production version of the `editor.js` file would both end up in a `build/` folder within a theme or plugin, you may load the bundle by using the Asset Loader's autoloader method:
+`Asset_Loader` provides a set of methods for reading in this manifest file and registering a specific resource within it to load within your WordPress website. The primary public interface provided by this plugin is a pair of methods, `Asset_Loader\register_asset()` and `Asset_Loader\enqueue_asset()`. To register a manifest asset call one of these methods inside actions like `wp_enqueue_scripts` or `enqueue_block_editor_assets`, in the same manner you would have called the standard WordPress `wp_register_script` or `wp_enqueue_style` functions.
+
+```php
+<?php
+namespace My_Plugin_Or_Theme;
+
+use Asset_Loader;
+
+add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\\enqueue_block_editor_assets' );
+
+/**
+ * Enqueue the JS and CSS for blocks in the editor.
+ *
+ * @return void
+ */
+function enqueue_block_editor_assets() {
+  Asset_Loader\enqueue_asset(
+    // In a plugin, this would be `plugin_dir_path( __FILE__ )` or similar.
+    get_stylesheet_directory() . '/build/asset-manifest.json',
+    // The handle of a resource within the manifest. For static file fallbacks,
+    // this should also match the filename on disk of a build production asset.
+    'editor.js',
+    [
+      'handle'       => 'optional-custom-script-handle',
+      'dependencies' => [ 'wp-element', 'wp-editor' ],
+    ]
+  );
+}
+```
+
+To register an asset to be manually enqueued later, use `Asset_Loader\register_asset()` instead of `enqueue_asset()`. Both methods take the same arguments.
+
+If a manifest is not present then `Asset_Loader` will attempt to load the specified resource from the same directory containing the manifest file.
+
+## Migrating from v0.3
+
+Prior to v0.4, the main public interface exposed by this package was a pair of methods named `autoenqueue` and `autoregister`. Internally these methods used a somewhat "magical" and inefficient method of filtering through asset resources. They are deprecated as of v0.4, and will be removed in v0.5.
+
+The following snippet of v0.3-compatible code using `autoenqueue` can be replaced with the `Asset_Loader\enqueue_asset()` example above.
 
 ```php
 <?php
@@ -40,13 +78,14 @@ function enqueue_block_editor_assets() {
 
 ## Local Development
 
-Before submitting a pull request, ensure that your PHP code passes our [coding standards](https://github.com/humanmade/coding-standards) by running [PHPCS](https://pear.php.net/package/PHP_CodeSniffer):
+Before submitting a pull request, ensure that your PHP code passes all existing unit tests and conforms to our [coding standards](https://github.com/humanmade/coding-standards) by running these commands:
 
 ```sh
-composer run-script lint
+composer lint
+composer test
 ```
 
-If the above command does not work, ensure you have [Composer](https://getcomposer.org/) installed on your machine & run `composer install` from the project root.
+If the above commands do not work, ensure you have [Composer](https://getcomposer.org/) installed on your machine & run `composer install` from the project root.
 
 ## License
 

asset-loader.php

@@ -20,6 +20,8 @@
  * License URI: https//github.com/humanmade/asset-loader/tree/master/LICENSE
  */
 
+declare( strict_types=1 );
+
 // phpcs:disable HM.Files.NamespaceDirectoryName
 namespace Asset_Loader;
 

composer.json

@@ -7,9 +7,12 @@
         "composer/installers": "~1.0"
     },
     "require-dev": {
-        "humanmade/coding-standards": "dev-master"
+        "humanmade/coding-standards": "dev-master",
+        "10up/wp_mock": "^0.4.2",
+        "phpunit/phpunit": "^7.5"
     },
     "scripts": {
-        "lint": "phpcs --standard=phpcs.ruleset.xml ."
+        "lint": "phpcs .",
+        "test": "phpunit"
     }
 }