Application Skeleton Documentation

pieceofcake2/app is the application skeleton for CakePHP 2 applications running on pieceofcake2/cakephp. It uses a directory layout compatible with CakePHP 5 (config/, src/, templates/, tests/, webroot/) and loads CakePHP and all dependencies with Composer.

WARNING

CakePHP 2.x is for the maintenance of existing applications. For new projects, use the current major version of CakePHP instead.

• Requirements
• Installation
• Directory Layout
• Configuration
• Environment Variables (.env)
• Running the Application
• Development

To move an existing application with the legacy app/ layout to this layout, see Migrating to the Modern Layout.

Requirements

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

See the requirements of pieceofcake2/cakephp for details.

Installation

Create a new application with Composer's create-project command:

composer create-project pieceofcake2/app my_app

This creates the my_app directory and installs CakePHP (pieceofcake2/cakephp) into vendor/. The Bake and DebugKit plugins and the development tools (PHPUnit, PHPStan with pieceofcake2/phpstan-cakephp2, and the CakePHP coding standard) are installed as development dependencies.

Then finish the configuration:

1. Copy config/database.php.default to config/database.php and enter your database connection settings, or set them with environment variables.
2. Change Security.salt and Security.cipherSeed in config/core.php, or set SECURITY_SALT and SECURITY_CIPHER_SEED. The skeleton ships with well-known example values that must not be used in a real application.
3. If you send email, copy config/email.php.default to config/email.php and configure your transport.
4. Make sure that the web server can write to tmp/ and logs/.

config/database.php, config/email.php and the .env files are ignored by Git.

Loading the Development Plugins

The plugins installed by Composer are not loaded automatically. Load them in config/bootstrap.php:

CakePlugin::loadAll();

CakePlugin::loadAll() loads the plugins that are installed, so it also works when the development plugins are not installed (composer install --no-dev). To load the plugins one by one, make sure that CakePlugin::load() only runs where the plugin is installed, because loading a missing plugin throws a MissingPluginException.

Then add the DebugKit toolbar to your AppController as described in the DebugKit documentation, and run Bake with bin/cake bake.

Directory Layout

my_app/
├── bin/
│   └── cake            the console
├── config/             configuration (core.php, bootstrap.php, routes.php, database.php, ...)
├── logs/               log files
├── plugins/            plugins installed by Composer
├── resources/
│   └── locales/        translation files
├── src/                PHP code
│   ├── Console/        shells, tasks and bake templates
│   ├── Controller/
│   ├── Lib/
│   ├── Model/
│   └── View/           helpers
├── templates/          view templates, layouts, elements and email templates
├── tests/
│   ├── Fixture/
│   └── TestCase/
├── tmp/                cache, sessions and test files
├── vendor/             Composer packages, including CakePHP
└── webroot/            document root (index.php, test.php, css/, js/, img/)

webroot/index.php, webroot/test.php and bin/cake load config/define.php, which sets the root directory (ROOT), the application directory (APP_DIR, src), the document root (WWW_ROOT) and the Composer vendor directory (VENDORS). CakePHP finds the other directories by itself: config/, tests/, tmp/, logs/, templates/ and resources/locales/ are used when they exist.

The legacy layout with an app/ directory (app/Config/, app/Controller/, app/View/, ...) is supported as well, but the skeleton only ships the modern layout.

Configuration

File	Contents
config/core.php	Debug level, error and exception handling, caching, session, security salts.
config/bootstrap.php	Cache configuration, plugin loading, logging and other application setup.
config/routes.php	URL routing.
config/database.php	Database connections (default and test). Copy it from database.php.default.
config/email.php	Email transports and profiles. Copy it from email.php.default.
config/acl.php, config/acl.ini.php	Configuration of IniAcl and PhpAcl.
config/define.php	Path constants of the modern layout.
config/Schema/	Schema files of the DbAcl, i18n and session tables.

Environment Variables (.env)

Settings such as the debug level, security salt and database credentials can be read from environment variables. For local development, copy the example file and edit it:

cp config/.env.example config/.env
# or, in the project root:
cp config/.env.example .env

config/.env and .env in the project root are loaded at the top of config/core.php (so they apply to web requests, bin/cake and tests) using josegonzalez/dotenv. Both are ignored by Git. Values are then available through env(), getenv(), $_ENV and $_SERVER.

This follows the .env support of the CakePHP 3+/5 application skeleton (cakephp/app loads config/.env with josegonzalez/dotenv in config/bootstrap.php), backported for CakePHP 2 and extended to also accept a .env in the project root.

Variable	Setting	Default
DEBUG	debug (0, 1, 2, true = 2, false = 0)	2
SECURITY_SALT	Security.salt	value in config/core.php
SECURITY_CIPHER_SEED	Security.cipherSeed (digits only)	value in config/core.php
DB_DATASOURCE, DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE	default connection in config/database.php	values in config/database.php
DB_TEST_DATASOURCE, DB_TEST_HOST, DB_TEST_PORT, DB_TEST_USERNAME, DB_TEST_PASSWORD, DB_TEST_DATABASE	test connection in config/database.php	values in config/database.php

• Precedence: real environment variables (web server, shell, container, CI) > config/.env > root .env. config/.env is loaded first and the root .env second; a variable that is already set is never overwritten.
• Unset or empty variables keep the defaults, so the application behaves exactly as before without a .env file (an empty DB_PASSWORD / DB_TEST_PASSWORD is allowed).
• Quote values in .env files (e.g. DEBUG="0"). Unquoted numbers are normalized by the parser (007 becomes 7, and long digit strings such as a cipher seed overflow).
• .env files are meant for development. In production, set real environment variables instead.
• The database variables are read by config/database.php.default. If you created config/database.php before this was added, copy the __construct() and applyEnv() methods into it.

Running the Application

For development, start PHP's built-in web server with:

bin/cake server

and open http://localhost:8765/. Use --port (-p) to choose another port.

In production, point the document root of your web server to webroot/. The webroot/.htaccess file rewrites the requests to index.php for Apache with mod_rewrite.

Development

Running Tests

Put your test cases in tests/TestCase/ and your fixtures in tests/Fixture/. Configure the test connection in config/database.php (or with the DB_TEST_* variables), then run all tests with PHPUnit:

vendor/bin/phpunit

or a single test case with the test shell:

bin/cake test app Controller/PostsController

Code Standards

Check your code against the CakePHP coding standard:

vendor/bin/phpcs

Static Analysis

Run PHPStan (level 5) on src/ and config/:

vendor/bin/phpstan analyse

The configuration is in phpstan.neon and uses the pieceofcake2/phpstan-cakephp2 extension.