Flat (Vanilla) Structure

Running the Framework in a Flat (Vanilla) WordPress Structure

This guide explains how to configure and run the Framework using a flat, vanilla-style setup where WordPress files are located directly inside the public/ directory, similar to a standard installation.

What Is a Flat Structure?

In the flat (or vanilla) setup, your directory structure closely resembles a default installation. All core files (such as wp-admin/, wp-includes/, and index.php) are placed inside the public/ directory, while wp-config.php is moved one level up into the app/ directory.

Directory Structure

project-root/
├── app/
│   ├── wp-config.php          ← Framework bootstrap
│   └── vendor/                ← Composer dependencies
└── public/
    ├── wp-admin/
    ├── wp-includes/
    ├── wp-content/
    └── index.php

This differs from the default modular framework setup where WordPress core typically lives in public/wp/ and wp-config.php remains inside the public/ directory.

Required Configuration Changes

To implement the flat structure, you need to make the following changes:

1. Move Configuration File

Move wp-config.php from the public/ directory to the root app/ directory.

2. Verify Composer Dependencies

Ensure that the vendor/ directory is located in the app/ directory, at the same level as wp-config.php.

3. Update Composer Configuration

Update your composer.json file to reflect the flat structure. Locate the extra section and modify the installation directory:

Change from:

"extra": {
    "wordpress-install-dir": "public/wp",
    "installer-paths": {
        "public/wp-content/mu-plugins/{$name}/": [
            "type:wordpress-muplugin"
        ],
        "public/wp-content/plugins/{$name}/": [
            "type:wordpress-plugin"
        ],
        "public/wp-content/themes/{$name}/": [
            "type:wordpress-theme"
        ]
    }
}

Change to:

"extra": {
    "wordpress-install-dir": "public",
    "installer-paths": {
        "public/wp-content/mu-plugins/{$name}/": [
            "type:wordpress-muplugin"
        ],
        "public/wp-content/plugins/{$name}/": [
            "type:wordpress-plugin"
        ],
        "public/wp-content/themes/{$name}/": [
            "type:wordpress-theme"
        ]
    }
}

The key change is updating wordpress-install-dir from "public/wp" to "public" so that WordPress core files are installed directly into the public/ directory rather than a subdirectory.

Automatic Path Detection

The Framework now automatically detects the correct directory structure without requiring manual path configuration. The AppFactory::create(__DIR__) call works for both flat and modular structures by:

1. First checking for vendor/autoload.php in the current directory
2. If not found, checking the parent directory

This means no bootstrap path changes are required when switching between structures - the same code works for both setups.

Composer Installation and Autoloading

After updating your composer.json configuration, you need to install or update your dependencies to ensure WordPress is installed in the correct location:

# If starting fresh
composer install

# If you already have dependencies installed, update to apply the new configuration
composer update

These commands will:

• Generate the vendor/ directory required to bootstrap the Framework
• Install WordPress core into the public/ directory (instead of public/wp/)
• Place plugins, themes, and mu-plugins in the correct wp-content subdirectories

The Framework automatically locates the Composer autoloader regardless of directory structure

When to Use This Structure

The flat setup is recommended in the following scenarios:

• Legacy Migration: When migrating from an existing site with a traditional structure
• Standard Compatibility: Working in environments that expect conventional WordPress layouts
• Plugin Compatibility: When using plugins or tools that assume default WordPress file paths
• Hosting Requirements: Some hosting providers may require this specific directory structure

Verification

Once your directory structure is configured, the Framework will initialize automatically. Your site will load from the public/ directory exactly like a standard installation.

To verify your setup is working correctly:

1. Update your composer.json file with the correct wordpress-install-dir setting
2. Run composer install or composer update to apply the new configuration
3. Confirm all WordPress core files are now in the public/ directory (not public/wp/)
4. Ensure wp-config.php and vendor/ are in the app/ directory
5. Test that your WordPress site loads properly

No manual path configuration is required - the Framework automatically detects the correct structure.

Troubleshooting

If you encounter issues:

• WordPress core in wrong location: Verify that wordpress-install-dir in composer.json is set to "public" and run composer update
• Autoloader errors: Verify that composer install was run successfully after updating composer.json
• File not found errors: Ensure all WordPress core files are properly located in public/ (not public/wp/)
• Plugin/theme installation issues: Check that the installer paths in composer.json point to the correct directories

The Framework's automatic path detection eliminates most path-related configuration issues.