Continuing from the previous post Developing a Command Bus in PHP , we will look into how to get started in setting up our composer library project. Although my PHP software development workflow does vary slightly from project to project, most steps are more or less the same. Whether your project is the result of a successful proposal or you want to build an open source composer package like we're doing here, this post will guide you in working with PHP the right way. If you are learning PHP from scratch and find that I am missing some intermediary steps or making assumptions, please feel welcome to comment below and I'll be more than happy to explain in more detail.

How to get started on a new PHP project

First things first, let's get organised.

As with every project, we obviously have some sort of list of features or requirements. Instead of having to remember a bunch of things and having a number of resources spread everywhere; in emails, message threads, Skype conversations and numerous attachments, I start by putting everything related to the project in one place. I use the Kanban board on GitHub.com to list everything that I know needs doing. This way I don't have to remember anything and I can find everything that I need in one place, including conversing with the project stakeholders.

Throughout the years, I have been part of Scrum, Kanban and ScrumBan teams, when given a choice, I prefer to adopt a Kanban methodology to my projects because it fits better with my remote teams. This is even truer when working on Open Source projects where contributors come and go over time which makes time-boxed Sprints impossible. Also, I find Kanban to fit perfectly with my Continuous Integration strategies.

So, I head to over GitHub and create a new repository were both the code and the Kanban project will be hosted. However, because I want to allow for any developer to be able to contribute to this library and to keep things even more organised, I will create the repository under an organisation "SwellPhp" so that I can then fork it from my personal account and thus I'll be a code contributor as everyone else involved. I find this process better when reviewing code and approving pull requests without risking conflicts with my own contributions.

This process is straight forward; from GitHub, I click on the "SwellPhp" organisation and then click the "New" button, and enter the repository name to match the project's name, in this case "admiral". In the same screen I enter a brief description for the repository and since I'm here, I also add the initial Readme, .gitignore and License files. Since this is an open source project, I'll obviously make it publicly available and choose an appropriate license. In this case I chose the "MIT" licence so that everyone can use the code as they like as long as they provide an attribution to the author. I also selected the "Composer" pre-configured .gitignore file.

Create repository screen Repository created

Now I want to create my project so that I have access to the Kanban board. This is simple, just give the Kanban board a name and a description. I also use the "Automated Kanban" template so my cards, issues and pull-requests are automatically transitioned in between columns during certain events.

Once I have a Kanban board, I immediately create cards for each task that I'm aware about. This should be kept simple and not much detail is needed as this initial purpose is similar to a "brain dump list" and I'll break down each card into smaller units of work once I start working on the specific card. Basically, all I do at this stage is create a card for each feature that I know about and then add more cards as tasks come up throughout the project.

The Admiral project is quite simple as reflected on the Kanban board.

Kanban board

I simply created a card for each task I know off at this time. Now I can actually start working 😊

Work station and initial set up

As with every task, I start by moving the current card from the "To Do" column to the "In Progress" one. I also convert the current card into an issue so that it has an identifier which I'll match with the repository branch name once I start submitting code as I'll explain shortly. So, I moved the first card named "Project Setup" to the "In Progress" column and converted it to an issue. The next step is to add some beautiful tick boxes with broken down tasks so that I don't forget anything but mainly so that this issue is fully planned in advance and I can just get on with it.

I also created a new milestone named "Release of version 1.0" and some additional issue labels to categorise my tasks appropriately.

First issue

As you can see in the above screenshot, we have a broken down list of all the steps required in getting set up so we can now go ahead and move on to the next "sub" task of installing and launching a vagrant box.

As I do with most PHP projects, I use the Homestead vagrant box provided by Taylor Otwell, the creator of Laravel. I'm assuming that you'll have all of Homestead's dependencies installed already, including composer on your host machine but if you don't, you can follow the instructions on the Homestead documentation or you can ask me for more detailed instructions in the comments section below. Also note that I work on a Windows 10 workstation so the commands on the host machine will vary for Mac users. However, I'm using Git Bash so I have access to the standard unix commands.

$ mkdir -p ~/Code/swellphp/admiral $ cd ~/Code/swellphp/admiral $ composer require laravel/homestead --dev $ vendor/bin/homestead make

Since this project does not require an http server or a database, I will comment those lines out from the Homestead.yaml file and then launch the box.

ip : 192.168.22.12 memory : 2048 cpus : 1 provider : virtualbox authorize : ~/.ssh/id_rsa.pub keys : - ~/.ssh/id_rsa folders : - map : 'C:\Users\Keith\Code\swellphp\admiral' to : /home/vagrant/code name : admiral hostname : admiral

$ vagrant up $ vagrant ssh $ cd code

Setting up Git

Now I want to fork the swellphp/admiral repository so that I don't work directly on the official code base. I simply navigate to the swellphp/admiral repository page on GitHub and click the fork button, select my account and voila, I have the forked repository under keithmifsud/admiral .

I now need to add both the main repository and the fork to my local git. The official repository will be named as "upstream" whilst the fork will be "origin". I also configure git's author so that the commits are linked to me on GitHub

$ git init $ git remote add upstream git@github.com:swellphp/admiral.git $ git remote add origin git@github.com:keithmifsud/admiral.git $ git pull upstream master $ git config --global --edit Ctrl+x Y $ git add . $ git commit -m "GH-1 Initial commit"

With the first commit out of the way I set up my local branches by first checking out a new "develop" branch which will hold my local changes, then I checkout my first feature branch which I name the same as the issue key on GitHub, in this case "GH-1". Using feature branches and naming them the same as the issue at hand keeps everything organised and also GitHub will mention the commits on the issue page making it easier for future reference. Further to this, the feature branching model enforces us to segregate all responsibilities in the code itself.

$ git checkout -b develop $ git checkout -b GH-1

Next, I like to take care of protecting my upstream master branch and forcing contributors to request to merge their contributions, including myself. This is quite straight forward to do. From the swellphp/admiral repository, I navigate to settings, then in branches, under protected branches I select the master branch and at the very least select "Protect this branch" and "Include administrators". What this does is forces any pull requests to be reviewed before merging into the master branch of the upstream repository. It also protects the branch from being deleted.

Setting up the IDE

Ok, so we have a vagrant box running, we have git setup locally and remotely, what's next? Setting up the IDE! I use (and you should as well) PhpStorm. My PhpStorm is very well configured already but I still have to do a few things on every project. First and foremost, I add the project to the IDE ... obviously! 😊

Then I rename the project, in our case, "SwellPhp Admiral". This is because I have my DocBlocks configured to automatically retrieve the project's name from PhpStorm and PhpStorm defaults the project name to name of the directory which is all in lowercase and we don't like that, do we? 😊

An important setting in PhpStorm is to configure the Php interpreter so that it uses the one from our vagrant box. I consider this setting very important, especially now, with all the differences in PHP versions. PhpStorm will tell you if for example you use features only available in Php7.1 when your interpreter is set to Php 7.0.