Merge remote-tracking branch 'origin/master'

scarstens · scarstens · commit 0f7e1d981e3e · 2018-06-04T12:31:42.000-07:00
# Conflicts:
#	.circleci/codesniffer.ruleset.xml
diff --git a/.circleci/codesniffer.ruleset.xml b/.circleci/codesniffer.ruleset.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset name="timeinc-wp-plugin">
+<ruleset name="wp-dev-toolkit-wp-plugin">
     <description>Custom plugin codesniffer exceptions.</description>
     <exclude-pattern>vendor/*</exclude-pattern>
     <exclude-pattern>lib/composer/*</exclude-pattern>
diff --git a/app/admin/class-auth-assets.php b/app/admin/class-auth-assets.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
 /**
  * Register and enqueue assets used in the WordPress Admin or only when a user is authenticated here.
diff --git a/app/admin/class-generators-page.php b/app/admin/class-generators-page.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
 class Generators_Page {
 	/**
diff --git a/app/admin/class-init.php b/app/admin/class-init.php
@@ -1,10 +1,9 @@
 <?php
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
 /**
  * Class Init
- * @package Wordpress_development_toolkit
  */
 class Init {
 
diff --git a/app/admin/class-plugin-generator-form.php b/app/admin/class-plugin-generator-form.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
 class Plugin_Generator_Form {
 
diff --git a/app/admin/class-product-machine.php b/app/admin/class-product-machine.php
@@ -1,10 +1,10 @@
 <?php
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
-use RecursiveDirectoryIterator;
-use RecursiveIteratorIterator;
-use ZipArchive;
+use \RecursiveDirectoryIterator;
+use \RecursiveIteratorIterator;
+use \ZipArchive;
 
 /**
  * Class Product_Machine
@@ -117,15 +117,6 @@ static function make_zip_download( $filename, $origin_dir, $tmp_dir, $data, $con
 				}
 			}
 
-
-
-			// only run these operations for standard plugins
-			// add empties to key directories
-			$blank_file = '<?php ' . PHP_EOL . '// *gentle wave* not the code you\'re looking for..' . PHP_EOL;
-			$idx        = '/index.php';
-			$zip->addFromString( 'app' . $idx, $blank_file );
-			$zip->addFromString( 'app/admin' . $idx, $blank_file );
-
 			// close zip
 			$zip->close();
 
@@ -189,7 +180,8 @@ static function process_file_contents( $file ) {
 			'main.php',
 			'README.md',
 			'composer.json',
-			'app/class-plugin.php'
+			'app/class-plugin.php',
+			'.circleci/codesniffer.ruleset.xml',
 		) );
 
 		if ( in_array( $filename, $important_files ) ) {
@@ -267,4 +259,5 @@ static function get_abstract_plugin_base_namespace( $file_contents ) {
 
 		return null;
 	}
+
 }
diff --git a/app/admin/class-toolkit-dashboard-page.php b/app/admin/class-toolkit-dashboard-page.php
@@ -6,7 +6,7 @@
  * @subpackage wordpress-development-toolkit
  */
 
-namespace PHX_WP_DEVKIT\V_3_0\Admin;
+namespace PHX_WP_DEVKIT\V_3_1\Admin;
 
 /**
  * Class Toolkit_Dashboard_Page
diff --git a/app/admin/templates/main.php b/app/admin/templates/main.php
@@ -1,3 +1,6 @@
+<?php
+// start that php
+?>
 <script id="tmpl-wp-phx-tools" type="text/html">
 	<table width="100%">
 		<tr>
@@ -111,4 +114,4 @@
 		</div>
 	</div>
 	<br class="clear" />
-</script>
+</script>
diff --git a/app/boilerplates/simple/.circleci/codesniffer.ruleset.xml b/app/boilerplates/simple/.circleci/codesniffer.ruleset.xml
@@ -1,8 +1,13 @@
 <?xml version="1.0"?>
-<ruleset name="timeinc-wp-plugin">
+<ruleset name="<%= DASHES_SLUG %>-wp-plugin">
     <description>Custom plugin codesniffer exceptions.</description>
     <exclude-pattern>vendor/*</exclude-pattern>
     <exclude-pattern>lib/composer/*</exclude-pattern>
     <exclude-pattern>assets/*</exclude-pattern>
-    <rule ref="WordPress-VIP"></rule>
+    <rule ref="WordPress-VIP">
+        <exclude name="WordPress.VIP.SuperGlobalInputUsage" />
+        <exclude name="WordPress.VIP.RestrictedFunctions.switch_to_blog" />
+    </rule>
+    <rule ref="WordPress-Core"></rule>
+    <rule ref="WordPress"></rule>
 </ruleset>
diff --git a/app/boilerplates/simple/app/admin/class-app.php b/app/boilerplates/simple/app/admin/class-app.php
@@ -6,47 +6,47 @@
  * @subpackage <%= PKG %>
  */
 
-namespace < %= PRIMARY_NAMESPACE %>\< %= SECONDARY_NAMESPACE %>\Admin;
+namespace <%= PRIMARY_NAMESPACE %>\<%= SECONDARY_NAMESPACE %>\Admin;
 
 /**
  * Class App
  */
 class App {
 
 	/**
-	 * Plugins class object installed directory on the server
+	 * Plugins class object installed directory on the server.
 	 *
-	 * @var string $installed_dir Installed server directory
+	 * @var string $installed_dir Installed server directory.
 	 */
 	public $installed_dir;
 
 	/**
-	 * Plugins URL for access to any static files or assets like css, js, or media
+	 * Plugins URL for access to any static files or assets like css, js, or media.
 	 *
-	 * @var string $installed_url Installed URL
+	 * @var string $installed_url Installed URL.
 	 */
 	public $installed_url;
 
 	/**
-	 * If plugin_data is built, this represents the version number defined the the main plugin file meta
+	 * If plugin_data is built, this represents the version number defined the the main plugin file meta.
 	 *
-	 * @var string $version Version
+	 * @var string $version Version.
 	 */
 	public $version;
 
 	/**
 	 * Add auth'd/admin functionality via new Class() instantiation, add_action() and add_filter() in this method.
 	 *
-	 * @param string $installed_dir Installed server directory
-	 * @param string $installed_url Installed URL
-	 * @param string $version       Version
+	 * @param string $installed_dir Installed server directory.
+	 * @param string $installed_url Installed URL.
+	 * @param string $version       Version.
 	 */
 	function __construct( $installed_dir, $installed_url, $version ) {
 		$this->installed_dir = $installed_dir;
 		$this->installed_url = $installed_url;
 		$this->version       = $version;
 
-		// Put your new Class() or add_action() here.
+		// Put your new PHP Class or add_action method here.
 	}
 
 }
diff --git a/app/boilerplates/simple/app/class-plugin.php b/app/boilerplates/simple/app/class-plugin.php
@@ -8,15 +8,9 @@
 
 namespace <%= PRIMARY_NAMESPACE %>\<%= SECONDARY_NAMESPACE %>;
 
-use <%= PRIMARY_NAMESPACE %>\< %= SECONDARY_NAMESPACE %>\Admin;;
+use <%= PRIMARY_NAMESPACE %>\<%= SECONDARY_NAMESPACE %>\Admin;
 use <%= ABSTRACT_PLUGIN_NAMESPACE %>\Abstract_Plugin;
 
-if ( ! function_exists( 'add_filter' ) ) {
-	header( 'Status: 403 Forbidden' );
-	header( 'HTTP/1.1 403 Forbidden' );
-	exit(); /* protects plugin source from public view */
-}
-
 /**
  * Class Plugin
  */
@@ -81,6 +75,8 @@ public function authenticated_init() {
 	}
 
 	/**
+	 * Defines and Globals.
+	 *
 	 * @return mixed|void
 	 */
 	protected function defines_and_globals() {
diff --git a/app/boilerplates/simple/composer-test.json b/app/boilerplates/simple/composer-test.json
@@ -7,6 +7,6 @@
 	"wp-coding-standards/wpcs": "^0.10"
   },
   "scripts": {
-	"test": "./bin/phpcs --standard=./.circleci/codesniffer.ruleset.xml --extensions='php,js,css' ./"
+	"test": "./bin/phpcs --standard=./.circleci/codesniffer.ruleset.xml --extensions='php,css' ./"
   }
-}
+}
diff --git a/app/boilerplates/simple/main.php b/app/boilerplates/simple/main.php
@@ -8,7 +8,6 @@
  * @author         <%= AUTHORS %><%= TEAM %>
  * @license        <%= LICENSE_TEXT %>
  * @link           <%= URL %>
- * @version        <%= VERSION %>
  *
  * Built with WP PHX WordPress Development Toolkit v<%= GENERATOR_VERSION %> on <%= CURRENT_TIME %>
  * @link           https://github.com/WordPress-Phoenix/wordpress-development-toolkit
@@ -22,11 +21,7 @@
  * License: <%= LICENSE_TEXT %>
  */
 
-if ( ! function_exists( 'add_filter' ) ) {
-	header( 'Status: 403 Forbidden' );
-	header( 'HTTP/1.1 403 Forbidden' );
-	exit(); /* protects plugin source from public view */
-}
+defined( 'ABSPATH' ) or die(); // WordPress must exist.
 
 $current_dir = trailingslashit( dirname( __FILE__ ) );
 
@@ -43,4 +38,4 @@
  */
 include_once $current_dir . 'app/class-plugin.php';
 
-< %= PRIMARY_NAMESPACE %>\< %= SECONDARY_NAMESPACE %>\Plugin::run( __FILE__ );
+<%= PRIMARY_NAMESPACE %>\<%= SECONDARY_NAMESPACE %>\Plugin::run( __FILE__ );
diff --git a/app/class-plugin.php b/app/class-plugin.php
@@ -5,9 +5,9 @@
  * @package WordPress
  */
 
-namespace PHX_WP_DEVKIT\V_3_0;
+namespace PHX_WP_DEVKIT\V_3_1;
 
-use PHX_WP_DEVKIT\V_3_0\Admin;
+use PHX_WP_DEVKIT\V_3_1\Admin;
 use WPAZ_Plugin_Base\V_2_6\Abstract_Plugin;
 
 /**
diff --git a/docs/best-practices-asset-management.md b/docs/best-practices-asset-management.md
@@ -1,5 +1,13 @@
 # WordPress Asset Management Best Practices
 
+##### WordPress uses internal functions to register *(`wp_register_script()` & `wp_register_style()`)* and enqueue *(`wp_enqueue_script()` & `wp-enqueue_style()`)* static JavaScript and CSS files so that WordPress Core, Themes and Plugins can **programatically interact with scripts and styles.**
+
+This approach allows WordPress to:
+  1. Load registered dependencies
+  1. Chose the printing order & location of files in the DOM
+  1. Print inline script/style alongside referenced files
+  1. Print inline js variables to make PHP data safely available to the script via the Window variable (`wp_localize_script()` -- originally used for "localizing" translated strings from WordPress language packs into in labels needed in scripts).
+
 #### Break `wp_register_script()` and `wp_register_style()` arguments onto their own lines
 
 This is a matter of preference and judgement, but these registrations are super important, often overrun 80 characters and are worth breaking out to multiple lines for easy locating in files and nice code hygene.
@@ -8,17 +16,20 @@ This is a matter of preference and judgement, but these registrations are super
 
 Always register CSS and JavaScript first instead of directly enqueueing them. This makes dequeueing easier for other products interacting with your dependency in the environment.
 
-###### Additionally, always register assets globally. Never scope a script registration inside `is_admin()` or another check to prevent registration collision.
+#### Always register assets globally
 
-#### Store dependency handles in accessible variables and constants
+Never scope a script registration inside `is_admin()` or another check to prevent registration collision. Only scope enqueues.
 
-When registering CSS or JS within a PHP class, always store the asset handle as a class variable. When registering a dependency outside a class, define a PHP constant. This allows the entire class and application interact programmatically with the asset, preventing string scavenger hunts across files and easing rename.
+#### Store the string used to register/enqueue an asset in a static class variable or PHP constant
+
+This allows the entire class and application interact programmatically with the asset, preventing string scavenger hunts across files and easing rename.
 
 #### Naming dependency handle slugs
 * **This is a global namespace**. Be creative, be courteous, be concise, be clear and be defensive.
-* Please don't describe the asset with a postfix like `-js`, `-css`, `-script`, `-style` -- WordPress will add postfixes when printing assets in the DOM, resulting in `something-js-js`. However, if a product is called purecss or momentjs, we then use the full slug with repetitive postfix, despite repetion (i.e. `purecss-css`)
-* When appropriate, try to match the filename. This makes life easier and applications scale nicer.
-* Never use WordPress Filters or difficult-to-predict dynamic variables to register asset handles so others may dequeue and register handles with confidence.
+* **Please don't use a postfix like `-js`, `-css`, `-script`, `-style`** -- WordPress will add postfixes when printing assets in the DOM, resulting in `something-js-js`. However, if a product is called purecss or momentjs, we then use the full slug with repetitive postfix, despite repetion (i.e. `purecss-css`)
+* **Try to keep parity between filename and dependency string**. This makes life easier and applications scale nicer.
+* **Plan for growth: avoid calling dependency `my-product`** Use `-primary`, `-core` or `-main` postfix.
+* **Never use WordPress Filters or difficult-to-predict dynamic variables** so others may dequeue and register handles with confidence.
 
 #### Leverage dependency chaining and the `array()` method for `wp_enqueue_*()`
 
@@ -52,4 +63,7 @@ WordPress does little to prevent the collision of scripts. Short of defining dep
 Plus at time of writing it's 2017 and React and Vue-based apps, use of JavaScript tools is becoming more prevalent. Some of these authors create a rollup file of dependencies and a rollup of their app. Even in an environment you control, you likely rely on some 3rd party plugins that load dependencies.
 
 #### Provide a version string for caching
-We recommend tying product assets the version for the Theme or Plugin you're in. Having a condition that checks for local environments (i.e. check request string for ".test") and toggling between a production version and a `rand(0,PHP_INT_MAX)` is another good option.
+We recommend tying product assets the version for the Theme or Plugin you're in. Having a condition that checks for local environments (i.e. check request string for ".test") and toggling between a production version and `time()` is another good option for cache-busting on a local env.
+
+###### NEW: Working with Assets containing cache-hash
+Often when working with JavaScript SPA frameworks and tools, a unique hash is generated in the filename. To account for these assets
diff --git a/phpcs.xml b/phpcs.xml
@@ -1,9 +1,11 @@
 <?xml version="1.0"?>
 <ruleset name="wp-enterprise-core">
 	<description>Code standard for Enterprise WordPress development</description>
+	<exclude-pattern>app/boilerplates/*</exclude-pattern>
+	<exclude-pattern>vendor/*</exclude-pattern>
 	<exclude-pattern>vendor/*</exclude-pattern>
 	<exclude-pattern>tests/bootstrap.php</exclude-pattern>
 	<rule ref="WordPress-VIP"></rule>
 	<rule ref="WordPress-Core"></rule>
 	<rule ref="WordPress"></rule>
-</ruleset>
+</ruleset>
diff --git a/wordpress-development-toolkit.php b/wordpress-development-toolkit.php
@@ -6,7 +6,7 @@
  * @author      David Ryan - WordPress Phoenix
  * @license     GNU GPL v2.0+
  * @link        https://github.com/wordpress-phoenix
- * @version     3.0.5
+ * @version     3.1.0
  *
  * Built using WP PHX Plugin Generator v1.1.0 on Tuesday 23rd of January 2018 07:33:12 AM
  * @link https://github.com/WordPress-Phoenix/wordpress-development-toolkit
@@ -15,7 +15,7 @@
  * Plugin Name: WordPress Development Toolkit
  * Plugin URI: https://github.com/wordpress-phoenix
  * Description: Tools and resources for WordPress development.
- * Version: 3.0.4
+ * Version: 3.1.0
  * Author: David Ryan  - WordPress Phoenix
  * Text Domain: wordpress-development-toolkit
  * License: GNU GPL v2.0+
@@ -38,7 +38,7 @@
  * Check PHX_WP_DEVKIT\V_1_2\Plugin Instantiated
  * (The check prevents fatal error if multiple copies of plugin are activated or namespaces aren't unique)
  */
-if ( ! class_exists( 'PHX_WP_DEVKIT\\V_3_0\\Plugin' ) ) {
+if ( ! class_exists( 'PHX_WP_DEVKIT\\V_3_1\\Plugin' ) ) {
 	include_once trailingslashit( dirname( __FILE__ ) ) . 'app/class-plugin.php';
 } else {
 	new WP_Error( '500', 'Multiple copies of PHX_WP_DEVKIT\V_1_2\Plugin are active' );
@@ -47,4 +47,4 @@
 /**
  * Start WordPress Development Toolkit Main Plugin Class
  */
-PHX_WP_DEVKIT\V_3_0\Plugin::run( __FILE__ );
+PHX_WP_DEVKIT\V_3_1\Plugin::run( __FILE__ );
