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/
├── 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/

File Migration Map

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

Migration Steps

1. Update composer.json

{
    "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"]
        }
    }
}

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:

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

4. Verify Your Application Still Works

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.

5. Leverage Composer Autoloading (Optional)

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.

Important

You must run composer dump-autoload every time you create a new class file. Composer's classmap autoloader needs to be regenerated to recognize new classes.

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.

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

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

Documentation

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

License

MIT License. See LICENSE file for details.

Support

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

• pieceofcake2/cakephp Issues
• pieceofcake2/app Issues