App Template

(Modified for Dokku compatibility)

An empty CakePHP project for use with composer

Requirements

PHP 5.4 and above.

Installation

composer create-project -sdev --repository-url=http://thegallagher.github.io/composer-repository thegallagher/cakephp-app-template-dokku

This will create a new project, with dependencies, based on this repository. Be sure to point the webserver at the webroot folder and ensure that URL rewriting is configured correctly.

Sane-default Configuration

By default, the following has been enabled:

Composer Autoloading
Setting Timezone to UTC
Setting database connection encoding to utf8

You may change any of these at your leisure.

Application Configuration

This template is setup to configure the application via environment variables and data source names (DSN).

What is an Environment variable?

Defining configuration settings via environment variables allows clear separation between the code, and the config it is running. To remove any complexity, this repository includes josegonzalez/php-dotenv, which automatically configures the environment if it's not already defined.

What is a DSN?

A DSN is a string which defines how to connect to a service. Since it's a string, it's portable, not language or implementation dependent and anything capable of parsing it can know how to connect to the service it points at.

OK but why use Env variables and DSNs?

Using environment variables makes it very easy to separate install-specific config settings from the code itself; and possible to change the application config without modifying the source files. There is only one file containing install-specific settings in the template and that file is only used at all if the environment isn't already configured.

The intention is that in a production system the environment is configured not an application - and the application just reads that information.

Ok I'm sold, how do I use this?

In a development scenario, copy the file Config/.env.default to Config/.env and edit it.

In a production scenario - configure the environment however you wish (via webserver config for example) and remove the use of php-dotenv.

In neither case is it necessary/desirable to modify any php files to configure the application temporarily or permanetly.

Yeah.. that's not for me.

If you don't want to use Env variables and DSNs - change it =).

Use a standard database.php file
Use a standard email.php file
Define debug to an integer not an env variable
Remove the php-dotenv loading logic
It's also recommended to remove database.php (and core.php and email.php) from the repository as they need to be modified on each install

Dokku Compatibility

Your Dokku server will need to be setup with the user-env-compile plugin.

Deploy your app with:

git remote add dokku dokku@<domain.name>:<app_name>
git push dokku master

Configure security:

dokku config:set <app_name> SECURITY_SALT=<SOME_ALPHANUMERIC_SALT_HERE>
dokku config:set <app_name> SECURITY_CIPHER_SEED=<SOME_NUMERIC_SEED_HERE>

You will probably want MySQL too. Get this MySQL plugin. To install:

cd /var/lib/dokku/plugins
git clone https://github.com/victorgama/dokku-mysql-plugin mysql
dokku plugins-install

Then create a database for your app:

dokku mysql:create <app_name>

Due to the way the plugin added the DATABASE_URL config, you will need to change the value slightly:

dokku config:get <app_name> DATABASE_URL
# > mysql2://admin:password@1.1.1.1:3306/db
dokku config:set <app_name> DATABASE_URL=mysql://admin:password@1.1.1.1:3306/db # Change 'mysql2' to 'mysql'

Note about dependencies

FriendsOfCake encourages the use of composer and it's best not to mix composer with git submodules for dependency management. If you need to use submodules you might notice /vendor and /Plugin folders are ignored by git. Composer creates those directories when installing vendors and plugins.

There a few ways to solve this:

edit the .gitignore file
use the -f param with git add Plugin/SomePlugin -f
use app/Plugin and app/Vendor for your submodules.

Included packages

The application template comes with some dependancies already included in the composer file. These are designed to help you get up and running quickly.

To find out how to make the most of these packages, please read their respective readme files.

thegallagher / cakephp-app-template-dokku