README

📦  View on Packagist
📃  Read the Docs

About

The purpose of this package is to enable developers to use the familiar model-view-controller pattern in the creation of WordPress themes. This is accomplished by keeping HTML and PHP code as seperated as possible and adding convenient methods to organize data before it's sent to the view controllers. Querying for posts, rendering menus, handling taxonomies and all the other essential parts of developing a WordPress theme are now easier than ever with the RAD Theme Engine.

Quick Start

Inside of your site's wp-content/themes folder, run the following command to create a new Rad Theme Engine project.

composer create-project open-function-computers-llc/wp-theme <theme-name>

Next, enter your new theme's folder and run npm install to get dependencies.

cd <theme-name>
npm install

And that's it! Read about advanced installations and asset bundling on the docs.

Companion Fields

Themes define admin edit fields in yml files next to their templates (e.g. tpl-flexible.yml, single-<post-type>.yml). Flexible fields render a modal slice picker, and repeaters render as sortable tables. Beyond the standard field keys, layout definitions support:

# tpl-flexible.yml
fields:
  content:
    type: flexible
    layouts:
      Hero:
        title: Hero
        description: Full-width headline with a background image and one button.
        thumbnail: hero        # assets/hero.png
        fields:
          headline: { type: text, required: true }

• description: — shown under the layout name in the slice picker modal.
• thumbnail: — 16:9 preview image (1280×720 recommended) in the picker. A bare filename resolves inside the theme's assets/ directory; a value containing a slash is relative to the theme root (so a dedicated folder is explicit: assets/thumbnails/hero). The extension may be omitted and is resolved in this order: png, jpg, jpeg, webp, svg, gif.

Repeaters

Repeater rows are added with a plain "Add Row" button. Set the label explicitly in the yml — there is no automatic singularisation of the field label:

# tpl-flexible.yml
fields:
  features:
    type: repeater
    label: Features
    add button text: Add Feature

Sharing layouts with imports:

Repeated slice definitions can live once in a shared file (e.g. slices/base.yml with a top-level layouts: map) and be pulled into any companion yml. imports: is only valid at the top of the file — never inside a field definition — and when it's present a flexible field needs no layouts (or even a definition body) below it unless it adds or overrides layouts of its own:

# single-service-area.yml
imports: slices/base.yml      # or a list of paths
fields:
  content: flexible           # all layouts come from the import
  other:
    type: flexible
    layouts:
      Intro: { ... }          # local layouts win over imported ones of the same name

Imported layouts load first; a local layout with the same key replaces the imported one in place. Paths are relative to the theme root (imports outside the theme are rejected), imports may nest, cycles are detected, and resolution errors are shown inline on the field instead of failing silently.

Collapsed flexible slices stay collapsed: collapse state is stored per post + field + block in the browser's localStorage and restored on the next edit.

Local Development & Testing

This section is for contributors who want to work on rad-theme-engine itself with a full TDD setup.

Prerequisites

• PHP >= 8.1
• Composer
• MariaDB or MySQL running locally
• WP-CLI (wp)
• A local WordPress install (see below)

1. Clone the repos

Pick a working directory (e.g. ~/programming/php/ofco) and clone both repos into it:

git clone https://github.com/open-function-computers-llc/rad-theme-engine.git
git clone https://github.com/open-function-computers-llc/wp-theme.git

2. Set up a local WordPress install

mkdir wordpress && cd wordpress
wp core download
wp config create --dbname=rad_tdd --dbuser=root --dbpass=YOUR_PASSWORD --dbhost=localhost
wp core install \
  --url=localhost:8080 \
  --title="RAD TDD" \
  --admin_user=admin \
  --admin_password=password \
  --admin_email=dev@localhost.com

Start the built-in PHP server to browse the site:

php -S localhost:8080

3. Create a dev theme with a symlinked package

From inside wp-content/themes, scaffold a new theme:

cd wordpress/wp-content/themes
composer create-project open-function-computers-llc/wp-theme dev-theme

Then update dev-theme/composer.json to add a path repository so Composer symlinks your local clone instead of downloading from Packagist:

{
    "name": "open-function-computers-llc/wp-theme",
    "require": {
        "open-function-computers-llc/rad-theme-engine": "*"
    },
    "repositories": [
        {
            "type": "path",
            "url": "/path/to/your/rad-theme-engine",
            "options": {
                "symlink": true
            }
        }
    ],
    "autoload": {
        "psr-4": {
            "Helpers\\": "helpers/"
        }
    },
    "minimum-stability": "dev",
    "prefer-stable": false
}

Run composer update and verify the symlink:

ls -la vendor/open-function-computers-llc/
# rad-theme-engine -> /path/to/your/rad-theme-engine

Activate the theme:

cd /path/to/wordpress
wp theme activate dev-theme

Any changes you make in rad-theme-engine/src/ are now live immediately in the WordPress install — no reinstall required.

4. Set up the WordPress test suite

Clone wordpress-develop somewhere permanent on your machine:

git clone --depth=1 https://github.com/WordPress/wordpress-develop.git /path/to/wordpress-develop

Create a dedicated test database:

mysql -u root -p -e "CREATE DATABASE rad_tdd_tests;"

Copy and fill in the test config:

cp /path/to/wordpress-develop/wp-tests-config-sample.php \
   /path/to/wordpress-develop/wp-tests-config.php

Edit wp-tests-config.php with your database credentials and point ABSPATH at your WordPress install:

define( 'DB_NAME', 'rad_tdd_tests' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'your_password' );
define( 'DB_HOST', 'localhost' );

define( 'ABSPATH', '/path/to/wordpress/' );

5. Configure the test environment

Inside rad-theme-engine, copy .env.example to .env and fill in your local paths:

cp .env.example .env

WP_TESTS_DIR=/path/to/wordpress-develop
WP_TESTS_CONFIG=/path/to/wordpress-develop/wp-tests-config.php

This file is gitignored — it never gets committed.

6. Install dev dependencies and run the suite

cd rad-theme-engine
composer install
make test

You should see WordPress boot and all tests pass:

Installing...
Running as single site...
PHPUnit 9.6.23 by Sebastian Bergmann and contributors.

.....                                               5 / 5 (100%)

OK (5 tests, 13 assertions)

Available make commands

Install entr on Debian/Ubuntu with sudo apt install entr, or on macOS with brew install entr.

Writing tests

Tests live in the tests/ directory. Integration tests that need WordPress extend WP_UnitTestCase. The Site class is a singleton, so each test class that instantiates it must reset the instance in tearDown:

<?php

namespace ofc\tests;

use ofc\Site;
use WP_UnitTestCase;

class MyFeatureTest extends WP_UnitTestCase
{
    protected function tearDown(): void
    {
        parent::tearDown();
        $reflection = new \ReflectionClass(Site::class);
        $instance = $reflection->getProperty('instance');
        $instance->setAccessible(true);
        $instance->setValue(null, null);
    }

    /** @test */
    public function myFeatureWorkAsExpected()
    {
        Site::getInstance([
            "handlebars" => false,
            // your config here
        ]);

        // your assertions here
    }
}

Pure unit tests that don't need WordPress (like testing utility methods) can extend PHPUnit\Framework\TestCase directly and will run faster.

Example Projects

• Shirt Store – Demonstrates custom post types, taxonomies, handlebars, and more.

Authors

• Kurtis Holsapple – @lapubell
• Escher Wright-Dykhouse – @escherwd
• Gabriel Johnson - @gabriel-johnson

License

Licensed under the MIT license, see LICENSE