Installation. CakePHP CakePHP

CHAPTER 2

Installation

CakePHP is fast and easy to install. The minimum requirements are a webserver and a copy of Cake, that’s it! While this manual focuses primarily on setting up with Apache (because it’s the most common), you can configure Cake to run on a variety of web servers such as LightHTTPD or Microsoft IIS.

Requirements

• HTTP Server. For example: Apache. mod_rewrite is preferred, but by no means required.

• PHP 5.2.8 or greater.

Technically a database engine isn’t required, but we imagine that most applications will utilize one.

CakePHP supports a variety of database storage engines:

• MySQL (4 or greater)

• PostgreSQL

• Microsoft SQL Server

• SQLite

Note: The built-in drivers all require PDO. You should make sure you have the correct PDO extensions installed.

License

CakePHP is licensed under the MIT license. This means that you are free to modify, distribute and republish the source code on the condition that the copyright notices are left intact. You are also free to incorporate

CakePHP into any Commercial or closed source application.

27

CakePHP Cookbook Documentation, Release 2.x

Downloading CakePHP

There are two main ways to get a fresh copy of CakePHP. You can either download an archive copy

(zip/tar.gz/tar.bz2) from the main website, or check out the code from the git repository.

To download the latest major release of CakePHP. Visit the main website http://www.cakephp.org

and follow the “Download Now” link.

All current releases of CakePHP are hosted on Github (http://github.com/cakephp/cakephp). Github houses both CakePHP itself as well as many other plugins for CakePHP. The CakePHP releases are available at

Github downloads (http://github.com/cakephp/cakephp/downloads).

Alternatively you can get fresh off the press code, with all the bug-fixes and up to the minute enhancements.

These can be accessed from github by cloning the Github (http://github.com/cakephp/cakephp) repository: git

clone

git :// github .

com / cakephp / cakephp .

git

Permissions

CakePHP uses the app/tmp directory for a number of different operations. Model descriptions, cached views, and session information are just a few examples.

As such, make sure the directory app/tmp and all its subdirectories in your cake installation are writable by the web server user.

Setup

Setting up CakePHP can be as simple as slapping it in your web server’s document root, or as complex and flexible as you wish. This section will cover the three main installation types for CakePHP: development, production, and advanced.

• Development: easy to get going, URLs for the application include the CakePHP installation directory name, and less secure.

• Production: Requires the ability to configure the web server’s document root, clean URLs, very secure.

• Advanced: With some configuration, allows you to place key CakePHP directories in different parts of the filesystem, possibly sharing a single CakePHP core library folder amongst many CakePHP applications.

Development

A development installation is the fastest method to setup Cake. This example will help you install a

CakePHP application and make it available at http://www.example.com/cake_2_0/ . We assume for the purposes of this example that your document root is set to /var/www/html.

28 Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

Unpack the contents of the Cake archive into /var/www/html. You now have a folder in your document root named after the release you’ve downloaded (e.g. cake_2.0.0). Rename this folder to cake_2_0. Your development setup will look like this on the file system:

/

var

/ www / html / cake_2_0 / app / lib / plugins / vendors /

.

htaccess index .

php

README

If your web server is configured correctly, you should now find your Cake application accessible at http://www.example.com/cake_2_0/ .

Using one CakePHP checkout for multiple applications

If you are developing a number of applications, it often makes sense to have them share the same CakePHP core checkout. There are a few ways in which you can accomplish this. Often the easiest is to use PHP’s include_path

. To start off, clone CakePHP into a directory. For this example, we’ll use ~/projects: git

clone

git :// github .

com / cakephp / cakephp .

git ~/ projects / cakephp

This will clone CakePHP into your ~/projects directory. If you don’t want to use git, you can download a zipball and the remaining steps will be the same. Next you’ll have to locate and modify your php.ini.

On *nix systems this is often in /etc/php.ini, but using php -i and looking for ‘Loaded Configuration File’. Once you’ve found the correct ini file, modify the include_path configuration to include

~/projects/cakephp/lib . An example would look like: include_path = .:/ home / mark / projects / cakephp / lib :/ usr / local / php / lib / php

After restarting your webserver, you should see the changes reflected in phpinfo().

Note: If you are on windows, separate include paths with ; instead of :

Having finished setting up your include_path your applications should be able to find CakePHP automatically.

Production

A production installation is a more flexible way to setup Cake. Using this method allows an entire domain to act as a single CakePHP application. This example will help you install Cake anywhere on your filesystem and make it available at http://www.example.com

. Note that this installation may require the rights to change the DocumentRoot on Apache webservers.

Production 29

CakePHP Cookbook Documentation, Release 2.x

Unpack the contents of the Cake archive into a directory of your choosing. For the purposes of this example, we assume you choose to install Cake into /cake_install. Your production setup will look like this on the filesystem:

/ cake_install / app / webroot / (

this

directory is set

as

the ‘‘ DocumentRoot ‘‘ directive) lib / plugins / vendors /

.

htaccess index .

php

README

Developers using Apache should set the DocumentRoot directive for the domain to:

DocumentRoot / cake_install / app / webroot

If your web server is configured correctly, you should now find your Cake application accessible at http://www.example.com

.

Advanced Installation and URL Rewriting

Advanced Installation

There may be some situations where you wish to place CakePHP’s directories on different places on the filesystem. This may be due to a shared host restriction, or maybe you just want a few of your apps to share the same Cake libraries. This section describes how to spread your CakePHP directories across a filesystem.

First, realize that there are three main parts to a Cake application:

1. The core CakePHP libraries, in /lib/Cake.

2. Your application code, in /app.

3. The application’s webroot, usually in /app/webroot.

Each of these directories can be located anywhere on your file system, with the exception of the webroot, which needs to be accessible by your web server. You can even move the webroot folder out of the app folder as long as you tell Cake where you’ve put it.

To configure your Cake installation, you’ll need to make some changes to the following files.

• /app/webroot/index.php

• /app/webroot/test.php (if you use the

Testing

feature.)

There are three constants that you’ll need to edit: ROOT, APP_DIR, and CAKE_CORE_INCLUDE_PATH.

• ROOT should be set to the path of the directory that contains your app folder.

• APP_DIR should be set to the (base)name of your app folder.

• CAKE_CORE_INCLUDE_PATH should be set to the path of your CakePHP libraries folder.

30 Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

Let’s run through an example so you can see what an advanced installation might look like in practice.

Imagine that I wanted to set up CakePHP to work as follows:

• The CakePHP core libraries will be placed in /usr/lib/cake.

• My application’s webroot directory will be /var/www/mysite/.

• My application’s app directory will be /home/me/myapp.

Given this type of setup, I would need to edit my webroot/index.php file (which will end up at

/var/www/mysite/index.php, in this example) to look like the following:

// /app/webroot/index.php (partial, comments removed)

if

( !

defined ( ’ROOT’ )) { define ( ’ROOT’ , DS .

’home’ .

DS .

’me’ );

}

if

( !

defined ( ’APP_DIR’ )) { define ( ’APP_DIR’ , ’myapp’ );

}

if

( !

defined ( ’CAKE_CORE_INCLUDE_PATH’ )) { define ( ’CAKE_CORE_INCLUDE_PATH’ , DS .

’usr’ .

DS .

’lib’ );

}

It is recommended to use the DS constant rather than slashes to delimit file paths. This prevents any missing file errors you might get as a result of using the wrong delimiter, and it makes your code more portable.

Apache and mod_rewrite (and .htaccess)

This section was moved to URL rewriting.

URL Rewriting

Apache and mod_rewrite (and .htaccess)

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).

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.

Advanced Installation and URL Rewriting 31

CakePHP Cookbook Documentation, Release 2.x

32

#

< Directory />

Options FollowSymLinks

AllowOverride All

#

#

Order deny,allow

Deny from all

</ Directory >

2. Make sure you are loading up 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 being prepended with a #) by default, so you may just need to remove those leading # symbols.

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

Verify that you your .htaccess files are actually in the right directories.

This can happen during copying because some operating systems treat files that start with ‘.’ as hidden and therefore won’t see them to copy.

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

Cake root directory (needs to be copied to your document, this redirects everything to your Cake app):

< IfModule mod_rewrite .

c >

RewriteEngine on

RewriteRule

RewriteRule

</ IfModule >

^ $ app / webroot / [L]

( .* ) app / webroot / $ 1 [L]

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

< IfModule mod_rewrite .

c >

RewriteEngine on

RewriteRule ^ $ webroot /

RewriteRule

</ IfModule >

( .* ) webroot / $ 1

[L]

[L]

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

< IfModule mod_rewrite .

c >

RewriteEngine On

RewriteCond % {REQUEST_FILENAME} !d

RewriteCond % {REQUEST_FILENAME} !f

RewriteRule ^ ( .* ) $ index .

php [QSA,L]

</ IfModule >

If your CakePHP site still has problems with mod_rewrite you might want to try and modify settings for virtualhosts. If 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:

Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

< Directory />

Options FollowSymLinks

AllowOverride All

</ Directory >

< Directory /

var

/ www >

Options Indexes FollowSymLinks MultiViews

AllowOverride All

Order Allow,Deny

Allow from all

</ Directory >

If on Mac OSX, 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 actually 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, /app/.htaccess, /app/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 / cake / app

RewriteCond % {REQUEST_FILENAME} !d

RewriteCond % {REQUEST_FILENAME} !f

RewriteRule ^ ( .* ) $ index .

php [QSA,L]

</ IfModule >

The details of those changes will depend on your setup, and can include additional things that are not

Cake related. Please refer to Apache’s online documentation for more information.

Pretty URLs on nginx

nginx is a popular server that uses less system resources than Apache. Its drawback is that it does not make use of .htaccess files like Apache, so it is necessary to create those rewritten URLs in the site-available configuration. Depending upon your setup, you will have to modify this, but at the very least, you will need

PHP running as a FastCGI instance.

server { listen 80 ; server_name www .

example .

com; rewrite ^ ( .* ) http :// example .

com $ 1 permanent;

} server { listen 80 ; server_name example .

com;

# root directive should be global

Advanced Installation and URL Rewriting 33

CakePHP Cookbook Documentation, Release 2.x

} root /

var

/ www / example .

com /

public

/ app / 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 ?

$uri & $args ;

} location ~ \ .

php $ { try_files $uri = 404 ;

include

/ etc / nginx / fastcgi_params; fastcgi_pass 127.0

.

0.1

: 9000 ; fastcgi_index index .

php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name ;

}

URL Rewrites on 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 (http://www.microsoft.com/web/downloads/platform.aspx) to install the URL Rewrite Module 2.0

(http://www.iis.net/downloads/microsoft/url-rewrite) or download it directly ( 32-bit (http://www.microsoft.com/en-us/download/details.aspx?id=5747) / 64-bit

(http://www.microsoft.com/en-us/download/details.aspx?id=7435)).

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

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

<?

xml version = "1.0" encoding = "UTF-8" ?>

<configuration>

<system.webServer>

<rewrite>

<rules>

<clear/>

<rule name="Imported Rule 0" stopProcessing="true">

<match url="^(img|css|files|js)(.*)$"></match>

<action type="Rewrite" url="app/webroot/{R:1}{R:2}" appendQueryString="false"></action>

</rule>

<rule name="Imported Rule 1" stopProcessing="true">

<match url="^(.*)$" ignoreCase="false" />

<conditions logicalGrouping="MatchAll">

<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />

<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />

</conditions>

<action type="Rewrite" url="index.php?url={R:1}" appendQueryString="true" />

</rule>

<rule name="Imported Rule 2" stopProcessing="true">

34 Chapter 2. Installation

CakePHP Cookbook Documentation, Release 2.x

<match url="^$" ignoreCase="false" />

<action type="Rewrite" url="app/webroot/" />

</rule>

<rule name="Imported Rule 3" stopProcessing="true">

<match url="(.*)" ignoreCase="false" />

<action type="Rewrite" url="app/webroot/{R:1}" />

</rule>

<rule name="Imported Rule 4" stopProcessing="true">

<match url="^(.*)$" ignoreCase="false" />

<conditions logicalGrouping="MatchAll">

<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />

<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />

</conditions>

<action type="Rewrite" url="index.php?url={R:1}" appendQueryString="true" />

</rule>

</rules>

</rewrite>

</system.webServer>

</configuration>

It is also possible to use the Import functionality in IIS’s URL Rewrite module to import rules directly from CakePHP’s .htaccess files in root, /app/, and /app/webroot/ - although some editing within IIS may be necessary to get these to work. When Importing the rules this way, IIS will automatically create your web.config file for you (in the currently selected folder within IIS).

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

I don’t / can’t use URL rewriting

If you don’t want to or can’t use URL rewriting on your webserver, refer to the

core configuration .

Fire It Up

Alright, let’s see CakePHP in action. Depending on which setup you used, you should point your browser to http://example.com/ or http://example.com/cake_install/ . At this point, you’ll be presented with CakePHP’s default home, and a message that tells you the status of your current database connection.

Congratulations! You are ready to

create your first CakePHP application .

Not working?

If you’re getting timezone related error from PHP uncomment one line in app/Config/core.php

:

/**

* Uncomment this line and correct your server timezone to fix

* any date & time related errors.

*/ date_default_timezone_set( ’UTC’ );

Fire It Up 35

CakePHP Cookbook Documentation, Release 2.x

36 Chapter 2. Installation