README.md.template

_This template includes more information than a typical project requires, both to provide hints on possible things to include, as well as to make the process of filling it largely a matter of deleting information that is not applicable. Specifically; **be sure to remove or replace any notes and comments in italics,** like this one. By convention, pseudo-variables you should replace are typically in ALLCAPS._


# [{{PROJECT_TITLE:@TODO}}]({{PROJECT_REPO_URL:https://github.com/loadsys/app}})

<!--
[![Build Status](https://magnum.travis-ci.com/loadsys/__REPO_NAME__.svg?token=__TRAVIS_TOKEN__&branch=dev)](https://magnum.travis-ci.com/loadsys/__REPO_NAME__)
-->

{{PROJECT_DESCRIPTION_NO_QUOTES:@TODO}}

_Brief app description. Why does it exist? Who uses it?_

* Production URL: {{PROJECT_PRODUCTION_URL:@TODO}}
* Staging URL: {{PROJECT_STAGING_URL:@TODO}}
* Project Management URL: {{PROJECT_MANAGEMENT_URL:@TODO}}
* Loadsys Project Docs: {{PROJECT_DOCUMENT_URL:@TODO}}


## Environment

_"Environment" refers to external technologies required for the app to run. Anything that the app "assumes" will be available. Memcache is part of the environment, jQuery is a library. **Always** include the minimum PHP version, PHP extensions (and versions) utilized, database software version, and any other **external** programs used. Think in particular about the production environment, even if a tool (like memcached) is not used locally in development._

### Hosting

This section documents the minimum required tools for hosting this application.

* [CakePHP](https://github.com/cakephp/cakephp) v3.1+
* PHP v5.6+
	* intl
	* pdo + mysql
	* mbstring
	* mcrypt
	* memcached
	* openssl
* Apache v2.4+
* MySQL v5+
* Memcached

(These tools are all provided in the bundled vagrant environment, described below.)


### Developer-specific

The following tools **should be installed on your development machine** in order to work with this project:

* PHP v5.4+ (Mac system default should work fine.)
* [composer](http://getcomposer.org/) for dependency management.
* [git](https://git-scm.com/)
* Either of the following:
	* [VirtualBox](https://www.virtualbox.org/) v4.3+ (free)
	* [VMware Fusion](http://www.vmware.com/products/fusion) v6+ plus the [vagrant VMware plugin](https://www.vagrantup.com/vmware) (not free, but **fast**)
* [vagrant](http://www.vagrantup.com/downloads.html) v1.6+ for dev VM hosting. The following plugins are helpful but not required:
	* [vagrant-bindfs](https://github.com/gael-ian/vagrant-bindfs)
	* [vagrant-cachier](https://github.com/fgrehm/vagrant-cachier)
	* [vagrant-vbguest](https://github.com/dotless-de/vagrant-vbguest)
* For automatically running tests:
	* [node.js](http://nodejs.org/download/)
	* [npm](https://npmjs.org/)
	* [grunt-cli](http://gruntjs.com/getting-started)

Vagrant + VirtualBox/VMware provide the following additional tools inside the VM. There are no "optional" installs. Developers must be able to run tests, generate phpDocs and run the code sniffer locally before committing. Thankfully, **the vagrant VM provides the following tools**, including:

* PHP's [xdebug extension](http://xdebug.org/) v2+
* PHP's sqlite extension (for DebugKit).
* [composer](https://getcomposer.org/)

The following tools can easily be _made_ available by uncommenting the appropriate section of the `provision/main.sh` script:

* [nodejs](http://nodejs.org/) + [npm](https://www.npmjs.org/)
	* [`json`](http://trentm.com/json/) command line tool.
	* ember-cli
	* grunt-cli


### Included Libaries and Submodules

_"Libraries" refer to packages that are directly executed or used by the app. Items that the app is able to obtain or install for itself are libraries. List any packages that are pulled in via composer, included as git submodules or directly bundled in the repo. Include links to the package's homepage or repo and the version number in use (if applicable). The list below is pre-populated with the submodules included in this CakePHP-Skeleton repo, and also lists some common add-ons._

Libraries should be included with Composer whenever possible. Git submodules should be used as a fallback, and directly bundling the code into the project repo as a last resort. The Skeleton includes the following defaults:

Composer-provided:

* [CakePHP](https://github.com/cakephp/cakephp) v3.0+
* [Bake](https://github.com/cakephp/bake)
* [DebugKit](https://github.com/cakephp/debug_kit)
* [Loadsys Cake Basic Seeds](https://github.com/loadsys/CakePHP-Basic-Seed)
* [Loadsys Cake ConfigReadShell](https://github.com/loadsys/CakePHP-ConfigReadShell)
* [Loadsys Cake LibRegistry](https://github.com/loadsys/CakePHP-LibRegistry)
* [Loadsys Cake Shell Scripts](https://github.com/loadsys/CakePHP-Shell-Scripts)
* [Migrations](https://github.com/cakephp/migrations)
* [phpunit](http://phpunit.de/) v4.1+
* [phpDocumentor](http://phpdoc.org/) v2
* [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) v2


Git submodules:

* (none)


Bundled packages:

* (none)


### cron Tasks

_Document anything that is expected to run outside of a normal web browser interface here. Include when it is supposed to run and any details about permissions, logging, etc._

```
0 0,12	* * *	/var/www/bin/cake COMMAND > /var/www/logs/COMMAND.log 2>&1
```



## Installation

_In general, document the series of steps necessary to set up the project on a new system (development or production). If there is a setup shell script, don't document its internal steps (the script itself does that), just how to run it. If setup is manual, list each step in order._


### Development (vagrant)

Developers are expected to use the vagrant environment for all local work. Using a \_AMP stack on your machine directly is no longer advised or supported. You should have everything from the [Developer Specific](#Developer-specific) section above already installed on your Mac.

```bash
git clone {{PROJECT_REPO_CLONE_URL:@TODO}} ./
./bootstrap.sh vagrant
```

The bootstrap script takes care of installing dependencies. After this process, the project should be available at [http://localhost:8080/](http://localhost:8080/).


### Staging

1. Create or provision a new web instance server (typically EC2), matching the Vagrant `box` in use (or vice-versa). This currently means **Ubuntu Server 14.04 LTS 64bit**.
	1. The box should expose **only** the following ports:
		* HTTP from Anywhere
		* 1080 TCP from Anywhere (Mailcatcher)
		* SSH from `66.228.59.201/32` (Loadsysdev)
	1. ssh into the box.
	1. Run `https://raw.githubusercontent.com/loadsys/CakePHP-Shell-Scripts/master/baremetal-bootstrap | bash -s -- {{PROJECT_REPO_HTTPS_URL:@TODO}} staging staging`


### Production

1. Create appropriate Security Groups for the gateway, app servers, cache servers and database servers.
1. Create an Elastic Load Balancer.
	* Install the site's SSL certificate.
	* Assign a Route53 domain name to it.
1. Create or provision a new Memcached/ElastiCache instance.
	* (Locally) Update the `config/app.php` with the correct credentials and commit/push them to GitHub.
1. Create or provision a new MySQL/RDS server.
	* Assign a user permissions to that database.
	* (Locally) Update the `config/app.php` with the new credentials and commit/push them to GitHub.
1. Create or provision a new web instance server (EC2), matching the Vagrant `box` in use (or vice-versa). This currently means **Ubuntu Server 14.04 LTS 64bit**.
	1. ssh into the box.
	1. Run `https://raw.githubusercontent.com/loadsys/CakePHP-Shell-Scripts/master/baremetal-bootstrap | bash -s -- {{PROJECT_REPO_HTTPS_URL:@TODO}} master master`


## Contributing

_Information a developer would need to work on the project in the "correct" way. (Tests, etc.)_


### After Pulling

Things to do after pulling updates from the remote repo.

On your host:

* `composer install` (Install any changed/updated dependencies.)
* `vagrant ssh`
	* `bin/cache-clear` (Make sure temp files are reset between host/vm use.)
	* `bin/db-backup` (Store the previous database contents before running schema/data updates.)
	* `bin/migrations` (Set up the DB with the latest schema.)
	* `bin/cake BasicSeed.basic_seed` (Populate the latest set of development data from the seeds, if the plugin is available.)


### Developer Workflow

* Pull origin and get `dev` up to date.
* Create new topic branch from `dev`.
* Make changes and commit to your branch.
* (Pull origin and get `dev` up to date.)
* Rebase branch on latest `dev`.
* Push (forced) topic branch to origin.
* Create a PR and add the "Review" label to it. Assign to the PM.
* PM will take it from there.


### Configuration

App configuration is stored in `config/app.php`. This configuration is then added to (or overwritten by) anything defined in the environment-specific config file, such as `config/app-vagrant.php` or `config/app-staging.php`.

The bundled vagrant VM automatically sets `APP_ENV=vagrant` both on the command line (via `vagrant ssh` and in the Apache context via `SetEnv`.) If you want to work with the project on your host machine locally, you need to `export APP_ENV=dev` (or whatever environment you want to match for `config/app-*.php`) before running `bin/cake`.


### Database Changes

The app assumes that every table will have the following fields by default. These fields are handled by the TimestampBehavior and the CreatorModifierBehavior, which are engaged via a custom [App]Table class automatically. See `src/Model/Table/Table.php` for details.

```sql
  `id` char(36) NOT NULL COMMENT 'UUID primary key.', -- First field in table.

  -- Foreign keys next.

  -- All other fields here.

  -- Last 4 fields in table:
  `created`     datetime DEFAULT NULL COMMENT 'Creation datetime.',
  `creator_id`  char(36) DEFAULT NULL COMMENT 'User.id that created the record.',
  `modified`    datetime DEFAULT NULL COMMENT 'Last modification datetime.',
  `modifier_id` char(36) DEFAULT NULL COMMENT 'User.id that last modified the record.'
```

#### Connecting to MySQL

Because the development MySQL DB runs inside of the vagrant VM, you must connect to it via SSH. The easiest way to do this is using [Sequel Pro](http://sequelpro.com/).

Create a new "SSH" connection with the following settings:

* Name: vagrant@vagrant
* MySQL Host: 127.0.0.1 (This is the MySQL server's address after you've SSHed into the vagrant box.)
* Username: vagrant
* Password: vagrant (as defined in `provision/vagrant.sql`.)
* Database: vagrant (again per `provision/vagrant.sql`.)
* Port: 3306
* SSH Host: 127.0.0.1
* SSH User: vagrant
* SSH Password: vagrant (Or [someone online](https://coderwall.com/p/yzwqvg) say you can point to your local `~/.vagrant.d/insecureprivatekey`.)
* SSH Port: 2222 (per `config/provision.yaml`.)

This setup is handy for backing up your data if you're about to destroy the box, or for making Schema or Seed changes before running the Shell commands in the VM.


#### Schema Migrations

* The database schema is maintained using the Migrations plugin.
* Use the BakeShell to generate a new Migration. For example:
	`bin/cake bake migration CreatePosts id:uuid:primary title:string body:text created modified`
* Modify the generated migration file to add table and column comments, limits, etc.
* Run `bin/phpunit tests/TestCase/Migrations/MigrationsTest.php` to validate the migration file.
* Review and commit the new Migration file.


#### Sample Data

* Both test data and started production data is maintained by the Loadsys Basic Seeds plugin.
* The default seed files are environment aware, making it possible to run the same command regardless of environment.
* To populate (or reset) your local dev data back to the contents of the seed:
	* `bin/cake BasicSeed.basic_seed`
* There is not currently any way to automatically generate seed data-- it must be entered into the related files (`config/seed.php` for production, `config/seed_staging.php` and `config/seed_vagrant.php` for development) by hand.
* It's possible for the seeds to refer to each other. In the default setup, staging and vagrant envs load **both** the production data, and the vagrant data.
* :warning: Seeds are capable of `TRUNCATE`ing data during their execution-- be careful to have backups of any data you want to keep by using `bin/db-backup`.


### Email Debugging

The VM comes with Mailcatcher pre-installed and port-forwarded. The stock `config/app-vagrant.php` config file is set up to route email to Mailcatcher automatically.

* ClassName: `Smtp`
* Host: `127.0.0.1`
* Port: `1025`
* Username: `null`
* Password: `null`
* Client: `null`
* TLS: `null`

* Web Interface: http://192.168.8.42:1080 (the vagrant VM's local IP, or port-forwarded: http://localhost:1080/ )


### PHP Unit Testing

A project-wide phpunit configuration file is provided as `phpunit.xml.dist`. Changes to this file will be used during Travis testing and should be considered the "baseline" for the app. Developers may create a local `phpunit.xml` file which will be ignored by the repo if they wish to use or test more precise local configs.

Unit tests should be created for all new code written in the following categories:

* Model methods
* Behaviors
* Controller actions
* AppController methods
* Components
* Helper methods
* Shells and Tasks
* Libraries in `Lib/'
* Javascript in `webroot/js/`
* **Bundled** plugins


The full testsuite is run using `bin/phpunit` from the root of the project.

There are three testsuites setup as part of the phpunit.xml.dist file.

* `bin/phpunit --testsuite app` - The default testsuite, runs all tests available for the application. Equivalent to `./bin/phpunit`.
* `bin/phpunit --testsuite unit` - Runs all tests excluding the `./tests/TestCase/Controller` path.
* `bin/phpunit --testsuite integration` - Runs only the tests in the `./tests/TestCase/Controller` path.


### Javascript Unit Testing

**@TODO: Review and update this section.**

* Tests can also be written for the browser JavaScript code.
* Javascript should be written in individual "class" files (they will be merged by asset compilation) in `webroot/js/src/`.
* Anything you would normally put in a `document.ready(...)` call should be placed in @TODO.
* Matching test files should be created in `webroot/js/test/`.


### CSS Changes

* CSS is managed via Standard CSS files in the webroot directory


### Command Line Scripts

Any command line scripts written to support **this project specifically** should be placed in the `/scripts` root-level folder. Composer dependencies and the `cake` executables will continue to live in `/bin`. For more details, see loadsys/CakePHP-Skeleton#130.


## Immersion

**@TODO: Review and update this section.**

_This section may make more sense to include with the "Project" documentation instead of the "repo" README..._

New devs should all run through these steps to get familiar with the app and the features available.


## License

Copyright (c) 2015 {{PROJECT_CLIENT_NAME:@TODO}}