A reference implementation for CakePHP 2.x applications using a modern, CakePHP 5.x-compatible directory structure.

If you're planning to upgrade to CakePHP 5.x in the future, you can prepare now by adopting the modern directory structure while still on CakePHP 2.x:

Traditional migration approach (harder):

CakePHP 2.x → CakePHP 5.x
(change everything at once: code + folder structure + APIs)

New gradual migration approach (easier):

Step 1: CakePHP 2.x with traditional structure
        ↓ (modernize folder structure only)
Step 2: CakePHP 2.x with CakePHP 5.x-style structure ← You can stop here
        ↓ (upgrade code only)
Step 3: CakePHP 5.x with CakePHP 5.x-style structure

Benefits:

• ✅ Smaller, manageable changes: Separate folder restructuring from code changes
• ✅ Test incrementally: Verify each step works before moving to the next
• ✅ Reduced risk: You can stay on Step 2 indefinitely if needed
• ✅ Team-friendly: Easier for teams to understand and review smaller changes

This skeleton shows you how to achieve Step 2 - running CakePHP 2.x with a modern folder structure.

Before: Traditional CakePHP 2.x

your-project/
├── app/
│   ├── Config/          (uppercase, nested)
│   ├── Controller/
│   ├── Model/
│   ├── View/           (templates + helpers mixed)
│   ├── Test/
│   ├── Plugin/
│   ├── Vendor/
│   └── tmp/
│       └── logs/
├── vendors/
└── ...

After: Modern Structure (CakePHP 5.x Ready)

your-project/
├── bin/
│   └── cake
├── config/             (lowercase, top-level)
├── src/                (all PHP code)
│   ├── Controller/
│   ├── Model/
│   └── View/           (Helper classes only)
├── templates/          (all .ctp files, separated)
├── resources/
│   └── locales/
├── tests/              (lowercase, top-level)
├── plugins/            (Composer-managed)
├── vendor/             (standard Composer)
├── logs/               (separated from tmp/)
├── tmp/
└── webroot/

Use this table to migrate your files from traditional structure to modern structure:

{
    "require": {
        "php": ">=8.0",
        "pieceofcake2/cakephp": "^2.12"
    },
    "autoload": {
        "classmap": ["src/"]
    },
    "config": {
        "vendor-dir": "vendor/",
        "sort-packages": true,
        "allow-plugins": {
            "composer/installers": true
        }
    },
    "extra": {
        "installer-paths": {
            "plugins/{$name}/": ["type:cakephp-plugin"]
        }
    }
}

Copy or reference this skeleton's webroot/index.php, webroot/test.php, and bin/cake to update the path definitions in your project:

define('ROOT', dirname(__DIR__));
define('APP_DIR', 'src');                     // Changed from 'app'
define('APP', ROOT . DS . APP_DIR . DS);
define('CONFIG', ROOT . DS . 'config' . DS);  // Top-level, lowercase
define('TESTS', ROOT . DS . 'tests' . DS);    // Top-level, lowercase
define('TMP', ROOT . DS . 'tmp' . DS);        // Top-level
define('LOGS', ROOT . DS . 'logs' . DS);      // Separated from tmp/
define('VENDORS', ROOT . DS . 'vendor' . DS); // Standard Composer

Refer to this skeleton's implementation files for complete examples.

Move files according to the File Migration Map above. You can do this gradually:

1. Configuration files: app/Config/* → config/*
2. PHP code: app/Controller/*, app/Model/* → src/
3. Templates: app/View/**/*.ctp → templates/
4. Tests: app/Test/* → tests/
5. Dependencies: Use Composer for plugins and vendors

The pieceofcake2/cakephp core automatically supports this modern structure with App::uses() and class loading, so your existing CakePHP 2.x code should work without modifications.

Once Composer's autoload is configured in composer.json, you can remove App::uses() calls from your code:

"autoload": {
    "classmap": ["src/"]
}

After running composer dump-autoload, you can safely remove App::uses() statements from your controllers, models, helpers, and shells.

For example:

// Before
App::uses('AppController', 'Controller');

class UsersController extends AppController {
    // ...
}

// After (with Composer autoload)
class UsersController extends AppController {
    // ...
}

Note: Plugins that don't support Composer autoloading will still require App::uses() or CakePlugin::load() to function properly.

Once you've completed Step 2 (modern folder structure with CakePHP 2.x), upgrading to CakePHP 5.x becomes much simpler:

What's already done:

• ✅ Directory structure is already correct - No need to reorganize files
• ✅ Templates already separated - No need to move .ctp files
• ✅ Modern Composer setup - Already using vendor/ and plugins/

What you need to do:

• Update composer.json to require CakePHP 5.x
• Update code for CakePHP 5.x API changes
• Test and fix compatibility issues

The key advantage: You can focus 100% on code changes, not structural changes.

Refer to the CakePHP 5.x Migration Guide for framework-specific changes.

• PHP 8.0, 8.1, 8.2, 8.3, 8.4, 8.5
• Composer
• Database: MySQL 5.6+, PostgreSQL 9.4+, SQLite 3, or SQL Server 2022+
• PHP Extensions: mbstring, intl, openssl, PDO driver for your database

See pieceofcake2/cakephp requirements for details.

This modern directory structure works with CakePHP 2.x through custom path configuration in bootstrap files (webroot/index.php, webroot/test.php, bin/cake).

The pieceofcake2/cakephp core has been enhanced to:

• Automatically load classes from src/Controller/, src/Model/, etc. with App::uses()
• Find templates in the templates/ directory
• Support both modern and traditional file locations during migration

You don't need to modify your application code - the framework handles the path mapping automatically.

./bin/cake test app AllTests

Or with PHPUnit:

./vendor/bin/phpunit

Check your code against CakePHP coding standards:

./vendor/bin/phpcs

• CakePHP 2.x Documentation
• CakePHP 5.x Migration Guide

MIT License. See LICENSE file for details.

This is a community-maintained fork of CakePHP 2.x. For issues and questions:

• pieceofcake2/cakephp Issues
• pieceofcake2/app Issues