php-theme-gen

v1.2.0

Published

6 months ago

A robust starter template for modern Node.js development, pre-configured with Jest for testing, ESLint for linting, and Prettier for code formatting.

0High
0Medium
0Low

shytiger

javascript starter node wordpress theme generator cli html-to-php scaffolding development php

WordPress Theme PHP Files Generator

A command-line interface (CLI) that streamlines WordPress theme development. It generates a complete WordPress theme structure (including header.php, footer.php, index.php, style.css, and functions.php) from a single HTML file, using  comment tags for content separation. It also provides a command to quickly scaffold new HTML templates.

📚 Table of Contents

WordPress Theme PHP Files Generator

✨ Key Features

WordPress Theme Generation: Quickly generate a full WordPress theme (including header.php, footer.php, index.php, and style.css) from a single HTML file.
HTML-to-PHP Conversion: Intelligently extracts content based on  and  HTML comment tags to create corresponding PHP template files.
Customizable Theme Metadata: Easily define theme name, author, description, and other details via CLI options, which are automatically included in style.css and PHP file headers.
HTML Template Scaffolding: Generate new HTML template files pre-configured with wp:file tags, accelerating new page development.
Comprehensive Testing Suite: Pre-configured with Jest for unit and integration testing. Includes coverage reporting out-of-the-box to ensure code quality.
Automated Code Quality: A strict, pre-configured setup using ESLint and Prettier to catch errors, enforce best practices, and maintain a consistent code style across all files (.js, .md, .json).
Enforced Documentation Standards: Integrated eslint-plugin-jsdoc to require JSDoc comments for all functions, improving code clarity and long-term maintainability.
Living Documentation: Custom automation scripts (npm run docs:all) that keep your README.md perpetually up-to-date by generating the project structure, a table of contents, and a list of available scripts. This eliminates documentation drift.
Automated Release Workflow: Integrated release-please to automate version bumping, CHANGELOG.md generation, and GitHub releases based on the Conventional Commits specification.
One-Command Pre-Commit Preparation: A single npm run ready command that formats, lints, and updates all documentation, guaranteeing every commit is clean, consistent, and professional. This command is designed to be run before every commit.
Robust Project Defaults: Thoughtfully pre-configured with .gitignore, .prettierignore, and a ready-to-use Continuous Integration (CI) workflow for GitHub Actions.
Automated Dependency Updates: Dependabot integration to keep your dependencies up-to-date and secure.

🚀 Getting Started

Prerequisites

Node.js version 18.0.0 or higher

Installation

Install the package globally (recommended):
```
npm install -g php-theme-gen
```
The phpgen app is available globally. In any folder on your computer, check it runs:
```
phpgen -V
```

Execute the package directly, using the npx command:

npx php-theme-gen [options] [command] [arguments]

# e.g. for help
# npx php-theme-gen -h

# e.g. to build theme from index.html
# npx php-theme-gen build demo/index.html --output demo/mytheme

Quick demo

Create demo/index.html with the following content:

<!-- wp:file name="header" -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Elegant Page with Tailwind CSS</title>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body class="bg-gray-100 text-gray-800 font-sans">
    <header class="bg-white shadow-md"></header>
    <!-- /wp:file -->

    <main class="container mx-auto px-6 py-12">
      <!-- Hero Section -->
      <section class="text-center mb-16">
        <h1 class="text-5xl font-extrabold text-gray-900 mb-4">
          Build Your Elegant Website
        </h1>
        <p class="text-lg text-gray-600 mb-8">
          A beautiful and responsive starting point for your next project.
        </p>
        <a
          href="#"
          class="bg-blue-600 text-white font-bold py-3 px-8 rounded-full hover:bg-blue-700 transition duration-300"
          >Get Started</a
        >
      </section>
    </main>

    <!-- wp:file name="footer" -->
    <footer class="bg-gray-800 text-white">
      <div class="container mx-auto px-6 py-12"></div>
      <div class="bg-gray-900 py-4">
        <div class="container mx-auto px-6 text-center text-gray-500">
          &copy; 2025 MyLogo. All Rights Reserved.
        </div>
      </div>
    </footer>
  </body>
</html>
<!-- /wp:file -->

The file contains HTML code and <~-- wp-file ... --> and  pair to designate the php filename and the content for that file.

Invoke phphen:

phpgen build demo/index.html --output demo/mytheme

It generates the following files in demo/mytheme:

header.php
footer.php
index.php
style.css

🚀 Usage

The phpgen CLI tool allows you to quickly generate a WordPress theme structure from a single HTML file.

`build` Command

The build command is used to process your HTML file and generate the theme files.

node src/index.js build <sourceFile> [options]

Arguments:

<sourceFile>: The path to your source HTML file. This file should contain  and  HTML comments to delineate the header and footer sections.

Options:

-o, --output <dir>: The output directory for the generated theme files. Defaults to dist.
--themeName <name>: The name of your WordPress theme. This will be used in the theme's style.css and PHP file headers. Defaults to MyTheme.
--themeURI <uri>: The URI of your theme.
--author <name>: The author of the theme.
--authorURI <uri>: The author's URI.
--description <text>: A brief description of your theme.
--tags <tags>: Comma-separated tags for your theme (e.g., blog, responsive).

Example:

To generate a theme from demo/index.html into the demo/mytheme directory with a custom theme name:

phpgen build demo/index.html --output demo/mytheme --themeName "My Elegant Theme" --author "Your Name" --description "An elegant WordPress theme."

This command will create the following files in demo/mytheme:

header.php
footer.php
index.php (or the basename of your source file, e.g., demo.php)
style.css

`new` Command

The new command generates a new HTML template file with basic WordPress theme tags. This is useful for quickly starting a new theme development.

phpgen new <templateName> [options]

Arguments:

<templateName>: The name of the HTML template file to create (e.g., my-page). The tool will create <templateName>.html.

Options:

-o, --output <dir>: The output directory for the new template file. Defaults to the current directory (.).

Example:

To create a new HTML template named about-us.html in the templates directory:

phpgen new about-us --output templates

🚀 Available Scripts

This template includes a set of scripts designed to streamline development, enforce quality, and automate documentation.

Automated Documentation

npm run docs:all: A convenience script that updates all documentation sections: table of contents, available scripts, and project structure.
npm run docs:scripts: Updates the "Available Scripts" section in README.md with this script.
npm run docs:structure: Updates the project structure tree in README.md.
npm run toc: Generates a Table of Contents in README.md using doctoc.

Code Quality & Formatting

npm run check: A convenience script that runs the linter.
npm run fix: A convenience script that formats code and then fixes lint issues.
npm run format: Formats all JavaScript, Markdown, and JSON files with Prettier.
npm run lint: Lints all JavaScript and Markdown files using ESLint.
npm run lint:fix: Automatically fixes linting issues in all JavaScript and Markdown files.

Core Development

npm run start: Runs the application using node src/index.js.
npm run test: Runs all tests with Jest and generates a coverage report.
npm run test:watch: Runs Jest in watch mode, re-running tests on file changes.

The "One-Click" Pre-Commit Workflow

npm run ready: A convenience script to run before committing: updates all documentation and then formats and fixes all files.

A Focus on Quality and Productivity

This starter template is more than just a collection of files; it's a workflow designed to maximize developer productivity and enforce high-quality standards from day one. The core philosophy is to automate the tedious and error-prone tasks so you can focus on what matters: building great software.

The Cost of Stale Documentation

In many projects, the README.md quickly becomes outdated. Manually updating the project structure or list of scripts is an easily forgotten chore.

php-theme-gen solves this problem with its custom documentation scripts:

scripts/update-readme-structure.js: Saves you from manually drawing out file trees. What might take 5-10 minutes of careful, manual work (and is often forgotten) is now an instant, accurate, and repeatable command.
scripts/update-readme-scripts.js: Ensures that your project's capabilities are always documented. It reads directly from package.json, so the documentation can't lie. It even reminds you to describe your scripts, promoting good habits.

The Power of Workflow Scripts

Chaining commands together is a simple but powerful concept. The fix, docs:all, and ready scripts are designed to create a seamless development experience.

Instead of remembering to run prettier then eslint --fix, you just run npm run fix.
Instead of running three separate documentation commands, you just run npm run docs:all.
And most importantly, before you commit, you run npm run ready. This single command is your pre-flight check. It guarantees that every commit you push is not only functional but also perfectly formatted, linted, and documented. This discipline saves countless hours in code review and prevents messy commit histories.

By embracing this automation, php-theme-gen helps you build better software, faster.

📦 Release & Versioning

This project uses release-please to automate releases, versioning, and changelog generation. This ensures a consistent and hands-off release process, relying on the Conventional Commits specification.

How it Works

Conventional Commits: All changes merged into the main branch should follow the Conventional Commits specification (e.g., feat: add new feature, fix: resolve bug).
Release Pull Request: release-please runs as a GitHub Action and monitors the main branch for new Conventional Commits. When it detects changes that warrant a new release (e.g., a feat commit for a minor version, a fix commit for a patch version), it automatically creates a "Release PR" with a title like chore(release): 1.2.3.
Review and Merge: This Release PR contains:
- An updated CHANGELOG.md with all changes since the last release.
- A bumped version number in package.json.
- Proposed release notes. Review this PR, and once satisfied, merge it into main.
Automated GitHub Release & Publish: Merging the Release PR triggers two final, sequential actions:
- The release-please action creates a formal GitHub Release and a corresponding Git tag (e.g., v1.1.0).
- The creation of this release then triggers the publish.yml workflow, which automatically publishes the package to the npm registry.

Creating a New Release

To create subsequent releases, simply merge changes into the main branch using Conventional Commits. release-please will handle the rest by creating a Release PR. Once that PR is merged, the new version will be released automatically.

Your First Release

To bootstrap the process and create your very first release:

Ensure your package.json version is at a sensible starting point (e.g., 1.0.0).
Make at least one commit to the main branch that follows the Conventional Commits specification. A good first commit would be: feat: Initial release.
Push your commit(s) to main. The release-please action will run and create your first Release PR.
Review and merge this PR. This will trigger the creation of your v1.0.0 GitHub Release and publish the package to npm.

For more details, refer to the release-please documentation.

📁 Project Structure

.
├── .github/           # GitHub Actions workflows
│   └── workflows/
│       ├── ci.yml             # Continuous Integration (CI) workflow
│       ├── publish.yml
│       └── release-please.yml
├── .qodo/
├── demo/
│   ├── mytheme/
│   │   ├── footer.php
│   │   ├── header.php
│   │   ├── index.php
│   │   └── style.css
│   └── index.html
├── src/               # Source code
│   ├── commands/
│   │   ├── build.js
│   │   └── new.js
│   ├── utils/
│   │   ├── createThemeFile.js
│   │   └── loadCommands.js
│   ├── cli.js
│   ├── index.js   # Main application entry point
│   └── program.js
├── tests/
│   ├── utils/
│   │   └── createThemeFile.test.js
│   └── index.test.js
├── .eslintignore      # Files/folders for ESLint to ignore
├── .eslintrc.json     # ESLint configuration
├── .gitignore         # Files/folders for Git to ignore
├── .npmrc
├── .prettierignore    # Files/folders for Prettier to ignore
├── .prettierrc.json   # Prettier configuration
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md # Community standards
├── CONTRIBUTING.md    # Guidelines for contributors
├── jest.config.mjs
├── LICENSE            # Project license
├── package.json       # Project metadata and dependencies
└── README.md          # This file

✍️ Linting for Documentation

This project uses the eslint-plugin-jsdoc package to enforce that all functions, classes, and methods are properly documented using JSDoc comments. This helps maintain a high level of code quality and makes the codebase easier for new and existing developers to understand.

How to Check for Missing Documentation

You can check the entire project for missing or incomplete docblocks by running the standard linting command:

npm run lint

ESLint will scan your JavaScript files and report any undocumented code as a warning.

Example

Consider the following function in your code without any documentation:

function calculateArea(width, height) {
  return width * height;
}

When you run npm run lint, ESLint will produce a warning similar to this:

/path/to/your/project/src/your-file.js
  1:1  warning  Missing JSDoc for function 'calculateArea'  jsdoc/require-jsdoc

To fix this, you would add a JSDoc block that describes the function, its parameters, and what it returns. Most modern code editors (like VS Code) can help by generating a skeleton for you if you type /** and press Enter above the function.

Corrected Code:

/**
 * Calculates the area of a rectangle.
 * @param {number} width The width of the rectangle.
 * @param {number} height The height of the rectangle.
 * @returns {number} The calculated area.
 */
function calculateArea(width, height) {
  return width * height;
}

After adding the docblock, running npm run lint again will no longer show the warning for this function.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines to get started.

🗺️ Roadmap

This project is actively maintained, and we have a clear vision for its future. Here are some of the features and improvements we are planning:

TypeScript Support: Add a separate branch or configuration for a TypeScript version of this template.
Monorepo Example: Provide guidance and an example setup for using this template within a monorepo structure.
Containerization: Include a Dockerfile and docker-compose.yml for easy container-based development.
Additional CI/CD Examples: Add examples for other CI/CD providers like CircleCI or GitLab CI.

If you have ideas for other features, please open an issue to discuss them!

⚖️ Code of Conduct

To ensure a welcoming and inclusive community, this project adheres to a Code of Conduct. Please read it to understand the standards of behavior we expect from all participants.

🙏 Acknowledgements

This project was built upon the shoulders of giants. We'd like to thank the creators and maintainers of these amazing open-source tools and specifications that make this template possible:

👨‍💻 About the Author

This template was created and is maintained by Ion Gireada.

GitHub: @ioncakephper
Website: Feel free to add your personal website or blog here.
LinkedIn: Connect with me on LinkedIn!

📄 License

This project is licensed under the MIT License.