Merge pull request #5 from lightspeedwp/audit/updates

Standardize PHP naming conventions and improve theme generator

Author: krugazul

.github/README.md

@@ -1,18 +1,96 @@
 ---
-title: GitHub Configuration
-description: GitHub-specific configuration and workflow files
-category: Project
-type: Index
+title: Block Theme Scaffold
+description: Generate a block theme for WordPress
+category: Tool
+type: Generate
 audience: Developers
-date: 2025-12-01
+date: 2026-01-10
 ---
 
-# GitHub Configuration
+## Getting Started
+
+Advanced documentation on the theme generation is provided [here](../docs/GENERATE_THEME.md)
+
+### Visual Studio Code
+
+This tool is meant to be used on its own, and not inside a WordPress install. We suggest creating a "tools" folder at the root of your hosting applications folder (where all the sites are housed).
+You can then clone your it to your tools folder, and re-use it everytime you need a new theme.
+
+### Prerequisites
+Make sure you have the following installed:
+
+- Node.js (check .nvmrc for the required version)
+- Composer (for PHP dependencies)
+- A WordPress environment with a database.
+
+### Installation Steps
+
+#### 1. Clone the Repository
+```bash
+git clone https://github.com/lightspeedwp/block-theme-scaffold.git
+cd block-theme-scaffold
+```
+
+#### 2. Install Dependencies
+```bash
+# Install Node.js dependencies
+npm install
+
+# Install PHP/Composer dependencies
+composer install
+```
+
+#### 3. Generate your theme
+
+**Interactive prompts (easiest)**
+
+Add the folder to the chat to your IDE, and select the "Generate Theme Agent" from the agent dropdown, 
+
+Then simply ask the agent to generate a theme, it will prompt you for the basic placeholder replacements.
+
+```bash
+Please generate a theme for me
+```
+
+If you cannot see it in the dropdown, add the js file to the chat as well.
+Agent Location: `scripts/agents/generate-theme.agent.js`
+
+```bash
+Please use the attached agent and folder, and generate a theme for me.
+```
 
-This directory contains GitHub-specific configuration files for the {{theme_name}} theme.
 
-## Contents
 
+**CLI Mode**
+```bash
+node scripts/generate-theme.js --slug my-theme --name "My Theme" --author  "Your Name" ...
+```
+
+**JSON Mode**
+```bash
+node scripts/generate-theme.js --config theme-config.json
+```
+
+#### 4. Copy the theme to your site.
+Copy the `output-theme` directory that will be generated in your repository and copy and paste that in your `themes` directory. 
+
+Make sure to rename it to the same value as your Theme Slug.
+
+### Available Scripts
+- `npm run build` - Build for development
+- `npm run watch` - Watch for changes during development
+- `npm run lint`  - Run linters
+- `npm test`      - Run tests
+
+
+## Importing Design Tokens
+
+🚧 **Coming Soon** 🚧
+
+## GitHub Configuration
+This directory contains GitHub-specific configuration files for the {{theme_name}} theme.
+
+### Contents
 - **agents/** - AI agent configurations for automated development tasks
 - **instructions/** - Development instructions and guidelines for AI tools
 - **projects/** - Active Copilot projects and in-progress work
@@ -23,31 +101,14 @@ This directory contains GitHub-specific configuration files for the {{theme_name
 - `copilot-tasks.md` - Copilot task definitions and specifications
 - `custom-instructions.md` - Custom AI instructions for Copilot
 
-## Documentation
-
+### Documentation
 Permanent user-facing documentation is stored in the [docs/](../docs/) folder. See [docs/FILE_ORGANIZATION.md](../docs/FILE_ORGANIZATION.md) for the complete file organization guide.
 
-## Workflows
+### Workflows
 
 | Workflow | Description |
 |----------|-------------|
 | `ci-cd.yml` | Main CI/CD pipeline (lint, test, security audit, E2E) |
 | `code-quality.yml` | Code coverage, quality gates, bundle analysis |
 | `deploy-wporg.yml` | Automated WordPress.org theme directory deployment |
 | `release.yml` | Version bumping, changelog generation, releases |
-
-## Purpose
-
-These files enable:
-
-- Automated build and test workflows
-- Code coverage tracking with Codecov
-- Quality gates for PRs
-- AI-assisted development with context-specific instructions
-- Consistent code review and quality checks
-- Automated release and deployment processes
-- WordPress.org theme directory deployment
-
-## Usage
-
-These files are automatically used by GitHub Actions and compatible AI development tools. They are excluded from theme distribution packages via `.distignore`.

.github/schemas/theme-config.schema.json

@@ -459,6 +459,13 @@
 					"minimum": 20,
 					"maximum": 200
 				},
+				"archive_excerpt_length": {
+					"type": "integer",
+					"description": "Number of words in archive/listing excerpts",
+					"default": 40,
+					"minimum": 20,
+					"maximum": 200
+				},
 				"excerpt_more": {
 					"type": "string",
 					"description": "Excerpt 'more' text",

CHANGELOG.md

@@ -16,8 +16,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **PHP Naming Convention Standardization**: All theme functions and hooks now use `{{theme_slug|phpCase}}` placeholder filter for consistent snake_case naming
+  - Updated `functions.php` - theme setup, asset enqueue, and utility functions
+  - Updated `inc/block-patterns.php` - pattern registration functions
+  - Updated `inc/block-styles.php` - block style registration functions  
+  - Updated `inc/template-functions.php` - template helper functions
+  - All function names now follow WordPress coding standards (e.g., `my_theme_setup()` instead of `my-theme_setup()`)
+
+- **Asset Handle Unification**: Standardized all asset handles to use `{{theme_slug}}` prefix
+  - Style handles: `{{theme_slug}}-style`, `{{theme_slug}}-editor-style`
+  - Script handles: `{{theme_slug}}-script`, `{{theme_slug}}-editor-script`
+  - Image size names: `{{theme_slug}}-featured`, `{{theme_slug}}-thumbnail`, `{{theme_slug}}-gallery`
+
+- **Theme Generator Improvements**: Enhanced placeholder replacement system in `scripts/generate-theme.js`
+  - Added support for multiple filter types: `upper`, `snakeCase`, `phpCase`, `pascalCase`, `camelCase`
+  - Consolidated placeholder replacement into single-pass regex for better performance
+  - Improved error handling and validation for theme slug and author URI
+  - Better error messages for invalid inputs
+  - Protocol validation for author URIs (must start with http:// or https://)
+
+- **theme.json Structure Updates**: Improved typography configuration
+  - Font families now use proper object structure with `slug`, `fontFamily`, and `name` properties
+  - Changed from array of strings to array of objects for better WordPress compatibility
+  - Removed redundant top-level `color` setting
+
+- **Test Suite Modernization**: Updated all PHPUnit tests to reflect new naming conventions
+  - Updated test discovery to use `Test_` prefix in `phpunit.xml`
+  - Fixed block style registry method calls to use `get_registered_styles_for_block()`
+  - Updated theme.json version assertion from 2 to 3
+  - Aligned test structure with WordPress coding standards
+
 ### Added
 
+- **New Placeholder Variables**:
+  - `{{logo_width}}` - Logo width dimension (default: 250)
+  - `{{logo_height}}` - Logo height dimension (default: 100)
+  - `{{archive_excerpt_length}}` - Excerpt length for archive/listing pages (default: 40)
+  - `{{content_width_num}}` - Numeric content width without units
+
+- **Schema Enhancements**: Added `archive_excerpt_length` configuration option
+  - Type: integer, default: 40, range: 20-200
+  - Controls excerpt length specifically for archive and listing pages
+
+- **Documentation Improvements**: Enhanced `.github/README.md`
+  - Clearer installation instructions
+  - Multiple theme generation methods (Interactive, CLI, JSON)
+  - Available scripts reference
+  - Prerequisites section
+  - Better structure and organization
+
+### Fixed
+
+- **Content Width Type Bug**: Fixed critical bug where `$GLOBALS['content_width']` was incorrectly set as string instead of integer
+  - Changed from `'{{content_width_px}}'` to `{{content_width_num}}`
+  - Now properly passes integer value to WordPress for embed/media width calculations
+  - Fixes PHPUnit test assertions for `assertIsInt($content_width)`
+
+- **Placeholder Type Consistency**: Improved type handling in theme generator
+  - Added string coercion for `content_width_num` calculation to prevent errors when config value is numeric
+  - Better handling of missing or invalid placeholder values
+
 - Automated mustache variable registry scan, update, and reporting:
   - Recursively scans all source, config, and documentation files for `{{mustache}}` variables.
   - Compares discovered variables to the canonical registry (`scripts/mustache-variables-registry.json`).

VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

functions.php

@@ -19,7 +19,7 @@
 /**
  * Theme setup.
  */
-function {{theme_slug}}_setup() {
+function {{theme_slug|snakeCase}}_setup() {
 	// Make theme available for translation.
 	load_theme_textdomain( '{{theme_slug}}', get_template_directory() . '/languages' );
 
@@ -37,20 +37,20 @@ function {{theme_slug}}_setup() {
 	add_editor_style( 'build/css/editor-style.css' );
 
 	// Set content width.
-	$GLOBALS['content_width'] = apply_filters( '{{theme_slug}}_content_width', {{content_width_px}} );
+	$GLOBALS['content_width'] = apply_filters( '{{theme_slug}}_content_width', {{content_width_num}} );
 }
-add_action( 'after_setup_theme', '{{theme_slug}}_setup' );
+add_action( 'after_setup_theme', '{{theme_slug|snakeCase}}_setup' );
 
 /**
  * Enqueue theme assets.
  */
-function {{theme_slug}}_enqueue_assets() {
+function {{theme_slug|snakeCase}}_enqueue_assets() {
 	// Main stylesheet.
 	$asset_file = get_theme_file_path( 'build/css/style.asset.php' );
 	if ( file_exists( $asset_file ) ) {
 		$asset = include $asset_file;
 		       wp_enqueue_style(
-				   '{{asset_slug}}-style',
+				   '{{theme_slug}}-style',
 			       get_theme_file_uri( 'build/css/style.css' ),
 			       $asset['dependencies'] ?? array(),
 				   $asset['version'] ?? {{theme_slug|upper}}_VERSION
@@ -62,7 +62,7 @@ function {{theme_slug}}_enqueue_assets() {
 	if ( file_exists( $js_asset_file ) ) {
 		$js_asset = include $js_asset_file;
 		       wp_enqueue_script(
-				   '{{asset_slug}}-script',
+				   '{{theme_slug}}-script',
 			       get_theme_file_uri( 'build/js/theme.js' ),
 			       $js_asset['dependencies'] ?? array(),
 				   $js_asset['version'] ?? {{theme_slug|upper}}_VERSION,
@@ -71,23 +71,23 @@ function {{theme_slug}}_enqueue_assets() {
 
 		// Set script translations.
 		       wp_set_script_translations(
-				   '{{asset_slug}}-script',
+				   '{{theme_slug}}-script',
 				   '{{theme_slug}}',
 			       get_theme_file_path( 'languages' )
 		       );
 	}
 }
-add_action( 'wp_enqueue_scripts', '{{theme_slug}}_enqueue_assets' );
+add_action( 'wp_enqueue_scripts', '{{theme_slug|snakeCase}}_enqueue_assets' );
 
 /**
  * Enqueue editor assets.
  */
-function {{theme_slug}}_enqueue_editor_assets() {
+function {{theme_slug|snakeCase}}_enqueue_editor_assets() {
 	$editor_asset_file = get_theme_file_path( 'build/css/editor-style.asset.php' );
 	if ( file_exists( $editor_asset_file ) ) {
 		$editor_asset = include $editor_asset_file;
 		       wp_enqueue_style(
-				   '{{asset_slug}}-editor-style',
+				   '{{theme_slug}}-editor-style',
 			       get_theme_file_uri( 'build/css/editor-style.css' ),
 			       $editor_asset['dependencies'] ?? array(),
 				   $editor_asset['version'] ?? {{theme_slug|upper}}_VERSION
@@ -99,7 +99,7 @@ function {{theme_slug}}_enqueue_editor_assets() {
 	if ( file_exists( $editor_js_asset_file ) ) {
 		$editor_js_asset = include $editor_js_asset_file;
 		       wp_enqueue_script(
-				   '{{asset_slug}}-editor-script',
+				   '{{theme_slug}}-editor-script',
 			       get_theme_file_uri( 'build/js/editor.js' ),
 			       $editor_js_asset['dependencies'] ?? array(),
 				   $editor_js_asset['version'] ?? {{theme_slug|upper}}_VERSION,
@@ -108,32 +108,32 @@ function {{theme_slug}}_enqueue_editor_assets() {
 
 		// Set script translations for editor.
 		       wp_set_script_translations(
-				   '{{asset_slug}}-editor-script',
+				   '{{theme_slug}}-editor-script',
 				   '{{theme_slug}}',
 			       get_theme_file_path( 'languages' )
 		       );
 	}
 }
-add_action( 'enqueue_block_editor_assets', '{{theme_slug}}_enqueue_editor_assets' );
+add_action( 'enqueue_block_editor_assets', '{{theme_slug|snakeCase}}_enqueue_editor_assets' );
 
 /**
  * Register block pattern categories.
  */
-function {{theme_slug}}_register_pattern_categories() {
+function {{theme_slug|snakeCase}}_register_pattern_categories() {
 		       $categories = array(
-			       '{{pattern_slug}}-hero'    => array( 'label' => __( '{{theme_name}} Hero', '{{theme_slug}}' ) ),
-			       '{{pattern_slug}}-about'   => array( 'label' => __( '{{theme_name}} About', '{{theme_slug}}' ) ),
-			       '{{pattern_slug}}-contact' => array( 'label' => __( '{{theme_name}} Contact', '{{theme_slug}}' ) ),
-			       '{{pattern_slug}}-cta'     => array( 'label' => __( '{{theme_name}} Call to Action', '{{theme_slug}}' ) ),
-			       '{{pattern_slug}}-gallery' => array( 'label' => __( '{{theme_name}} Gallery', '{{theme_slug}}' ) ),
-			       '{{pattern_slug}}-team'    => array( 'label' => __( '{{theme_name}} Team', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-hero'    => array( 'label' => __( '{{theme_name}} Hero', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-about'   => array( 'label' => __( '{{theme_name}} About', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-contact' => array( 'label' => __( '{{theme_name}} Contact', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-cta'     => array( 'label' => __( '{{theme_name}} Call to Action', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-gallery' => array( 'label' => __( '{{theme_name}} Gallery', '{{theme_slug}}' ) ),
+			       '{{theme_slug}}-team'    => array( 'label' => __( '{{theme_name}} Team', '{{theme_slug}}' ) ),
 		       );
 
 	foreach ( $categories as $slug => $args ) {
 		register_block_pattern_category( $slug, $args );
 	}
 }
-add_action( 'init', '{{theme_slug}}_register_pattern_categories' );
+add_action( 'init', '{{theme_slug|snakeCase}}_register_pattern_categories' );
 
 /**
  * Load theme includes.
@@ -154,25 +154,25 @@ function {{theme_slug}}_register_pattern_categories() {
 /**
  * Add custom image sizes.
  */
-function {{theme_slug}}_add_image_sizes() {
-	add_image_size( '{{asset_slug}}-featured', {{featured_image_width}}, {{featured_image_height}}, true );
-	add_image_size( '{{asset_slug}}-thumbnail', {{thumbnail_width}}, {{thumbnail_height}}, true );
-	add_image_size( '{{asset_slug}}-gallery', {{gallery_image_width}}, {{gallery_image_height}}, true );
+function {{theme_slug|snakeCase}}_add_image_sizes() {
+	add_image_size( '{{theme_slug}}-featured', {{featured_image_width}}, {{featured_image_height}}, true );
+	add_image_size( '{{theme_slug}}-thumbnail', {{thumbnail_width}}, {{thumbnail_height}}, true );
+	add_image_size( '{{theme_slug}}-gallery', {{gallery_image_width}}, {{gallery_image_height}}, true );
 }
-add_action( 'after_setup_theme', '{{theme_slug}}_add_image_sizes' );
+add_action( 'after_setup_theme', '{{theme_slug|snakeCase}}_add_image_sizes' );
 
 /**
  * Modify excerpt length.
  */
-function {{theme_slug}}_excerpt_length( $length ) {
+function {{theme_slug|snakeCase}}_excerpt_length( $length ) {
 	return {{excerpt_length}};
 }
-add_filter( 'excerpt_length', '{{theme_slug}}_excerpt_length' );
+add_filter( 'excerpt_length', '{{theme_slug|snakeCase}}_excerpt_length' );
 
 /**
  * Modify excerpt more.
  */
-function {{theme_slug}}_excerpt_more( $more ) {
+function {{theme_slug|snakeCase}}_excerpt_more( $more ) {
 	return '{{excerpt_more}}';
 }
-add_filter( 'excerpt_more', '{{theme_slug}}_excerpt_more' );
+add_filter( 'excerpt_more', '{{theme_slug|snakeCase}}_excerpt_more' );