Merge pull request #773 from WebDevStudios/feature/#769-function-naming

Adds namespacing and makes function naming more consistent.

404.php

@@ -4,7 +4,7 @@
  *
  * @link https://codex.wordpress.org/Creating_an_Error_404_Page
  *
- * @package _s
+ * @package wd_s
  */
 
 get_header(); ?>
@@ -13,12 +13,12 @@
 
 		<section class="error-404 not-found">
 			<header class="page-header">
-				<h1 class="page-title"><?php esc_html_e( "Sorry, this page doesn't exist.", '_s' ); ?></h1>
+				<h1 class="page-title"><?php esc_html_e( "Sorry, this page doesn't exist.", 'wd_s' ); ?></h1>
 			</header><!-- .page-header -->
 
 			<div class="page-content">
 
-				<p><?php esc_html_e( "It seems we can't find what you're looking for. Perhaps searching can help.", '_s' ); ?></p>
+				<p><?php esc_html_e( "It seems we can't find what you're looking for. Perhaps searching can help.", 'wd_s' ); ?></p>
 
 				<?php get_search_form(); ?>
 

README.md

@@ -53,15 +53,20 @@ If you want to set me up manually:
 
 2. Find & Replace
 
-You'll need to change all instances of the names: `_s`.
-
-- Search for: `'_s'` and replace with: `'project-name'` (inside single quotations) to capture the text domain
-- Search for: `"_s"` and replace with: `"project-name"` (inside double quotations) to capture the text domain
-- Search for: `_s_` and replace with: `project-name_` to capture all the function names
-- Search for: `Text Domain: _s` and replace with: `Text Domain: project-name` in style.css
-- Search for (and include the leading space): ` _s` and replace with: ` Project Name` (with a space before it) to capture DocBlocks
-- Search for: `_s-` and replace with: `project-name-` to capture prefixed handles
-- Search for `_s.pot` and replace with: `project-name.pot` to capture translation files
+You'll need to change all instances of the name: `wd_s`.
+
+- Search for: `@package wd_s` and replace with: `@package project_name` to capture the package name
+- Update `"WebDevStudios\wd_s,wd_s"` to: `"CompanyName\project_name,project_name"` (with double quotes) in phpcs.xml.dist
+- Search for: `WebDevStudios\wd_s` and replace with: `CompanyName\project_name` to capture the namespaces
+- Update `"webdevstudios/wd_s"` to `"companyname/project_name"` (with double quotes) in composer.json
+- Search for: `, 'wd_s'` and replace with: `, 'project_name'` (inside backticks) to capture the text domain
+- Update `Text Domain: wd_s` to: `Text Domain: project_name` in style.css
+- Update `"wd_s"` to: `"project_name"` (with double quotes) in phpcs.xml.dist and package.json
+- Update `'wd_s'` to: `'project_name'` (with single quotes) in inc/setup/setup.php
+- Search for: `wd_s_` and replace with: `project_name_` to capture all the function names
+- Search for: `'wd_s-` and replace with: `'project_name-` to capture prefixed handles
+- Search for `wd_s.pot` and replace with: `project_name.pot` to capture translation files
+- Search for `wdunderscores.test` and replace with: `project_name.test` to match your local development URL
 - Edit the theme information in the header of style.scss to meet your needs
 
 ## Setup

archive.php

@@ -4,43 +4,46 @@
  *
  * @link https://codex.wordpress.org/Template_Hierarchy
  *
- * @package _s
+ * @package wd_s
  */
 
+use function WebDevStudios\wd_s\print_numeric_pagination;
+
 get_header(); ?>
 
-	<main id="main" class="container site-main">
+<main id="main" class="container site-main">
 
-		<?php if ( have_posts() ) : ?>
+	<?php if ( have_posts() ) : ?>
 
-			<header class="page-header">
-				<?php
+	<header class="page-header">
+		<?php
 				the_archive_title( '<h1 class="page-title">', '</h1>' );
 				the_archive_description( '<div class="archive-description">', '</div>' );
-				?>
-			</header><!-- .page-header -->
+		?>
+	</header><!-- .page-header -->
 
-			<?php
+		<?php
 			/* Start the Loop */
-			while ( have_posts() ) :
-				the_post();
+		while ( have_posts() ) :
+			the_post();
 
-				/**
-				 * Include the Post-Format-specific template for the content.
-				 * If you want to override this in a child theme, then include a file
-				 * called content-___.php (where ___ is the Post Format name) and that will be used instead.
-				 */
-				get_template_part( 'template-parts/content', get_post_format() );
+			/**
+			 * Include the Post-Format-specific template for the content.
+			 * If you want to override this in a child theme, then include a file
+			 * called content-___.php (where ___ is the Post Format name) and that will be used instead.
+			 */
+			get_template_part( 'template-parts/content', get_post_format() );
 
 			endwhile;
 
-			_s_display_numeric_pagination();
+			print_numeric_pagination();
 
 		else :
 			get_template_part( 'template-parts/content', 'none' );
 		endif;
 		?>
 
-	</main><!-- #main -->
+</main><!-- #main -->
 
-<?php get_footer(); ?>
+<?php get_footer();
+?>

comments.php

@@ -7,21 +7,22 @@
  *
  * @link https://codex.wordpress.org/Template_Hierarchy
  *
- * @package _s
+ * @package wd_s
  */
 
 /**
  * If the current post is protected by a password and
  * the visitor has not yet entered the password we will
  * return early without loading the comments.
  */
+
 if ( post_password_required() ) {
 	return;
 }
 ?>
 
 <div id="comments" class="container comments-area">
-	<h2 class="screen-reader-text"><?php esc_html_e( 'Comment section', '_s' ); ?></h2>
+	<h2 class="screen-reader-text"><?php esc_html_e( 'Comment section', 'wd_s' ); ?></h2>
 
 	<?php
 	// You can start editing here -- including this comment!
@@ -31,7 +32,7 @@
 			<?php
 			printf(
 				/* translators: the number of comments */
-				esc_html( _nx( '%1$s thought on &ldquo;%2$s&rdquo;', '%1$s thoughts on &ldquo;%2$s&rdquo;', get_comments_number(), 'comments title', '_s' ) ),
+				esc_html( _nx( '%1$s thought on &ldquo;%2$s&rdquo;', '%1$s thoughts on &ldquo;%2$s&rdquo;', get_comments_number(), 'comments title', 'wd_s' ) ),
 				number_format_i18n( get_comments_number() ), // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- XSS OK.
 				'<span>' . wp_kses_post( get_the_title() ) . '</span>' // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- XSS OK.
 			);
@@ -42,11 +43,11 @@
 		if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // Are there comments to navigate through?
 			?>
 			<nav id="comment-nav-above" class="navigation comment-navigation" role="navigation">
-				<h3 class="screen-reader-text"><?php esc_html_e( 'Comment navigation', '_s' ); ?></h3>
+				<h3 class="screen-reader-text"><?php esc_html_e( 'Comment navigation', 'wd_s' ); ?></h3>
 				<div class="nav-links">
 
-					<div class="nav-previous"><?php previous_comments_link( esc_html__( 'Older Comments', '_s' ) ); ?></div>
-					<div class="nav-next"><?php next_comments_link( esc_html__( 'Newer Comments', '_s' ) ); ?></div>
+					<div class="nav-previous"><?php previous_comments_link( esc_html__( 'Older Comments', 'wd_s' ) ); ?></div>
+					<div class="nav-next"><?php next_comments_link( esc_html__( 'Newer Comments', 'wd_s' ) ); ?></div>
 
 				</div><!-- .nav-links -->
 			</nav><!-- #comment-nav-above -->
@@ -68,11 +69,11 @@
 		if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // Are there comments to navigate through?
 			?>
 			<nav id="comment-nav-below" class="navigation comment-navigation" role="navigation">
-				<h2 class="screen-reader-text"><?php esc_html_e( 'Comment navigation', '_s' ); ?></h2>
+				<h2 class="screen-reader-text"><?php esc_html_e( 'Comment navigation', 'wd_s' ); ?></h2>
 				<div class="nav-links">
 
-					<div class="nav-previous"><?php previous_comments_link( esc_html__( 'Older Comments', '_s' ) ); ?></div>
-					<div class="nav-next"><?php next_comments_link( esc_html__( 'Newer Comments', '_s' ) ); ?></div>
+					<div class="nav-previous"><?php previous_comments_link( esc_html__( 'Older Comments', 'wd_s' ) ); ?></div>
+					<div class="nav-next"><?php next_comments_link( esc_html__( 'Newer Comments', 'wd_s' ) ); ?></div>
 
 				</div><!-- .nav-links -->
 			</nav><!-- #comment-nav-below -->
@@ -84,7 +85,7 @@
 	// If comments are closed and there are comments, let's leave a little note, shall we?
 	if ( ! comments_open() && get_comments_number() && post_type_supports( get_post_type(), 'comments' ) ) :
 		?>
-		<p class="no-comments"><?php esc_html_e( 'Comments are closed.', '_s' ); ?></p>
+		<p class="no-comments"><?php esc_html_e( 'Comments are closed.', 'wd_s' ); ?></p>
 	<?php endif; ?>
 
 	<?php

composer.json

@@ -30,6 +30,6 @@
 	"scripts": {
 		"format": "phpcbf --report=summary,source",
 		"lint": "phpcs --report=summary,source",
-		"pot": "wp i18n make-pot . build/languages/_s.pot --exclude=node_modules,vendor,build --allow-root"
+		"pot": "wp i18n make-pot . build/languages/wd_s.pot --exclude=node_modules,vendor,build --allow-root"
 	}
 }

footer.php

@@ -6,14 +6,18 @@
  *
  * @link https://developer.wordpress.org/themes/basics/template-files/#template-partials
  *
- * @package _s
+ * @package wd_s
  */
 
+use function WebDevStudios\wd_s\print_copyright_text;
+use function WebDevStudios\wd_s\print_social_network_links;
+use function WebDevStudios\wd_s\print_mobile_menu;
+
 ?>
 
 	<footer class="site-footer">
 
-		<nav id="site-footer-navigation" class="footer-navigation navigation-menu" aria-label="<?php esc_attr_e( 'Footer Navigation', '_s' ); ?>">
+		<nav id="site-footer-navigation" class="footer-navigation navigation-menu" aria-label="<?php esc_attr_e( 'Footer Navigation', 'wd_s' ); ?>">
 			<?php
 			wp_nav_menu(
 				[
@@ -29,13 +33,13 @@
 		</nav><!-- #site-navigation-->
 
 		<div class="container site-info">
-			<?php _s_display_copyright_text(); ?>
-			<?php _s_display_social_network_links(); ?>
+			<?php print_copyright_text(); ?>
+			<?php print_social_network_links(); ?>
 		</div><!-- .site-info -->
 
 	</footer><!-- .site-footer container-->
 
-	<?php _s_display_mobile_menu(); ?>
+	<?php print_mobile_menu(); ?>
 	<?php wp_footer(); ?>
 
 </body>

functions.php

@@ -4,28 +4,40 @@
  *
  * @link https://developer.wordpress.org/themes/basics/theme-functions/
  *
- * @package _s
+ * @package wd_s
  */
 
+namespace WebDevStudios\wd_s;
+
 /**
  * Get all the include files for the theme.
  *
  * @author WebDevStudios
  */
-function _s_get_theme_include_files() {
-	return [
-		'inc/setup.php', // Theme set up. Should be included first.
-		'inc/compat.php', // Backwards Compatibility.
+function include_inc_files() {
+	$files = [
 		'inc/customizer/customizer.php', // Customizer additions.
-		'inc/extras.php', // Custom functions that act independently of the theme templates.
-		'inc/hooks.php', // Load custom filters and hooks.
-		'inc/security.php', // WordPress hardening.
-		'inc/scaffolding.php', // Scaffolding.
-		'inc/scripts.php', // Load styles and scripts.
-		'inc/template-tags.php', // Custom template tags for this theme.
+		'inc/functions/', // Custom functions that act independently of the theme templates.
+		'inc/hooks/', // Load custom filters and hooks.
+		'inc/post-types/', // Load custom post types.
+		'inc/scaffolding/', // Scaffolding.
+		'inc/setup/', // Theme setup.
+		'inc/shortcodes/', // Load shortcodes.
+		'inc/template-tags/', // Custom template tags for this theme.
 	];
-}
 
-foreach ( _s_get_theme_include_files() as $include ) {
-	require trailingslashit( get_template_directory() ) . $include;
+	foreach ( $files as $include ) {
+		$include = trailingslashit( get_template_directory() ) . $include;
+
+		// Allows inclusion of individual files or all .php files in a directory.
+		if ( is_dir( $include ) ) {
+			foreach ( glob( $include . '*.php' ) as $file ) {
+				require $file;
+			}
+		} else {
+			require $include;
+		}
+	}
 }
+
+include_inc_files();

header.php

@@ -6,7 +6,7 @@
  *
  * @link https://developer.wordpress.org/themes/basics/template-files/#template-partials
  *
- * @package _s
+ * @package wd_s
  */
 
 ?>
@@ -28,7 +28,7 @@
 
 	<?php wp_body_open(); ?>
 
-	<a class="skip-link screen-reader-text" href="#main"><?php esc_html_e( 'Skip to content', '_s' ); ?></a>
+	<a class="skip-link screen-reader-text" href="#main"><?php esc_html_e( 'Skip to content', 'wd_s' ); ?></a>
 
 	<header class="site-header">
 
@@ -46,21 +46,21 @@
 
 				<?php
 
-				$description = get_bloginfo( 'description', 'display' );
-				if ( $description || is_customize_preview() ) :
+				$wd_s_description = get_bloginfo( 'description', 'display' );
+				if ( $wd_s_description || is_customize_preview() ) :
 					?>
-					<p class="site-description"><?php echo esc_html( $description ); ?></p>
+					<p class="site-description"><?php echo esc_html( $wd_s_description ); ?></p>
 				<?php endif; ?>
 
 			</div><!-- .site-branding -->
 
 			<?php if ( has_nav_menu( 'primary' ) || has_nav_menu( 'mobile' ) ) : ?>
-				<button type="button" class="off-canvas-open" aria-expanded="false" aria-label="<?php esc_attr_e( 'Open Menu', '_s' ); ?>"></button>
+				<button type="button" class="off-canvas-open" aria-expanded="false" aria-label="<?php esc_attr_e( 'Open Menu', 'wd_s' ); ?>"></button>
 			<?php endif; ?>
 
 		</div><!-- .container -->
 
-		<nav id="site-navigation" class="main-navigation navigation-menu" aria-label="<?php esc_attr_e( 'Main Navigation', '_s' ); ?>">
+		<nav id="site-navigation" class="main-navigation navigation-menu" aria-label="<?php esc_attr_e( 'Main Navigation', 'wd_s' ); ?>">
 			<?php
 			wp_nav_menu(
 				[

inc/README.md

@@ -0,0 +1,27 @@
+# Included `PHP` Files
+
+Use the `/inc` directory to declare any theme functionality. All files in this directory are imported inside of `functions.php`. 
+
+## Directories
+
+The `/inc` directory is organized into sub-directories based on the functionality/purpose of the code. These directories can be modified as needed, but the following structure is recommended:
+
+```text
+inc/
+└─── customizer/    (functions relating to the theme customizer)
+└─── functions/     (general functions that don't fit into any other directory)
+└─── hooks/         (theme hooks)
+└─── post-types/    (theme post type registrations & functions)
+└─── scaffolding/   (theme scaffolding functions)
+└─── setup/         (functions relating to the theme setup)
+└─── shortcodes/    (shortcode registrations)
+└─── template-tags/ (functions that render markup for use in theme templates)
+└─── README.md
+```
+
+## Filenames
+
+As a general rule, each `.php` file should contain a single function/action which should match the name of the file (replacing underscores with hyphens in the filename).
+
+For example, `function demo_function() {...}` would be declared in a file named `demo-function.php` and stored inside an appropriate `/inc` sub-directory.
+