README

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

Warning

CakePHP 2.x is for legacy maintenance only. For new projects, use CakePHP 5.x instead.

Planning to migrate to CakePHP 5.x?

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

Restructuring to Modern Layout (Step 2)

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

Directory Structure Comparison

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/
├── config/             (lowercase, top-level)
├── src/                (all PHP code)
│   ├── Controller/
│   ├── Model/
│   └── View/          (Helper classes only)
├── templates/          (all .ctp files, separated)
├── tests/              (lowercase, top-level)
├── plugins/            (Composer-managed)
├── vendor/             (standard Composer)
├── logs/               (separated from tmp/)
├── tmp/
├── bin/
│   └── cake
└── webroot/

File Migration Map

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

From (Traditional)	To (Modern)
`app/Config/*`	`config/*`
`app/Controller/*`	`src/Controller/*`
`app/Model/*`	`src/Model/*`
`app/View/*/.ctp`	`templates/*/.ctp`
`app/View/Helper/*`	`src/View/Helper/*`
`app/Console/*`	`src/Console/*`
`app/Console/cake`	`bin/cake`
`app/Lib/*`	`src/Lib/*`
`app/Locale/*`	`src/Locale/*`
`app/Test/*`	`tests/*`
`app/Plugin/*`	`plugins/*` (use Composer)
`app/Vendor/*`	`vendor/*` (use Composer)
`app/tmp/logs/*`	`logs/*`
`app/tmp/*`	`tmp/*`
`app/webroot/*`	`webroot/*`

Migration Steps

1. Update composer.json

{
    "require": {
        "php": "^8.0",
        "friendsofcake2/cakephp": "^2.10"
    },
    "config": {
        "vendor-dir": "vendor/",
        "sort-packages": true,
        "allow-plugins": {
            "composer/installers": true
        }
    },
    "extra": {
        "installer-paths": {
            "plugins/{$name}/": ["type:cakephp-plugin"]
        }
    }
}

2. Update Bootstrap Path Definitions

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.

3. Migrate Files

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

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

4. Verify Your Application Still Works

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

Upgrading to CakePHP 5.x (Step 3)

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.

Requirements

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 friendsofcake2/cakephp requirements for details.

Technical Implementation

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 friendsofcake2/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.

Development

Running Tests

./bin/cake test app AllTests

Or with PHPUnit:

./vendor/bin/phpunit

Code Standards

Check your code against CakePHP coding standards:

./vendor/bin/phpcs

friendsofcake2 / app

Maintainers

Details