Merge pull request #1267 from jrfnl/feature/cs-update

Bring code style up to the latest standards
- This PR addresses code-style issues identified when testing the code against the WordPress Coding Standards.

.github/CONTRIBUTING.md

@@ -22,6 +22,7 @@ Found a bug you can fix? Fantastic! Patches are always welcome. Here's a few tip
 * Include the purpose of your PR. Be explicit about the issue your PR solves.
 * Reference any existing issues that relate to your PR. This allows everyone to easily see all related discussions.
 * When submitting a change that affects CSS, please make sure that both SCSS sources and output CSS have been updated equally.
+* `_s` complies with the [WordPress Coding Standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/) and any PR should comply as well.
 
 By contributing code to `_s`, you grant its use under the [GNU General Public License v2 (or later)](LICENSE).
 

.travis.yml

@@ -50,16 +50,17 @@ before_script:
     - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
     # Set up temporary paths.
     - export PHPCS_DIR=/tmp/phpcs
-    - export SNIFFS_DIR=/tmp/sniffs
+    - export WPCS_DIR=/tmp/wpcs
+    - export PHPCOMPAT_DIR=/tmp/phpcompatibility
     # Install CodeSniffer for WordPress Coding Standards checks.
-    - if [[ "$SNIFF" == "1" ]]; then git clone -b 2.9.1 --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR; fi
+    - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR; fi
     # Install WordPress Coding Standards.
-    - if [[ "$SNIFF" == "1" ]]; then git clone -b 0.11.0 --depth 1 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git $SNIFFS_DIR; fi
+    - if [[ "$SNIFF" == "1" ]]; then git clone -b 0.14.1 --depth 1 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git $WPCS_DIR; fi
     # Install PHP Compatibility sniffs.
-    - if [[ "$SNIFF" == "1" ]]; then git clone -b 7.1.5 --depth 1 https://github.com/wimg/PHPCompatibility.git $SNIFFS_DIR/PHPCompatibility; fi
+    - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/wimg/PHPCompatibility.git $PHPCOMPAT_DIR; fi
     # Set install path for PHPCS sniffs.
     # @link https://github.com/squizlabs/PHP_CodeSniffer/blob/4237c2fc98cc838730b76ee9cee316f99286a2a7/CodeSniffer.php#L1941
-    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/scripts/phpcs --config-set installed_paths $SNIFFS_DIR; fi
+    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/bin/phpcs --config-set installed_paths $WPCS_DIR,$PHPCOMPAT_DIR; fi
     # After CodeSniffer install you should refresh your path.
     - if [[ "$SNIFF" == "1" ]]; then phpenv rehash; fi
     # Install JSCS: JavaScript Code Style checker.
@@ -86,7 +87,7 @@ script:
     # @link https://pear.php.net/package/PHP_CodeSniffer/
     # Uses a custom ruleset based on WordPress. This ruleset is automatically
     # picked up by PHPCS as it's named `phpcs.xml(.dist)`.
-    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/scripts/phpcs; fi
+    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/bin/phpcs --runtime-set ignore_warnings_on_exit 1; fi
 
 # Receive notifications for build results.
 # @link https://docs.travis-ci.com/user/notifications/#Email-notifications

404.php

@@ -7,7 +7,8 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<div id="primary" class="content-area">
 		<main id="main" class="site-main">
@@ -42,10 +43,9 @@ get_header(); ?>
 					</div><!-- .widget -->
 
 					<?php
-
 					/* translators: %1$s: smiley */
-						$archive_content = '<p>' . sprintf( esc_html__( 'Try looking in the monthly archives. %1$s', '_s' ), convert_smilies( ':)' ) ) . '</p>';
+					$_s_archive_content = '<p>' . sprintf( esc_html__( 'Try looking in the monthly archives. %1$s', '_s' ), convert_smilies( ':)' ) ) . '</p>';
-						the_widget( 'WP_Widget_Archives', 'dropdown=1', "after_title=</h2>$archive_content" );
+					the_widget( 'WP_Widget_Archives', 'dropdown=1', "after_title=</h2>$_s_archive_content" );
 
 					the_widget( 'WP_Widget_Tag_Cloud' );
 					?>

archive.php

@@ -7,13 +7,13 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<div id="primary" class="content-area">
 		<main id="main" class="site-main">
 
-		<?php
+		<?php if ( have_posts() ) : ?>
-		if ( have_posts() ) : ?>
 
 			<header class="page-header">
 				<?php
@@ -24,7 +24,8 @@ get_header(); ?>
 
 			<?php
 			/* Start the Loop */
-			while ( have_posts() ) : the_post();
+			while ( have_posts() ) :
+				the_post();
 
 				/*
 				 * Include the Post-Type-specific template for the content.
@@ -41,7 +42,8 @@ get_header(); ?>
 
 			get_template_part( 'template-parts/content', 'none' );
 
-		endif; ?>
+		endif;
+		?>
 
 		</main><!-- #main -->
 	</div><!-- #primary -->

comments.php

@@ -24,11 +24,12 @@ if ( post_password_required() ) {
 
 	<?php
 	// You can start editing here -- including this comment!
-	if ( have_comments() ) : ?>
+	if ( have_comments() ) :
+		?>
 		<h2 class="comments-title">
 			<?php
-			$comment_count = get_comments_number();
+			$_s_comment_count = get_comments_number();
-			if ( '1' === $comment_count ) {
+			if ( '1' === $_s_comment_count ) {
 				printf(
 					/* translators: 1: title. */
 					esc_html__( 'One thought on &ldquo;%1$s&rdquo;', '_s' ),
@@ -37,8 +38,8 @@ if ( post_password_required() ) {
 			} else {
 				printf( // WPCS: XSS OK.
 					/* translators: 1: comment count number, 2: title. */
-					esc_html( _nx( '%1$s thought on &ldquo;%2$s&rdquo;', '%1$s thoughts on &ldquo;%2$s&rdquo;', $comment_count, 'comments title', '_s' ) ),
+					esc_html( _nx( '%1$s thought on &ldquo;%2$s&rdquo;', '%1$s thoughts on &ldquo;%2$s&rdquo;', $_s_comment_count, 'comments title', '_s' ) ),
-					number_format_i18n( $comment_count ),
+					number_format_i18n( $_s_comment_count ),
 					'<span>' . get_the_title() . '</span>'
 				);
 			}
@@ -56,10 +57,12 @@ if ( post_password_required() ) {
 			?>
 		</ol><!-- .comment-list -->
 
-		<?php the_comments_navigation();
+		<?php
+		the_comments_navigation();
 
 		// If comments are closed and there are comments, let's leave a little note, shall we?
-		if ( ! comments_open() ) : ?>
+		if ( ! comments_open() ) :
+			?>
 			<p class="no-comments"><?php esc_html_e( 'Comments are closed.', '_s' ); ?></p>
 			<?php
 		endif;

footer.php

@@ -15,10 +15,12 @@
 
 	<footer id="colophon" class="site-footer">
 		<div class="site-info">
-			<a href="<?php echo esc_url( __( 'https://wordpress.org/', '_s' ) ); ?>"><?php
+			<a href="<?php echo esc_url( __( 'https://wordpress.org/', '_s' ) ); ?>">
+				<?php
 				/* translators: %s: CMS name, i.e. WordPress. */
 				printf( esc_html__( 'Proudly powered by %s', '_s' ), 'WordPress' );
-			?></a>
+				?>
+			</a>
 			<span class="sep"> | </span>
 				<?php
 				/* translators: 1: Theme name, 2: Theme author. */

functions.php

@@ -91,6 +91,9 @@ add_action( 'after_setup_theme', '_s_setup' );
  * @global int $content_width
  */
 function _s_content_width() {
+	// This variable is intended to be overruled from themes.
+	// Open WPCS issue: {@link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1043}.
+	// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound
 	$GLOBALS['content_width'] = apply_filters( '_s_content_width', 640 );
 }
 add_action( 'after_setup_theme', '_s_content_width', 0 );

header.php

@@ -28,18 +28,20 @@
 		<div class="site-branding">
 			<?php
 			the_custom_logo();
-			if ( is_front_page() && is_home() ) : ?>
+			if ( is_front_page() && is_home() ) :
+				?>
 				<h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></h1>
-			<?php else : ?>
+				<?php
+			else :
+				?>
 				<p class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></p>
 				<?php
 			endif;
-
+			$_s_description = get_bloginfo( 'description', 'display' );
-			$description = get_bloginfo( 'description', 'display' );
+			if ( $_s_description || is_customize_preview() ) :
-			if ( $description || is_customize_preview() ) : ?>
+				?>
-				<p class="site-description"><?php echo $description; /* WPCS: xss ok. */ ?></p>
+				<p class="site-description"><?php echo $_s_description; /* WPCS: xss ok. */ ?></p>
-			<?php
+			<?php endif; ?>
-			endif; ?>
 		</div><!-- .site-branding -->
 
 		<nav id="site-navigation" class="main-navigation">

inc/template-tags.php

@@ -112,13 +112,13 @@ if ( ! function_exists( '_s_entry_footer' ) ) :
 endif;
 
 if ( ! function_exists( '_s_post_thumbnail' ) ) :
-/**
+	/**
 	 * Displays an optional post thumbnail.
 	 *
 	 * Wraps the post thumbnail in an anchor element on index views, or a div
 	 * element when on single views.
 	 */
-function _s_post_thumbnail() {
+	function _s_post_thumbnail() {
 		if ( post_password_required() || is_attachment() || ! has_post_thumbnail() ) {
 			return;
 		}
@@ -142,6 +142,7 @@ function _s_post_thumbnail() {
 			?>
 		</a>
 
-	<?php endif; // End is_singular().
+		<?php
-}
+		endif; // End is_singular().
+	}
 endif;

inc/woocommerce.php

@@ -225,8 +225,14 @@ if ( ! function_exists( '_s_woocommerce_cart_link' ) ) {
 	function _s_woocommerce_cart_link() {
 		?>
 		<a class="cart-contents" href="<?php echo esc_url( wc_get_cart_url() ); ?>" title="<?php esc_attr_e( 'View your shopping cart', '_s' ); ?>">
-				<?php /* translators: number of items in the mini cart. */ ?>
+			<?php
-				<span class="amount"><?php echo wp_kses_data( WC()->cart->get_cart_subtotal() ); ?></span> <span class="count"><?php echo wp_kses_data( sprintf( _n( '%d item', '%d items', WC()->cart->get_cart_contents_count(), '_s' ), WC()->cart->get_cart_contents_count() ) );?></span>
+			$item_count_text = sprintf(
+				/* translators: number of items in the mini cart. */
+				_n( '%d item', '%d items', WC()->cart->get_cart_contents_count(), '_s' ),
+				WC()->cart->get_cart_contents_count()
+			);
+			?>
+			<span class="amount"><?php echo wp_kses_data( WC()->cart->get_cart_subtotal() ); ?></span> <span class="count"><?php echo esc_html( $item_count_text ); ?></span>
 		</a>
 		<?php
 	}

inc/wpcom.php

@@ -17,6 +17,8 @@ function _s_wpcom_setup() {
 
 	// Set theme colors for third party services.
 	if ( ! isset( $themecolors ) ) {
+		// Whitelist wpcom specific variable intended to be overruled.
+		// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound
 		$themecolors = array(
 			'bg'     => '',
 			'border' => '',

index.php

@@ -12,7 +12,8 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<div id="primary" class="content-area">
 		<main id="main" class="site-main">
@@ -20,16 +21,17 @@ get_header(); ?>
 		<?php
 		if ( have_posts() ) :
 
-			if ( is_home() && ! is_front_page() ) : ?>
+			if ( is_home() && ! is_front_page() ) :
+				?>
 				<header>
 					<h1 class="page-title screen-reader-text"><?php single_post_title(); ?></h1>
 				</header>
-
 				<?php
 			endif;
 
 			/* Start the Loop */
-			while ( have_posts() ) : the_post();
+			while ( have_posts() ) :
+				the_post();
 
 				/*
 				 * Include the Post-Type-specific template for the content.
@@ -46,7 +48,8 @@ get_header(); ?>
 
 			get_template_part( 'template-parts/content', 'none' );
 
-		endif; ?>
+		endif;
+		?>
 
 		</main><!-- #main -->
 	</div><!-- #primary -->

page.php

@@ -12,13 +12,15 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<div id="primary" class="content-area">
 		<main id="main" class="site-main">
 
 		<?php
-			while ( have_posts() ) : the_post();
+		while ( have_posts() ) :
+			the_post();
 
 			get_template_part( 'template-parts/content', 'page' );
 

phpcs.xml.dist

@@ -8,13 +8,25 @@
 	<!-- Set a description for this ruleset. -->
 	<description>A custom set of code standard rules to check for WordPress themes.</description>
 
+
+	<!--
+	#############################################################################
+	COMMAND LINE ARGUMENTS
+	https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
+	#############################################################################
+	-->
+
 	<!-- Pass some flags to PHPCS:
 		 p flag: Show progress of the run.
 		 s flag: Show sniff codes in all reports.
-		 v flag: Print verbose output.
-		 n flag: Do not print warnings.
 	-->
-	<arg value="psvn"/>
+	<arg value="ps"/>
+
+	<!-- Strip the filepaths down to the relevant bit. -->
+	<arg name="basepath" value="./"/>
+
+	<!-- Check up to 8 files simultanously. -->
+	<arg name="parallel" value="8"/>
 
 	<!-- Only check the PHP, CSS and SCSS files. JS files are checked separately with JSCS and JSHint. -->
 	<arg name="extensions" value="php,css,scss/css"/>
@@ -22,18 +34,27 @@
 	<!-- Check all files in this directory and the directories below it. -->
 	<file>.</file>
 
-	<!-- Include the WordPress ruleset, with exclusions. -->
+
-	<rule ref="WordPress">
+	<!--
-		<exclude name="Generic.WhiteSpace.ScopeIndent.IncorrectExact" />
+	#############################################################################
-		<exclude name="Generic.WhiteSpace.ScopeIndent.Incorrect" />
+	USE THE WordPress RULESET
-		<exclude name="PEAR.Functions.FunctionCallSignature.Indent" />
+	#############################################################################
-	</rule>
+	-->
+
+	<rule ref="WordPress"/>
+
+
+	<!--
+	#############################################################################
+	SNIFF SPECIFIC CONFIGURATION
+	#############################################################################
+	-->
 
 	<!-- Verify that the text_domain is set to the desired text-domain.
 		 Multiple valid text domains can be provided as a comma-delimited list. -->
 	<rule ref="WordPress.WP.I18n">
 		<properties>
-			<property name="text_domain" type="array" value="_s" />
+			<property name="text_domain" type="array" value="_s"/>
 		</properties>
 	</rule>
 
@@ -41,20 +62,71 @@
 		 on the theme hierarchy. -->
 	<rule ref="WordPress.Files.FileName">
 		<properties>
-			<property name="is_theme" value="true" />
+			<property name="is_theme" value="true"/>
 		</properties>
 	</rule>
 
-	<!-- Verify that no WP functions are used which are deprecated or have been removed.
+	<!-- Set the minimum supported WP version. This is used by several sniffs.
 		 The minimum version set here should be in line with the minimum WP version
 		 as set in the "Requires at least" tag in the readme.txt file. -->
-	<rule ref="WordPress.WP.DeprecatedFunctions">
+	<config name="minimum_supported_wp_version" value="4.5"/>
+
+	<rule ref="WordPress.Arrays.MultipleStatementAlignment">
 		<properties>
-			<property name="minimum_supported_version" value="4.0" />
+			<!-- No need to adjust alignment of large arrays when the item with the largest key is removed. -->
+			<property name="exact" value="false"/>
+			<!-- Don't align multi-line items if ALL items in the array are multi-line. -->
+			<property name="alignMultilineItems" value="!=100"/>
+			<!-- Array assignment operator should always be on the same line as the array key. -->
+			<property name="ignoreNewlines" value="false"/>
 		</properties>
 	</rule>
 
-	<!-- Include sniffs for PHP cross-version compatibility. -->
+	<!-- Verify that everything in the global namespace is prefixed with a theme specific prefix.
+		 Multiple valid prefixes can be provided as a comma-delimited list. -->
+	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
+		<properties>
+			<property name="prefixes" type="array" value="_s" />
+		</properties>
+	</rule>
+
+
+	<!--
+	#############################################################################
+	USE THE PHPCompatibility RULESET
+	#############################################################################
+	-->
+
+
 	<config name="testVersion" value="5.2-99.0"/>
-	<rule ref="PHPCompatibility"/>
+	<rule ref="PHPCompatibility">
+		<!-- Whitelist PHP native classes, interfaces, functions and constants which
+			 are back-filled by WP.
+
+			 Based on:
+			 * /wp-includes/compat.php
+			 * /wp-includes/random_compat/random.php
+		-->
+		<exclude name="PHPCompatibility.PHP.NewClasses.errorFound"/>
+		<exclude name="PHPCompatibility.PHP.NewClasses.typeerrorFound"/>
+
+		<exclude name="PHPCompatibility.PHP.NewConstants.json_pretty_printFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.php_version_idFound"/>
+
+		<exclude name="PHPCompatibility.PHP.NewFunctions.hash_equalsFound"/>
+		<exclude name="PHPCompatibility.PHP.NewFunctions.json_last_error_msgFound"/>
+		<exclude name="PHPCompatibility.PHP.NewFunctions.random_intFound"/>
+		<exclude name="PHPCompatibility.PHP.NewFunctions.random_bytesFound"/>
+		<exclude name="PHPCompatibility.PHP.NewFunctions.array_replace_recursiveFound"/>
+
+		<exclude name="PHPCompatibility.PHP.NewInterfaces.jsonserializableFound"/>
+	</rule>
+
+	<!-- Whitelist the WP Core mysql_to_rfc3339() function. -->
+	<rule ref="PHPCompatibility.PHP.RemovedExtensions">
+		<properties>
+			<property name="functionWhitelist" type="array" value="mysql_to_rfc3339"/>
+		</properties>
+	</rule>
+
 </ruleset>

search.php

@@ -7,24 +7,27 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<section id="primary" class="content-area">
 		<main id="main" class="site-main">
 
-		<?php
+		<?php if ( have_posts() ) : ?>
-		if ( have_posts() ) : ?>
 
 			<header class="page-header">
-				<h1 class="page-title"><?php
+				<h1 class="page-title">
+					<?php
 					/* translators: %s: search query. */
 					printf( esc_html__( 'Search Results for: %s', '_s' ), '<span>' . get_search_query() . '</span>' );
-				?></h1>
+					?>
+				</h1>
 			</header><!-- .page-header -->
 
 			<?php
 			/* Start the Loop */
-			while ( have_posts() ) : the_post();
+			while ( have_posts() ) :
+				the_post();
 
 				/**
 				 * Run the loop for the search to output the results.
@@ -41,7 +44,8 @@ get_header(); ?>
 
 			get_template_part( 'template-parts/content', 'none' );
 
-		endif; ?>
+		endif;
+		?>
 
 		</main><!-- #main -->
 	</section><!-- #primary -->

single.php

@@ -7,13 +7,15 @@
  * @package _s
  */
 
-get_header(); ?>
+get_header();
+?>
 
 	<div id="primary" class="content-area">
 		<main id="main" class="site-main">
 
 		<?php
-		while ( have_posts() ) : the_post();
+		while ( have_posts() ) :
+			the_post();
 
 			get_template_part( 'template-parts/content', get_post_type() );
 

template-parts/content-none.php

@@ -16,11 +16,10 @@
 
 	<div class="page-content">
 		<?php
-		if ( is_home() && current_user_can( 'publish_posts' ) ) : ?>
+		if ( is_home() && current_user_can( 'publish_posts' ) ) :
 
-			<p><?php
 			printf(
-					wp_kses(
+				'<p>' . wp_kses(
 					/* translators: 1: link to WP admin new post page. */
 					__( 'Ready to publish your first post? <a href="%1$s">Get started here</a>.', '_s' ),
 					array(
@@ -28,23 +27,25 @@
 							'href' => array(),
 						),
 					)
-					),
+				) . '</p>',
 				esc_url( admin_url( 'post-new.php' ) )
 			);
-			?></p>
 
-		<?php elseif ( is_search() ) : ?>
+		elseif ( is_search() ) :
+			?>
 
 			<p><?php esc_html_e( 'Sorry, but nothing matched your search terms. Please try again with some different keywords.', '_s' ); ?></p>
 			<?php
 			get_search_form();
 
-		else : ?>
+		else :
+			?>
 
 			<p><?php esc_html_e( 'It seems we can&rsquo;t find what you&rsquo;re looking for. Perhaps searching can help.', '_s' ); ?></p>
 			<?php
 			get_search_form();
 
-		endif; ?>
+		endif;
+		?>
 	</div><!-- .page-content -->
 </section><!-- .no-results -->

template-parts/content.php

@@ -18,15 +18,15 @@
 			the_title( '<h2 class="entry-title"><a href="' . esc_url( get_permalink() ) . '" rel="bookmark">', '</a></h2>' );
 		endif;
 
-		if ( 'post' === get_post_type() ) : ?>
+		if ( 'post' === get_post_type() ) :
+			?>
 			<div class="entry-meta">
 				<?php
 				_s_posted_on();
 				_s_posted_by();
 				?>
 			</div><!-- .entry-meta -->
-		<?php
+		<?php endif; ?>
-		endif; ?>
 	</header><!-- .entry-header -->
 
 	<?php _s_post_thumbnail(); ?>