CakePHP Deployment & Usage Guide

1. Prerequisites

Before deploying or running a CakePHP application, ensure the following are installed on your system:

• PHP: Minimum version depends on the CakePHP version you are using. Check the version map for exact requirements. PHP must be compiled with the following extensions:
  • intl (for internationalization)
  • mbstring (for multibyte string handling)
  • openssl (for security)
  • pdo and a database driver (e.g., pdo_mysql, pdo_pgsql, pdo_sqlite)
• Composer: The PHP package manager. Install from getcomposer.org.
• Web Server: Apache with mod_rewrite enabled, or Nginx. For local development, PHP's built-in development server is sufficient.
• Database: MySQL, PostgreSQL, SQLite, or another supported database.

2. Installation

For a New Project (Recommended)

Use the official app skeleton to create a new CakePHP application with a standard directory structure and configuration.

composer create-project --prefer-dist cakephp/app my_app_name
cd my_app_name

For an Existing Project

Add the CakePHP framework to your existing project:

composer require cakephp/cakephp

3. Configuration

Database Configuration

1. Open config/app_local.php (this file is generated from config/app_local.php.example on first install).
2. Locate the 'Datasources' array.
3. Set the connection details for your primary database (default key is 'default'):

   'default' => [
       'className' => 'Cake\Database\Connection',
       'driver' => 'Cake\Database\Driver\Mysql', // or Postgres, Sqlite, etc.
       'host' => 'localhost',
       'username' => 'your_user',
       'password' => 'your_password',
       'database' => 'your_database',
       'encoding' => 'utf8mb4',
       'timezone' => 'UTC',
       'cacheMetadata' => true,
   ],
   

4. For SQLite, use:

   'driver' => 'Cake\Database\Driver\Sqlite',
   'database' => 'path/to/database.sqlite',
   

Application Configuration

• Debug Mode: In config/app_local.php, set 'debug' => true for development and false for production.
• App Name: Set 'App' => ['name' => 'Your App Name'].
• Security Salt & Cipher Seed: These are auto-generated in config/app_local.php. Do not share them.

Environment Variables (Optional)

You can use environment variables (e.g., via vlucas/phpdotenv) to manage configuration. The skeleton supports loading .env files. Create a .env file in the project root:

APP_DEBUG=true
APP_NAME="My CakePHP App"
DATABASE_URL="mysql://user:pass@localhost/dbname"

4. Build & Run

Local Development Server

CakePHP includes a built-in development server for quick testing.

# From your project root
bin/cake server

Your application will be available at http://localhost:8765.

Running Tests

1. Ensure development dependencies are installed: composer install.
2. Copy the test configuration:

   cp phpunit.xml.dist phpunit.xml
   

3. Edit phpunit.xml to add your test database credentials under the <php> section if not using SQLite.
4. Run the test suite:

   vendor/bin/phpunit
   

Production Build

There is no explicit "build" step. For production:

1. Set 'debug' => false in config/app_local.php.
2. Clear the cache:

   bin/cake cache clear_all
   

3. Ensure the logs/ and tmp/ directories are writable by the web server user.

5. Deployment

General Steps

1. Upload Files: Transfer all application files to your server. Exclude vendor/ if you plan to run composer install on the server.
2. Install Dependencies: On the server, run composer install --no-dev --optimize-autoloader.
3. Set Permissions:

   chmod -R 775 tmp logs
   chown -R www-data:www-data tmp logs # Adjust user/group for your server (e.g., nginx, apache)
   

4. Configure Web Server:
   • Apache: Ensure mod_rewrite is enabled. The .htaccess files in the root, app/, and webroot/ directories handle URL rewriting. The document root should point to the webroot/ directory.
   • Nginx: Use a configuration similar to:

     server {
         listen 80;
         root /path/to/your/app/webroot;
         index index.php;
         location / {
             try_files $uri $uri/ /index.php?$args;
         }
         location ~ \.php$ {
             include fastcgi_params;
             fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # Adjust PHP version/socket
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
         }
     }
     

5. Database: Create the database and run migrations (if any) via bin/cake migrations migrate or manually import schema.

Recommended Platforms

• Shared Hosting: Works with Apache and PHP. Ensure mod_rewrite is enabled and the document root is set to webroot/.
• VPS/Cloud (AWS EC2, DigitalOcean, Linode): Full control. Install LAMP/LEMP stack, deploy code, configure web server as above.
• Platform-as-a-Service (PaaS):
  • Heroku: Use the official CakePHP buildpack. Set APP_DEBUG=false and configure database via DATABASE_URL.
  • Railway/Render: Configure a PHP service with build command composer install --no-dev --optimize-autoloader and start command bin/cake server -H 0.0.0.0 -p $PORT.

6. Troubleshooting

Common Issues & Solutions

Getting Help

• Documentation: book.cakephp.org
• Community: Slack, Discord, Forum
• Issues: GitHub Issues