PHP Handbook

Our aim it to pull PHP developers together to work using the same tools and the same way. We believe that ensuring that having some best-practice and basic principles in place will play a big part in both team and personal development.

Before doing anything else make yourself a cup of tea and read everythign on PHP The Right Way.

We want to work in an ecosystem that empowers developers to reach their potential--one that encourages growth and collaboration. A space that is safe for all. This is why we support The Code Manifesto.

And remember, most systems work best if they are kept simple rather than made complicated.


Introduction

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED" and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Out Standards

  1. You Should use the Laravel framework
  2. You Must comply with the company Coding Style
  3. You Should use Composer for all autoloading
  4. You Should use $snake_case for properties, variables & parameters
  5. You Must use the Clicksco namespace for all packages
  6. You Must use an appropriate namespace for your project

Team Members

The below list is a quick list of the Clicksco PHP team. Clicking on a name will take you to the official Tech Team Who's Who page on the Clickso company wiki.

Name Team Location Links
Viacheslav Epifanov (aka Slava) ClicksControl Russia
Philippe Jausions CPA / ECommerce / Click.net France
Ruslan Kazantsev ClicksControl Russia
Elliot Lings Services UK
James Mills Services Dubai
Andrew Nicholson CPA / ECommerce UK
Jon Park Services UK
Alexey Polushin ClicksControl Russia
Antonio Rohman ECommerce Spain
Dmitrii Shumkov (aka Dima) ClicksControl Russia
Evgeny Stepanov ClicksControl Russia
Paul Taylor Services UK
Rick Trotter Clicksco Labs UK
Alexander Trunov (aka Sasha) ClicksControl Russia
Usman Zafar CPA / ECommerce Dubai

Communication and collaboration are key! Don't be a hermit, talk to each other!

  • HipChat - we have rooms for all projects and use every integration possable with other services so that notifications like Exceptions and deployments are send to the project rooms.
  • Basecamp - We have a Clicksco PHP project to discuss all things PHP.
  • ScreenHero - Collaboration is key. Pair Programming is a great and encoraged.

All projects must use version control. At Clicksco we use Git.

Workflow

The workflow of choice for the PHP team at Clicksco is Github Flow.

Github Flow Overview

Github Flow is a way of working with Git that focusses on collaboration and quick releases and has been demonstrated to grow well with large teams.

The only hard rule of the system, and the main thing to remember, is that anything on the master branch is deployable. This means that it should never be broken or partially complete.

An Example Workflow

  1. Fork a descriptive branch from master
  2. Create Awesome
  3. Pull request, review and merge
  4. Deploy
  5. Rinse and repeat

Let's look at each in a little more detail...

1. Fork a Descriptive Branch from master

Everything comes from master, it's stable, safe and a representation of the current live system.

Branches should be based on a description of the new feature or work that you're doing. It makes things easy to read at a glance and, for larger teams, makes it clear as to what everyone is/has been working on.

Some examples might be:

  • landing-page-content
  • hotfix-email-notifications
  • user-authentication
  • profit-reporting

Once created, push your new branch to the remote.

2. Create awesome

Do what you do, my friend. Squash bugs, add features, make the world better one line of code at a time.

Commit to your branch locally and regularly push to your remote copy.

3. Pull request, review and merge

Once you feel like the branch is ready for deployment, open a pull request on the remote. Where applicable, tag someone in it, possibly a developer responsible for reviewing and signing off the feature.

Review the code, go back and make changes if you need to. Any further pushes to the remote branch will update the pull request/sup>. (If you need a fix that has since been merged into master, you can always merge it into your feature branch.)

Peer review and/or sign-off isn't always required. If it's a rapid fix, or you're working on your own, just up and merge it yourself. That's not to say that you won't want to run something past someone; and merge requests are a great way to do that!

When satisfied, complete the merge to master.

4. Deploy

Where possible, master should be hooked up to a Continuous Integration system like Jenkins or, more simply, Deploy or FTPloy. If this isn't feasible for your project, you can deploy as you see fit.

5. Rinse & repeat

What? You thought you were finished? GOTO 10.


.gitignore

A standard .gitignore example is shown below. Please make sure to ignore all editor/IDE settings etc.

.idea
vendor
.DS_Store
.vagrant
            

There are several tools available to help you manage your projects. The main two are Basecamp and Codebase.

Basecamp

All projects at Clicksco have a Basecamp project assigned to them. Basecamp is a great way to communicate with project leads, project managers and other developers about top-level discussions. It's the prefered method of communication.

It's good practice to manage a top level to-do list in Basecamp which is understandable and readable by everyone. You can then reference which ticket this work refrences in Codebase by adding [Ticket 44] to the title.

Codebase

The Clicksco PHP team has access to our company Codebase account. Codebase is a great place for more technical discussions within your project team. The ticketing system must be used to manage all feature requests, bugs, enhancements etc. Each project that is managed by Codebase will have it's own repository which should be kept up to date.

Codebase repositories will have an automatic secondary backup to a repository on the company BitBucket account. This is managed in the settings in Codebase.

When you make a commit you can reference tickets in your commit and when it is pushed to Codebase it will automatically update ticket status etc. Read more about this.

Codebase Quick Tips

Updating Your Ticket

[touch: ticketnumber]
e.g. [touch: 10]

Changing the Status

[statusname: ticketnumber]
e.g. [completed: 10]

For every new project a short team discussion will take place to make sure the right Framework will be implemented. The default/standard framework is currently Laravel.

As a team we understand that each project is different with different requirements which may not fit in with the standard framework of choice. We also understand that as a large team of developers as part of a international company it is sensible to have a certain about of standardisation when it comes to tools and processes. Because of this we discuss each projects requirements together before a new project is started to make sure the correct tools are used. We are open to assessing new frameworks and have an internal process for this.


A developer is open to use whichever editor they want. Every developer has access to a PHP Storm licence if they want and this is the more widely used IDE within the group.


As we don't believe in wasting time reinventing the wheel, the Clickco PHP team follow the great work by the PHP Framework Interop Group (PHP-FIG) and follow the various PSR's (PHP Standards Recommendation). A great article explaining what this is all about can be read here PSR-Huh?.

There are a number of tools to help you stick to our chosen coding standard (coding style). One of those tools is called PHP_CodeSniffer, which validates your code for consistence with PSR. You can use this tool via the command line or set PHPStorm to use this to highlight errors in the IDE as you type. Setting up PHPStorm and PHP_CodeSniffer, checkout this quick video.


Composer is a tool for dependency management in PHP. It allows you to declare the dependent libraries your project needs and it will install them in your project for you.

Every project should make use of Composer and this is the standard way of setting up autoloading in projects.


You should always do a search on Packagist and also our company package directory before you work on a new package. Before writing new functionality for your project take a step back and discuss with the team if what you are working on should be a package so we can all make use of it.

Creating a package

When creating a package we have a set of standard README etc. templates which include some required and some optional sections. This is hosted in a repository on the company BitBucket account.

Internal package directory

We have a number of packages that are located on our internal Composer Repository which is powered by Satis.

Recomended Packages

It's always worth checking out the packages that are available on The League of Extraordinary Packages.

Below we have listed a few of our favourite packages that we uses across our projects.

Name / Summary Tags
Database Backup Manager
Supports MySQL and PostgreSQL, compress with Gzip, framework-agnostic, dead simple configuration, optional integrations for MVC framework Laravel
laravel, databaase, backup, mysql, postgresql
Inverse seed generator (iSeed)
Laravel 4 package that provides a method to generate a new seed file based on data from the existing database table.
laravel, seed, generator
Faker
Faker is a PHP library that generates fake data for you
laravel, data, seed
Generators by Jeffrey Way
Fast Workflow in Laravel With Custom Generators.
laravel, seed, generators
UUID for PHP
Rhumsaa\Uuid is a PHP 5.3+ library for generating and working with RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID).
uuid, unique, identifier
API for Laravel
This is an API package for the Laravel framework. It allows you to build a flexible RESTful API that can be consumed externally and by your own application.
laravel, api
PHP OAuth 2.0 Server for Laravel
A wrapper package for the standards compliant OAuth 2.0 authorization server and resource server written in PHP by the League of Extraordinary Packages.
laravel, oauth
Dispatcher
Dispatcher allows you to schedule your artisan commands within your Laravel project, eliminating the need to touch the crontab when deploying.
laravel, cron, schedule, commands

The best way to get a local development environment setup is to use VirtualBox and vagrant.

We are working on a base box to match the companies live environments. A temporary setup can be found on our GitHub page. Another great resource is puphpet.com, a simple GUI to set up virtual machines for PHP development.

Laravel Homestead

More recently Taylor Otwell has released Homestead. It is definatly checking this out.


Continuous Integration is managed using Codeship. This is a great service which runs tests and deployments. This is our prefered method of deployment.


Our prodcution bug tracking is managed by Bugsnag. Once a bug is detected the appropriate HipChat project room will be notified and a bug ticket will automatically be created in Codebase for that project.


Every project should include DocBlocks. What is a docblock?


A few useful links can be found below:

Development

  1. Sequel Pro - fast, easy-to-use Mac database management application for working with MySQL databases.
  2. SourceTree - SourceTree is a free Mac client for Git
  3. Laravel Homestead - Laravel Homestead is an official, pre-packaged Vagrant "box" that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine.

Screencasts

  1. Laracasts - A great set of screen casts covering all things Laravel

Blogs / News

  1. Laravel News (@laravelnews) - Curated news & information about Laravel, by

Podcasts

  1. Laravel.io - A great podcast covering all sorts of Laravel goodness.
  2. PHP Town Hall - General PHP podcast. Good to pick up new things in the industry.

Books

  1. Laravel: Code Bright
  2. Laravel Testing Decoded
  3. Laravel: From Apprentice To Artisan

Copyright 2014 Clicksco. All rights reserved.