Skip to content

Latest commit

 

History

History
203 lines (147 loc) · 7.59 KB

02.Installation.md

File metadata and controls

203 lines (147 loc) · 7.59 KB
Raw

Installation

This documentation aims to explain all necessary steps in depth for installation.

Prerequisites

ZF2 Boilerplate utilizes several cutting-edge PHP features, so make sure that your workstation has meets the minimum requirement list below before starting:

  • Nginx (recommended) or Apache HTTP server
  • PHP >= 5.6.x with FPM
  • php-mrycpt extension for enrcyption
  • php-intl extension for i18n requirements

Firstly, go to your projects directory in your workstation, clone the boilerplate and install dependencies by issuing the following commands:

$ cd /path/to/projects
$ git clone [email protected]:edigu/zf2-boilerplate.git
$ cd zf2-boilerplate
$ php composer.phar install

Thanks to composer, all required 3rd party dependencies (including Zend Framework 2) will be automatically downloaded and installed into the vendor directory. Keep calm and grab a coffee while waiting..

Now, install Bower for javascript related package management and Grunt for automating various javascript/less related tasks.

We assumed that you have already installed Nodejs and Npm on your system. Otherwise, you MUST install Nodejs and Npm before continue.

$ npm install -g bower grunt-cli
$ bower install
$ npm install

So far, so good. At this point, node_modules and bower_components directories should be created in the project root.

Now we're ready to run grunt first time with the dev option which doesn't uglifies or minifies the javascript & css files for development purposes while compiling less:

$ grunt dev

This will create public/img, public/js, public/css and public/fonts directories with all related frontend stuff inside by following the directives in gruntfile and mainly reading from assets folder in the project root.

As you noticed, these directories also ignored via .gitignore, this means you should create all further CSS/JS/Image files inside the assets directory, not public/* one.

Managing small image assets via grunt is really subjective decision which taken after various bad experiences. You feel free to ignore this detail and apply your own solution if necessary.

System Setup

Defining an APPLICATION_ENV environment variable on the host machine which runs the application is good practice. This also required to run application without any problem via CLI.

Open the terminal and issue the commands below:

$ echo "export APPLICATION_ENV=development" >> ~/.bashrc
$ source ~/.bashrc

IMPORTANT - On production server, you should use production value instead of development. If you wish to run the application on multiple servers for testing purposes, you can use values like testing, staging etc..

Also you need to append the line below to your /etc/hosts file:

127.0.0.1 www.boilerplate.local admin.boilerplate.local api.boilerplate.local

Database Setup

  • Create a database named boilerplate. Thanks to Doctrine 2, you can use MySQL, PostgreSQL or SQLite.
  • Create a local copy of doctrine.local.php.dist file using the commands below:
$ cd /path/to/projects/boilerplate
$ cp config/autoload/doctrine.local.{php.dist,php}
  • By default, ZF2 boilerplate ships with an example PDO PostgreSQL configuration in doctrine.local.php, if you prefer switch to MySQL, just replace the driverClass to :
  • Doctrine\DBAL\Driver\PDOPgSql\Driver for PostgreSQL
  • Doctrine\DBAL\Driver\PDOMySql\Driver for MySQL
  • Doctrine\DBAL\Driver\PDOSqlite\Driver for SQLite (Note: Folder and .db file should be writable via php server.)
  • Replace the @dbuser, @dbpass and @dbname in doctrine.local.php file with yours.
  • Switch to command line back and create required tables with the help of schema-tool:
$ php public/index.php orm:schema-tool:create
  • Finally, populate them with some sample data using data fixtures:
$ php public/index.php data-fixture:import

At this point, all required tables created and populated with some sample data. Your database is ready to use. Make sure that by browsing in your favourite RDBMS GUI.

HTTP Server Setup

ZF2 Boilerplate contributors uses Nginx as HTTP server. This documentation explains required configuration for nginx however achieving same result with the Apache Http server is possible too.

Create an upstream pool named http-servers in nginx.conf file and set default charset to UTF-8 to reduce localization related headaches:

http {
    # ... leave other lines as is ...

    charset UTF-8;

    upstream http-servers {
       # Switch commented lines if your php-fpm listening TCP port.
       # server 127.0.0.1:9000;
       server unix:/tmp/php-fpm.sock;
    }
}

Leave the original nginx/fastcgi_params as is and create a custom fastcgi.conf file in the same (nginx) folder with the contents below. We'll use this custom fastcgi.conf in our server definitions for the sake of DRY principle:

location ~ .php$ {
   # Add the original fastcgi_params
   include fastcgi_params;

   fastcgi_split_path_info ^(.+.php)(/.+)$;

   fastcgi_param   SCRIPT_FILENAME     $document_root$fastcgi_script_name;

   fastcgi_param   PATH_INFO           $fastcgi_path_info;
   fastcgi_param   PATH_TRANSLATED     $document_root$fastcgi_path_info;

   # Important:
   # Change this from "development" to "production" on a REAL SERVER.
   fastcgi_param   APPLICATION_ENV     development;

   fastcgi_read_timeout  300;
   fastcgi_pass          http-servers;
   fastcgi_index         index.php;
}

Finally, define three virtual hosts in a boilerplate.conf file and save it as nginx/sites-enabled/boilerplate.conf. Contents of the virtual hosts configuration should seem like this:

# FRONTEND
server {
   listen 80;
   server_name www.boilerplate.local;

   # Redirect url's with trailing slash to non-trailing slash version
   rewrite ^/(.*)/$ /$1 permanent;

   # Modify these three paths according to your project directory structure.
   root        /path/to/boilerplate/public;
   access_log  /path/to/boilerplate/data/logs/www.access.log;
   error_log   /path/to/boilerplate/data/logs/www.error.log notice;

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

# API
server {
   listen 80;
   server_name api.boilerplate.local;

   # Redirect url's with trailing slash to non-trailing slash version
   rewrite ^/(.*)/$ /$1 permanent;

   # Modify these three paths according to your project directory structure.
   root        /path/to/boilerplate/public;
   access_log  /path/to/boilerplate/data/logs/api.access.log;
   error_log   /path/to/boilerplate/data/logs/api.error.log notice;

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

# ADMIN
server {
   listen 80;
   server_name admin.boilerplate.local;

   # Redirect url's with trailing slash to non-trailing slash version
   rewrite ^/(.*)/$ /$1 permanent;

   # Modify these three paths according to your project directory structure.
   root        /path/to/boilerplate/public;
   access_log  /path/to/boilerplate/data/logs/admin.access.log;
   error_log   /path/to/boilerplate/data/logs/admin.error.log notice;

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

Now restart the nginx and open http://www.boilerplate.local in your favourite browser.