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.

Note: Flat structure support was added in verison 0.11.0

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. Update Environment Variables

Configure your environment variables to reflect the flat structure. The key difference is that WordPress core is now served from the root public directory instead of a subdirectory:

For Flat Structure:

HOME_URL='https://example.com'
WP_SITEURL="${HOME_URL}/"
ADMIN_LOGIN_URL="${HOME_URL}/wp-login.php"

For comparison, Modular Structure uses:

HOME_URL='https://example.com'
WP_SITEURL="${HOME_URL}/wp"
ADMIN_LOGIN_URL="${HOME_URL}/wp/wp-login.php"

The important changes are:

• WP_SITEURL changes from "${HOME_URL}/wp" to "${HOME_URL}/"
• ADMIN_LOGIN_URL changes from "${HOME_URL}/wp/wp-login.php" to "${HOME_URL}/wp-login.php"

3. Verify Composer Dependencies

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

4. 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.

Is It Safe to Switch?

Yes, switching to the flat structure is completely safe when your WordPress site is managed by Composer (like in this Framework setup).

What Composer Manages

Composer handles the installation and updates of:

• WordPress core files (the main WordPress software)
• Plugins and themes listed in your composer.json
• Directory structure and file placement

What Won't Be Affected

When you switch to the flat structure, these important parts of your site remain untouched:

• Your site content - All posts, pages, and media uploads stay exactly where they are
• Configuration files - Your wp-config.php and environment settings are safe
• Database - All your site data remains unchanged
• Custom uploads - Files in wp-content/uploads/ are preserved

Why It's Safe

The Framework uses Composer to manage WordPress as a package, which means:

• WordPress is installed fresh each time (no conflicting files)
• Your content and configuration live separately from the core WordPress files
• Switching structures just changes where WordPress core files are placed
• Your actual website data and settings aren't touched

Before You Switch

While it's safe, it's always good practice to:

1. Test on a development site first - Make sure everything works as expected
2. Have a backup - Though not required, it's always wise to backup before making changes
3. Update gradually - Switch structure, test, then deploy to production

Bottom line: If you're using this Framework with Composer, switching to the flat structure is a safe, straightforward process.

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. Update your environment variables to use the flat structure URLs
3. Run composer install or composer update to apply the new configuration
4. Confirm all WordPress core files are now in the public/ directory (not public/wp/)
5. Ensure wp-config.php and vendor/ are in the app/ directory
6. 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
• URL/login issues: Verify your environment variables are set correctly for the flat structure (WP_SITEURL should end with "/" and ADMIN_LOGIN_URL should point directly to "/wp-login.php")

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