Installation¶

Installing Composer¶

CakePHP uses Composer, a dependency management tool, as the officially supported method for installation.

• Installing Composer on Linux and macOS

  1. Run the installer script as described in the official Composer documentation and follow the instructions to install Composer.

  2. Execute the following command to move the composer.phar to a directory that is in your path:

     mv composer.phar /usr/local/bin/composer
     

• Installing Composer on Windows

  For Windows systems, you can download Composer’s Windows installer here. Further instructions for Composer’s Windows installer can be found within the README here.

Create a CakePHP Project¶

You can create a new CakePHP application using composer’s create-project command:

composer create-project --prefer-dist cakephp/app:~5.0 my_app_name

Once Composer finishes downloading the application skeleton and the core CakePHP library, you should have a functioning CakePHP application installed via Composer. Be sure to keep the composer.json and composer.lock files with the rest of your source code.

You can now visit the path to where you installed your CakePHP application and see the default home page. To change the content of this page, edit templates/Pages/home.php.

Although composer is the recommended installation method, there are pre-installed downloads available on Github. Those downloads contain the app skeleton with all vendor packages installed. Also it includes the composer.phar so you have everything you need for further use.

Keeping Up To Date with the Latest CakePHP Changes¶

By default this is what your application composer.json looks like:

"require": {
    "cakephp/cakephp": "5.0.*"
}

Each time you run php composer.phar update you will receive patch releases for this minor version. You can instead change this to ^5.0 to also receive the latest stable minor releases of the 5.x branch.

Installation using DDEV¶

Another quick way to install CakePHP is via DDEV. It is an open source tool for launching local web development environments.

If you want to configure a new project, you just need:

mkdir my-cakephp-app
cd my-cakephp-app
ddev config --project-type=cakephp --docroot=webroot
ddev composer create --prefer-dist cakephp/app:~5.0
ddev launch

If you have an existing project:

git clone <your-cakephp-repo>
cd <your-cakephp-project>
ddev config --project-type=cakephp --docroot=webroot
ddev composer install
ddev launch

Please check DDEV Docs for details on how to install / update DDEV.

Apache¶

While CakePHP is built to work with mod_rewrite out of the box–and usually does–we’ve noticed that a few users struggle with getting everything to play nicely on their systems.

Here are a few things you might try to get it running correctly. First look at your httpd.conf. (Make sure you are editing the system httpd.conf rather than a user- or site-specific httpd.conf.)

These files can vary between different distributions and Apache versions. You may also take a look at https://cwiki.apache.org/confluence/display/httpd/DistrosDefaultLayout for further information.

1. Make sure that an .htaccess override is allowed and that AllowOverride is set to All for the correct DocumentRoot. You should see something similar to:

   # Each directory to which Apache has access can be configured with respect
   # to which services and features are allowed and/or disabled in that
   # directory (and its subdirectories).
   #
   # First, we configure the "default" to be a very restrictive set of
   # features.
   <Directory />
       Options FollowSymLinks
       AllowOverride All
   #    Order deny,allow
   #    Deny from all
   </Directory>
   

2. Make sure you are loading mod_rewrite correctly. You should see something like:

   LoadModule rewrite_module libexec/apache2/mod_rewrite.so
   

   In many systems these will be commented out by default, so you may just need to remove the leading # symbols.

   After you make changes, restart Apache to make sure the settings are active.

   Verify that your .htaccess files are actually in the right directories. Some operating systems treat files that start with ‘.’ as hidden and therefore won’t copy them.

3. Make sure your copy of CakePHP comes from the downloads section of the site or our Git repository, and has been unpacked correctly, by checking for .htaccess files.

   CakePHP app directory (will be copied to the top directory of your application by bake):

   <IfModule mod_rewrite.c>
      RewriteEngine on
      RewriteRule    ^$    webroot/    [L]
      RewriteRule    (.*) webroot/$1    [L]
   </IfModule>
   

   CakePHP webroot directory (will be copied to your application’s web root by bake):

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^ index.php [L]
   </IfModule>
   

   If your CakePHP site still has problems with mod_rewrite, you might want to try modifying settings for Virtual Hosts. On Ubuntu, edit the file /etc/apache2/sites-available/default (location is distribution-dependent). In this file, ensure that AllowOverride None is changed to AllowOverride All, so you have:

   <Directory />
       Options FollowSymLinks
       AllowOverride All
   </Directory>
   <Directory /var/www>
       Options FollowSymLinks
       AllowOverride All
       Order Allow,Deny
       Allow from all
   </Directory>
   

   On macOS, another solution is to use the tool virtualhostx to make a Virtual Host to point to your folder.

   For many hosting services (GoDaddy, 1and1), your web server is being served from a user directory that already uses mod_rewrite. If you are installing CakePHP into a user directory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, you’ll need to add RewriteBase statements to the .htaccess files CakePHP uses (.htaccess, webroot/.htaccess).

   This can be added to the same section with the RewriteEngine directive, so for example, your webroot .htaccess file would look like:

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /path/to/app
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^ index.php [L]
   </IfModule>
   

   The details of those changes will depend on your setup, and can include additional things that are not related to CakePHP. Please refer to Apache’s online documentation for more information.

4. (Optional) To improve production setup, you should prevent invalid assets from being parsed by CakePHP. Modify your webroot .htaccess to something like:

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /path/to/app/
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteCond %{REQUEST_URI} !^/(webroot/)?(img|css|js)/(.*)$
       RewriteRule ^ index.php [L]
   </IfModule>
   

   The above will prevent incorrect assets from being sent to index.php and instead display your web server’s 404 page.

   Additionally you can create a matching HTML 404 page, or use the default built-in CakePHP 404 by adding an ErrorDocument directive:

   ErrorDocument 404 /404-not-found
   

nginx¶

nginx does not make use of .htaccess files like Apache, so it is necessary to create those rewritten URLs in the site-available configuration. This is usually found in /etc/nginx/sites-available/your_virtual_host_conf_file. Depending on your setup, you will have to modify this, but at the very least, you will need PHP running as a FastCGI instance. The following configuration redirects the request to webroot/index.php:

location / {
    try_files $uri $uri/ /index.php?$args;
}

A sample of the server directive is as follows:

server {
    listen   80;
    listen   [::]:80;
    server_name www.example.com;
    return 301 http://example.com$request_uri;
}

server {
    listen   80;
    listen   [::]:80;
    server_name example.com;

    root   /var/www/example.com/public/webroot;
    index  index.php;

    access_log /var/www/example.com/log/access.log;
    error_log /var/www/example.com/log/error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_intercept_errors on;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

NGINX Unit¶

NGINX Unit is dynamically configurable in runtime; the following configuration relies on webroot/index.php, also serving other .php scripts if present via cakephp_direct:

{
    "listeners": {
        "*:80": {
            "pass": "routes/cakephp"
        }
    },

    "routes": {
        "cakephp": [
            {
                "match": {
                    "uri": [
                        "*.php",
                        "*.php/*"
                    ]
                },

                "action": {
                    "pass": "applications/cakephp_direct"
                }
            },
            {
                "action": {
                    "share": "/path/to/cakephp/webroot/",
                    "fallback": {
                        "pass": "applications/cakephp_index"
                    }
                }
            }
        ]
    },

    "applications": {
        "cakephp_direct": {
            "type": "php",
            "root": "/path/to/cakephp/webroot/",
            "user": "www-data"
        },

        "cakephp_index": {
            "type": "php",
            "root": "/path/to/cakephp/webroot/",
            "user": "www-data",
            "script": "index.php"
        }
    }
}

To enable this config (assuming it’s saved as cakephp.json):

# curl -X PUT --data-binary @cakephp.json --unix-socket \
       /path/to/control.unit.sock http://localhost/config

IIS7 (Windows hosts)¶

IIS7 does not natively support .htaccess files. While there are add-ons that can add this support, you can also import htaccess rules into IIS to use CakePHP’s native rewrites. To do this, follow these steps:

1. Use Microsoft’s Web Platform Installer to install the URL Rewrite Module 2.0 or download it directly (32-bit / 64-bit).

2. Create a new file called web.config in your CakePHP root folder.

3. Using Notepad or any XML-safe editor, copy the following code into your new web.config file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Exclude direct access to webroot/*"
                  stopProcessing="true">
                    <match url="^webroot/(.*)$" ignoreCase="false" />
                    <action type="None" />
                </rule>
                <rule name="Rewrite routed access to assets(img, css, files, js, favicon)"
                  stopProcessing="true">
                    <match url="^(font|img|css|files|js|favicon.ico)(.*)$" />
                    <action type="Rewrite" url="webroot/{R:1}{R:2}"
                      appendQueryString="false" />
                </rule>
                <rule name="Rewrite requested file/folder to index.php"
                  stopProcessing="true">
                    <match url="^(.*)$" ignoreCase="false" />
                    <action type="Rewrite" url="index.php"
                      appendQueryString="true" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Once the web.config file is created with the correct IIS-friendly rewrite rules, CakePHP’s links, CSS, JavaScript, and rerouting should work correctly.

Lighttpd¶

Lighttpd does not make use of .htaccess files like Apache, so it is necessary to add a url.rewrite-once configuration in conf/lighttpd.conf. Ensure the following is present in your lighthttpd configuration:

server.modules += (
    "mod_alias",
    "mod_cgi",
    "mod_rewrite"
)

# Directory Alias
alias.url       = ( "/TestCake" => "C:/Users/Nicola/Documents/TestCake" )

# CGI Php
cgi.assign      = ( ".php" => "c:/php/php-cgi.exe" )

# Rewrite Cake Php (on /TestCake path)
url.rewrite-once = (
    "^/TestCake/(css|files|img|js|stats)/(.*)$" => "/TestCake/webroot/$1/$2",
    "^/TestCake/(.*)$" => "/TestCake/webroot/index.php/$1"
)

The above lines include PHP CGI configuration and example application configuration for an application on the /TestCake path.

I Can’t Use URL Rewriting¶

If you don’t want or can’t get mod_rewrite (or some other compatible module) running on your server, you will need to use CakePHP’s built in pretty URLs. In config/app.php, uncomment the line that looks like:

'App' => [
    // ...
    // 'baseUrl' => env('SCRIPT_NAME'),
]

Also remove these .htaccess files:

/.htaccess
webroot/.htaccess

This will make your URLs look like www.example.com/index.php/controllername/actionname/param rather than www.example.com/controllername/actionname/param.