Pumpkin [Big Alpha Release]

Next generation WordPress Theme boilerplate concept

This software is provided "as is" without any warranties, express or implied. The project is currently in active development and may contain bugs or incomplete features. Part of readme is generated by AI and because of frequent updates might not be up to date.

Designed around component-based architecture and DRY principles for better code organization and reusability. Note that this approach may not follow traditional WordPress theme patterns. It's a collection of best practices for streamlined theme development and long term maintenance that has proved to work for me in every environment during 15 years of developing bespoke WordPress themes.

⚠️ Important: This theme requires ACF Pro (paid plugin). You must purchase your own ACF Pro license separately. This project is not affiliated with or endorsed by ACF in any way.

Feedback welcome, contributions are not accepted at this stage. More examples on how to use this boilerplate will be provided soon.

Key Concepts

1. ACF Flexible Field Sections System

Component-based page building using ACF flexible fields. Everything is built around one ACF Flexible Field called "Sections".

📖 Read Full Documentation

Quick Overview:

Central hub: One ACF Flexible Field containing all section layouts
Each section = self-contained component with PHP, SCSS, JS, and assets
Auto-loading: Section CSS/JS loads only when used
Reusable across any page/post type

2. Custom Template Loader

Folder-based template system with automatic discovery and hierarchical fallbacks.

📖 Read Full Documentation

Quick Overview:

Create a folder → template appears in WordPress admin
Template hierarchy: Template-specific → Post-type → Shared
Template parts support: Override header, footer, sidebar per template

3. Webpack Build System

Auto-discovery and bundling of template and section assets.

📖 Read Full Documentation

Quick Overview:

Per-template bundles: Each template gets its own CSS/JS
Per-section bundles: Each section gets its own CSS/JS
Async loading support for deferred assets
Hot Module Replacement for development

4. ACF Options Manager

Composer package for managing WordPress options pages using ACF and custom post type. Data is stored and retrieved from post_content field and does not use the wp_options table. Supports multiple instances and capability-based access control.

📖 Read Documentation

📖 Package Documentation

5. Global PHP Config

Hardcoded configuration for settings that don't need WordPress admin editing.

📖 Read Full Documentation

Quick Overview:

Version-controlled settings
Template hierarchy for overrides
Feature flags, API keys, defaults
Environment-specific configuration

6. Reusable Static Components

Code-based UI components with custom PHP class architecture.

📖 Read Full Documentation

Quick Overview:

Self-contained component folders
Class-based rendering
Multiple template variations
Perfect for logos, breadcrumbs, social icons

Requirements:

PHP 8.2+, WordPress 6.x
Node.js >= 22, npm
ACF Pro

Quick Start

Clone the Repository:

git clone https://github.com/code-soup/pumpking.git my-awesome-theme
cd my-awesome-theme

Configure ACF Pro License: Create an auth.json file in the theme root with your ACF Pro license credentials:

{
    "http-basic": {
        "connect.advancedcustomfields.com": {
            "username": "YOUR_ACF_LICENSE_KEY",
            "password": "YOUR_ACF_LICENSE_URL"
        }
    }
}

Note: Get your license credentials from your ACF Pro account page.

Environment Configuration (Optional): Create a .env file for environment-specific settings:

# Development settings
WP_DEV_URL=http://localhost # Where your WordPress theme is installed
WP_CONTENT_PATH=/wp-content/themes # Sepcify custom themes folder if different from default

Run the Setup Script: This script will ask for your theme's details and configure the boilerplate files for you.
```
npm run setup
```

Install Dependencies: Once the setup is complete, install the necessary PHP and Node.js dependencies.

# Install PHP dependencies (includes ACF Pro)
composer install

# Install Node.js dependencies
npm install

Run the Development Server: For live-reloading and automatic recompilation of assets during development.
```
npm run dev
```

Available Scripts

This boilerplate comes with a set of pre-configured scripts for development tasks.

PHP Scripts (via Composer)

composer lint: Lints all PHP files for syntax errors.
composer wpcs: Checks PHP files against the WordPress Coding Standards.
composer cbf: Automatically fixes many phpcs errors.

JavaScript/Asset Scripts (via npm)

npm run setup: Initial plugin setup
npm run dev: Starts the webpack dev server with Hot Module Replacement.
npm run build: Compiles and optimizes all assets for a production environment.
npm run build:dev: Compiles assets for development without optimization.
npm run lint: Runs both the script and style linters.
- npm run lint:scripts: Lints JavaScript files with ESLint.
- npm run lint:styles: Lints SCSS files with Stylelint.
npm run clean: Deletes the dist folder and the webpack cache.

Folder Structure

pumpkin/
├── 📁 dist/                          # Compiled assets (auto-generated)
│   ├── manifest.json                 # Webpack asset manifest
│   ├── scripts/                      # Compiled JavaScript bundles
│   └── styles/                       # Compiled CSS bundles
│
├── 📁 includes/                      # Core PHP functionality
│   ├── 📁 acf/                       # ACF integration classes
│   │   ├── class-sections.php        # Flexible content sections
│   │   ├── class-setup.php           # ACF configuration
│   │   └── json/                     # ACF field group exports
│   ├── 📁 core/                      # Core theme classes
│   │   ├── class-bootstrap.php       # Theme initialization
│   │   ├── class-component.php       # Component base class
│   │   ├── class-hooker.php          # WordPress hooks manager
│   │   └── class-page-config.php     # Page configuration handler
│   ├── 📁 plugin-mods/               # Third-party plugin modifications
│   ├── 📁 utils/                     # Utility classes and traits
│   │   ├── html-helpers.php          # HTML generation helpers
│   │   ├── trait-asset-loader.php    # Asset loading functionality
│   │   ├── trait-script-loader.php   # Script loading utilities
│   │   └── trait-template-utilities.php # Template helper functions
│   └── 📁 wp-mods/                   # WordPress core modifications
│       ├── class-script-loader.php   # Custom script loading system
│       ├── class-template-admin.php  # Template admin interface
│       ├── class-template-loader.php # Custom template loading system
│       └── class-theme-setup.php     # WordPress theme setup
│
├── 📁 lang/                          # Translation files
│   └── pumpkin.pot                   # Translation template
│
├── 📁 src/                           # Source assets (pre-compilation)
│   ├── 📁 config/                    # Build configuration
│   │   ├── config.user.js            # User-specific webpack config
│   │   ├── config.webpack.js         # Main webpack configuration
│   │   └── 📁 webpack/               # Webpack module configurations
│   │       ├── config.module.js      # Module rules
│   │       ├── config.optimization.js # Optimization settings
│   │       ├── config.plugins.js     # Webpack plugins
│   │       └── 📁 loaders/           # Asset loaders
│   ├── 📁 fonts/                     # Font files
│   ├── 📁 icons/                     # Icon assets
│   ├── 📁 images/                    # Global images
│   ├── 📁 scripts/                   # Global JavaScript
│   │   ├── admin.js                  # WordPress admin scripts
│   │   ├── main.js                   # Main frontend script
│   │   └── 📁 util/                  # JavaScript utilities
│   └── 📁 styles/                    # Global SCSS
│       ├── main.scss                 # Main stylesheet entry
│       ├── admin.scss                # Admin stylesheet
│       ├── 📁 abstracts/             # SCSS variables, mixins, functions
│       ├── 📁 components/            # Global component styles
│       ├── 📁 core/                  # Base/reset styles
│       ├── 📁 layouts/               # Layout-specific styles
│       └── 📁 sections/              # Section-specific styles
│
├── 📁 templates/                     # Template system
│   ├── 📁 post-type/                 # Post type specific templates
│   │   ├── 📁 page/                  # Page templates
│   │   │   ├── index.php             # Default page template
│   │   │   └── 📁 404/               # 404 page template
│   │   │       └── index.php         # 404 template file
│   │   └── 📁 post/                  # Post templates
│   ├── 📁 shared/                    # Shared template components
│   │   ├── 📁 components/            # Reusable static components
│   │   │   └── 📁 website-logo/      # Example component
│   │   │       ├── Component.php     # Component class
│   │   │       ├── 📁 assets/        # Component-specific assets
│   │   │       └── 📁 templates/     # Component templates
│   │   ├── 📁 parts/                 # Template parts (header, footer, etc.)
│   │   └── 📁 sections/              # ACF flexible content sections
│   └── 📁 taxonomy/                  # Taxonomy templates
│       └── index.php                 # Default taxonomy template
│
├── 📁 vendor/                        # Composer dependencies
│   ├── 📁 codesoup/
│   │   ├── acf-admin-categories/     # ACF admin organization
│   │   └── acf-options/              # ACF options manager
│   ├── 📁 wpengine/
│   │   └── advanced-custom-fields-pro/ # ACF Pro plugin
│   └── autoload.php                  # Composer autoloader
│
├── 📄 base.php                       # Theme base template
├── 📄 functions.php                  # WordPress functions file
├── 📄 index.php                      # WordPress index template
├── 📄 page-config.php                # Global page configuration
├── 📄 style.css                      # WordPress theme header
├── 📄 composer.json                  # PHP dependencies
├── 📄 package.json                   # Node.js dependencies
└── 📄 README.md                      # This file

Key Directory Explanations

`/templates/` - Template System

The heart of Pumpkin's component-based architecture:

post-type/{post-type}/{template-name}/ - Each template gets its own folder containing all related files (PHP, SCSS, JS, images)
shared/components/ - Reusable static components with their own PHP classes
shared/parts/ - Traditional WordPress template parts (header, footer, sidebar)
shared/sections/ - ACF Flexible Content sections for page building

`/includes/` - Core Functionality

PHP classes that power the theme's features:

core/ - Essential theme classes (Bootstrap, Component base, Page config)
acf/ - ACF integration for flexible content sections
wp-mods/ - WordPress core modifications (custom template loader, script loader)
utils/ - Helper functions and traits for common tasks

`/src/` - Source Assets

Pre-compiled assets and build configuration:

config/ - Webpack configuration split into logical modules
styles/ - Global SCSS following ITCSS methodology
scripts/ - Global JavaScript and utilities

`/dist/` - Compiled Assets

Auto-generated by Webpack containing optimized, production-ready assets. Each page template gets its own bundle based on its index.js/scss files.

Template Loading Hierarchy

Templates follow this loading order for maximum flexibility:

Page-specific: /templates/post-type/{post-type}/{template-name}/index.php
Post-type default: /templates/post-type/{post-type}/index.php
Shared fallback: /templates/shared/index.php

The same hierarchy applies to template parts (header.php, footer.php, etc.), allowing granular customization per template while maintaining DRY principles.

Documentation

For detailed information on each feature, see the documentation files in the /docs folder:

ACF Flexible Field Sections - Component-based page building system
Custom Template Loader - Folder-based template discovery and hierarchy
Webpack Build System - Asset bundling and optimization
ACF Options Manager - Theme options package
Global PHP Config - Hardcoded configuration system
Static Components - Reusable UI components

Hooker

The Hooker class is a centralized service for adding WordPress actions and filters. It is registered in the Dependency Injection container and can be accessed from any class that has access to the container, such as a service provider or a class instantiated by one.

The primary benefit of using this service is to have a consistent, injectable way to manage WordPress hooks, which is useful for organization and testing.

Basic Usage

Getting the Hooker Instance

// From Bootstrap
$hooker = \CodeSoup\Pumpkin\Core\Bootstrap::get_instance()->get_hooker();

Adding Actions and Filters

// Add a single action
$hooker->add_action( 'wp_footer', $this, 'render_footer' );

// Add a single filter
$hooker->add_filter( 'the_title', $this, 'modify_title', 10, 2 );

// Add multiple actions at once
$hooker->add_actions( [
    [ 'wp_enqueue_scripts', $this, 'enqueue_scripts' ],
    [ 'wp_footer', $this, 'render_footer', 20 ],
] );

// Add multiple filters at once
$hooker->add_filters( [
    [ 'the_content', $this, 'filter_content' ],
    [ 'the_title', $this ], // Method name matches hook name, can be omitted
    [ 'quick_edit_enabled_for_post_type', '__return_false' ], // Use WordPress built in global function
] );

Navigation Menu

Uh oh!

Repository files navigation

Pumpkin [Big Alpha Release]

Next generation WordPress Theme boilerplate concept

Key Concepts

1. ACF Flexible Field Sections System

2. Custom Template Loader

3. Webpack Build System

4. ACF Options Manager

5. Global PHP Config

6. Reusable Static Components

Requirements:

Quick Start

Available Scripts

PHP Scripts (via Composer)

JavaScript/Asset Scripts (via npm)

Folder Structure

Key Directory Explanations

`/templates/` - Template System

`/includes/` - Core Functionality

`/src/` - Source Assets

`/dist/` - Compiled Assets

Template Loading Hierarchy

Documentation

Hooker

Basic Usage

Getting the Hooker Instance

Adding Actions and Filters

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
includes		includes
lang		lang
src		src
templates		templates
.babelrc		.babelrc
.editorconfig		.editorconfig
.env.exmple		.env.exmple
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc		.prettierrc
.stylelintrc.js		.stylelintrc.js
LICENSE.md		LICENSE.md
README.md		README.md
base.php		base.php
composer.json		composer.json
functions.php		functions.php
index.php		index.php
package.json		package.json
page-config.php		page-config.php
screenshot.png		screenshot.png
style.css		style.css

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Pumpkin [Big Alpha Release]

Next generation WordPress Theme boilerplate concept

Key Concepts

1. ACF Flexible Field Sections System

2. Custom Template Loader

3. Webpack Build System

4. ACF Options Manager

5. Global PHP Config

6. Reusable Static Components

Requirements:

Quick Start

Available Scripts

PHP Scripts (via Composer)

JavaScript/Asset Scripts (via npm)

Folder Structure

Key Directory Explanations

/templates/ - Template System

/includes/ - Core Functionality

/src/ - Source Assets

/dist/ - Compiled Assets

Template Loading Hierarchy

Documentation

Hooker

Basic Usage

Getting the Hooker Instance

Adding Actions and Filters

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`/templates/` - Template System

`/includes/` - Core Functionality

`/src/` - Source Assets

`/dist/` - Compiled Assets