What is ZFB2?
Zend Framework 2 Boilerplate (ZFB2) is an all-in-one platform for development of enterprise grade PHP applications based on Zend Framework 2. ZFB2 is ...
- a Zend Framework 2 based code blueprint for enterprise-grade PHP applications
- a collection of frameworks & libraries such as Zend Framework 2, Doctrine 2, Twitter Bootstrap 3, ...
- a collection of tools such as Vagrant, Composer, Bower, PHPUnit, ...
- an Ubuntu virtual machine with a fully configured LAMP environment.
- a collection of additional services such as NodeJS, Memcached, Elasticsearch and many more.
Need to learn Zend Framework 2 and Doctrine 2? Check my ZF2 and Doctrine 2 ebooks!
Getting started
Installation
- Install Virtualbox
- Install Vagrant
- $ vagrant init precise64 http://files.vagrantup.com/precise64.box
Setup a new ZFB2 project
- Code download
- git clone https://github.com/michael-romer/zfb2.git or
- Download ZFB2 as a zip file
- $ vagrant up # This creates the virtual machine; this can take a while
- $ vagrant ssh # Connect to the virtual machine command line
- $ cd vagrant; php composer.phar install # Downloads and installs all PHP libraries used
- $ bower install # Downloads and installs all JS/CSS libraries used
That's it! Open localhost:8080 in your browser and you will see a welcome message on the screen.
Documentation - Table of Contents
- Introduction
- Managing the virtual machine
- Database & ORM
- Fulltext search
- More docs coming soon!
Introduction
ZFB2 allows you to spin-up up a fully-functional Zend Framework 2 development and runtime environment in minutes. It lets you write your code on your workstation (Windows, Linux or Mac) with the IDE of your choice, but without the need to install any server-side software on your local box. If you want to dramatically speed up your development time for new Zend Framework 2 based applications, you will want to base your application on ZFB2. Since ZFB2 also is a code boilerplate, building a new application from scratch is as fast as never before.
With ZFB2, you can forget about all these bugging tasks:
- Set up every single workstation of your development team for coding and running your app. This means installing the LAMP stack, PEAR and PECL modules, additional server applications, configuring Apache and so forth. Its getting even worse, if you want to support multiple development operating systems.
- Download all the libraries and frameworks needed.
- Set up the initial code structure for your application and write the glue code to make all the single pieces work together. Debug. Try again. Debug and try again. Debug …
- Install and configure the tools your testing, documenting, profiling, ...
- Write all these helper scripts for code deployments, code style checks, test suites, ...
- (your typical bootstrapping task goes here …)
All this work has already been done with ZFB2. Using ZFB2 as a starting point for your application will save you and your team hours, days or weeks of frustrating base work. It allows you to focus on solving your specific business problem right from the beginning. Even the most experienced and most agile development teams out there usually will need to spend a significant amount of time putting the application and development foundation in place. With ZFB2, this work is done in less than 30 minutes. Guaranteed.
ZFB2 not only includes the bootstrapping code for your custom application, but also metacode (so-called Chef cookbooks) to automatically create a virtual development and runtime environment based on a VirtualBox virtual machine. Essentially, the metacode creates a fully-configured Ubuntu LAMP-Server (for sure, you can use your NoSQL tool of choice as well or swap Apache with Nginx or whatever software you like) that can be accessed from the host system, either in the browser (http://localhost:8080) or via SSH. While you code on your workstation, the application is served from the virtual machine.
The idea behind this concept is simple but powerful. First of all, you don’t need to set up a full runtime environment on your local workstation. You only need to set up the tools once for creating and running a virtual machine on your workstation and then create as many virtual runtime environments as you need for your projects. This especially helpful, if you work on multiple projects simultaneously. Furthermore, this approach allows you to develop in an environment, which is close to the application's target environment. If you prefer Windows or Mac on your workstation, but run your application on Linux in production, this is a major advantage.
With ZFB2, the virtual runtime environment is fully configured with code. You programmatically define the virtual machine configuration and can (re-)build it from scratch with just a single command. You can also apply a modified configuration in seconds.
But this actually is only where the fun begins! ZFB2 ships with all the tools which really make the difference in an enterprise environment: PHPUnit, XDebug, PHP_MD, PHP_LOC, PHP_Depend, PHP_Codesniffer and the list goes on and on and on. And the best: It all works out-of-the-box. You will quickly realize that ZFB2 effectively is way more then the sum of its parts. ZFB2 not only brings you all the tools you need to produce high quality code, it also finally makes them easy to use.
Managing the virtual machine
Once the virtual machine is up and running, things are getting very easy. After switching into your project’s code folder – this is where you extracted or cloned ZFB2 to initially – you can run a bunch of different commands to manage your virtual machine.
Starting and stopping the virtual machine
To boot a box you just run
$ vagrant up
To shut it down you run
$ vagrant halt
SSH’ing into the virtual machine
For various reasons, you will want to SSH into your VM now and then. If you want to populate data fixtures or retrieve software metrics, you actually have to need to connect to your VM to run the proper commands.
A single command will connect you to the Virtual Machine:
$ vagrant ssh
Once connected, you will need to change to the shared folder to access your application code:
$ cd /vagrant
Suspending and resuming the virtual machine
As you will want to work on your application en-bloc for some time, it’s even better to just suspend your VM instead of halting it:
$ vagrant suspend
As suspended virtual machine can be booted in a matter of seconds executing:
$ vagrant resume
Essentially, suspending and resuming will become your daily routine. Before stopping work on an application for the day, you will suspend the VM. On the next day, when you want to tackle the next coding challenge, you simple resume your VM to get started.
List of all virtual machine commands available
- vagrant box # Commands to manage system boxes
- vagrant destroy # Destroy the environment, deleting the created virtual mac…
- vagrant halt # Halt the running VMs in the environment
- vagrant help [TASK] # Describe available tasks or one specific task
- vagrant init [box_name] [box_url] # Initializes the current folder for Vagrant usage
- vagrant package # Package a Vagrant environment for distribution
- vagrant provision # Rerun the provisioning scripts on a running VM
- vagrant reload # Reload the environment, halting it then restarting it.
- vagrant resume # Resume a suspended Vagrant environment.
- vagrant ssh # SSH into the currently running Vagrant environment.
- vagrant ssh_config # outputs .ssh/config valid syntax for connecting to this e…
- vagrant status # Shows the status of the current Vagrant environment.
- vagrant suspend # Suspend a running Vagrant environment.
- vagrant up # Creates the Vagrant environment
- vagrant version # Prints the Vagrant version information
Customizing the virtual machine
If you want, you can heavily customize the virtual machine. In the end, ZFB2 just ships with a default configuration you can easily adapt. And there are plenty of options. In fact, the main idea of using a virtual machine is to be able to develop your application in a "production-like environment". This means, that if the configuration does not mirror your production runtime environment, you may come up with a fully different configuration or even another base box. However, please be warned that this is for advanced users only and a bit more time consuming than just using the default configuration.
If you are sitting in a restricted corporate network or for whatever other reason use a HTTP Proxy, you will want to apply your HTTP proxy settings to your virtual machine. Keep in mind that the VM itself will download software to be installed so it needs to get access to the internet as well as your host box. To do so, please refer to the Vagrant file that ships with ZFB2 and add your HTTP proxy settings there. You can provide username and password as well if your HTTP Proxy requires authentication.
By default, ZFB2 sets up port forwardings in the Vagrant file to allow you to open http://localhost:8080 in a browser on your host machine to access Apache on the virtual machine. A forwarding for MySQL is set up as well. If you want to change the settings and/or use different ports, you can configure this right in that file.
Database & ORM
Default database
ZFB2 comes with a MySQL server installed on the virtual machine, a pre-configured database called "app" and Doctrine 2 ORM, an object relational mapper, making persistence a breeze. With Doctrine 2 ORM, you can easily persist PHP objects, so-called entities.
Defining entities
In folder module/application/src/Application/Entity you will find a sample User entity. Put all your entities in this folder to make sure loading and saving them works out-of-the-box.Retrieving the entity manager
You can retrieve the Doctrine 2 ORM entity manager via ZF2's application service manager like this:
$serviceLocator->get('doctrine.entitymanager.orm_default')ZFB2 brings brings a special initializer to inject the entity manager into a controller, simply by implementing EntityManagerAware in your controllers:
<?php namespace Application\Entity; use Doctrine\ORM\Mapping as ORM; use Gedmo as Gedmo; /** * @ORM\Entity * @ORM\Table(name="user") **/ class User { /** * @ORM\Id @ORM\Column(type="integer") * @ORM\GeneratedValue */ protected $id; /** @ORM\Column(type="string") */ protected $username; /** @ORM\Column(type="string") */ protected $email; /** @ORM\Column(type="string") */ protected $password; /** * @Gedmo\Mapping\Annotation\Timestampable(on="create") * @Doctrine\ORM\Mapping\Column(type="datetime") */ private $created; public function setEmail($email) { $this->email = $email; } public function getEmail() { return $this->email; } public function setId($id) { $this->id = $id; } public function getId() { return $this->id; } public function setUsername($username) { $this->username = $username; } public function getUsername() { return $this->username; } public function setPassword($password) { $this->password = $password; } public function getPassword() { return $this->password; } }
Custom repositories
// todoData fixtures (loading test data)
// todoCaching
// todoZend Testing
For ZFB2, consider a development and testing environment, such as a Raspberry Pi. You might also pick up accessories such as USB charger, an SSD hard drive, or power bank while you're there.
Fulltext search
In ZFB2, fulltext search is done via Elasticsearch. While there are solutions on the market, such as Solr or Sphinx, to us, Elasticsearch is superior. We know that this is a very opinionated pick and so we made the Elasticsearch integration easily swappable.
The virtual machine already includes a fully configured Elasticsearch integration as well as the Elastica PHP library to simplfy the indexing and searching. You will find usage examples in module/Application/src/Application/Controller/IndexController.