When speaking of modern development nowadays, we can hear words like DevOps and as part of that, Continuous Integration (if you never heard about it, you can read more about it here). Anyways, today I am going to show you how to set up a build definition for a PHP project stored in Visual Studio Team Services and then the publication to an Azure Web App or a physical server.
So far so good, right? Assuming you have a VSTS workspace created and already have some code in there (if not, head here and sign up for one!), let’s take a look at how to set this up, step by step:
The core part of the build process itself is a build agent. Visual Studio Team Services offers a hosted build agent which can do the job for Node.js, ASP.NET and many other projects, however it doesn’t contain Composer or PHP runtime (but it contains a lot of other cool tools), so we will have to go and create our own (and it isn’t as hard as it sounds!).
Build Agent is practically a virtual machine (or a physical build machine) which receives the build task and processes the pipeline you define in the build definition.
Update (08AUG2018): After revisiting this article, I would like to add that it is now possible to use the hosted pipelines for building PHP as well thanks to the Docker integration. Simply pick or build your own PHP image which contains all the necessary things (PHP vX.X, Composer, NPM, Gulp, Grunt, etc.) and then just use it to build and publish the artifacts.
Okay, virtual machine, which OS to choose?
You would be usually choosing the OS type based on the environment where the application will be running. For Azure Web Apps or Windows machine, you will want to use Windows build agent, and for target environment with Linux or App Service on Linux you will want to do this on Linux. Just for explanation, I believe this is the best practice because when using for example Node.js packages, some of the native packages must be compiled and you just cannot take a native package built for Linux and run it on Windows. Also, and this is probably more important, when running unit tests, you want to run them in the same setup environment as production.
Protip: Also if you are going to use Azure Virtual Machines for your build agent, you will appreciate the ability to use Startup and Shutdown policies with Dev/Test labs to save a money when using a monster build agent (with setup where you use periodic builds). Additionally, you could make use of Azure Functions and set it up so the virtual machine with build agent starts when you commit to a repo and then triggers the build task after starting.
Setting it up
So in my case, I will be deploying my application to a Windows-based hosting (of course it is Azure App Service, but I will also show other options). So I need to setup Windows Server. I chose a VM in Azure, but it could be just anywhere, even on my PC in Hyper-V. To create a machine in Azure, you can find the tutorial here – I chose Windows Server 2016, just for the sake that I didn’t get to play with it much.
Once my VM is up and running, you need to connect to it through the Remote Desktop and start setting up the environment:
- You may want to install PHP runtime in first place. You can achieve that using Web Platform Installer or just by downloading the binaries (or compiling your own if you are hardcore enough) and adding the folder into your PATH. I chose to install PHP 7.0 (the latest stable available atm).
- Next thing you are definitely going to need is Composer. You can install it from the command line or using an installer for Windows which sets it up for you. Make sure it is available from the command line.
- If you need to run tests on your code, you should also install for example PHPUnit, it has an easy installation tutorial.
- You also need to have Node.js runtime installed. This is because of two reasons: if you ever need NPM or run some Tasks for your code, it will come in handy and secondly because the VSTS build tasks are written in Node.js (cool, right?).
- If you plan to deploy into Azure Web Apps, installing Web Deploy might come in handy.
- The last step would be to setup the build agent connection. Microsoft’s docs have a great tutorial on how to do this on Windows, Linux and Mac.
Upon successful configuration, the agent will appear in the Agent pools section of VSTS like so:
Since the VSTS agent doesn’t automatically detect PHP and Composer, it is also useful to add it into capabilities, so if you have multiple build agents, in a pool, it will be easier to run the build task only on a pool of agents which have PHP and Composer or PHP7 etc.
So now we have the build agent setup, lets move onto creating the Build Definition.
VSTS is automatically going to automatically create a temporary project folder, where the code is going to be pulled (and do it on every build), so the first thing we need to do is to get the packages from Composer.
Since there is no such thing predefined in the default steps or the marketplace, we will need to create our own script. On Windows, I really like PowerShell, so I created a new PowerShell step:
And then add the code to be executed. Make sure it is set as Inline Script, which will allow you to write it directly in the build step. The contents of the script will be like so:
# You can write your powershell scripts inline here.
# You can also pass predefined and custom variables to this scripts using arguments
Next, you need to tweak the script settings a bit – since Composer seems to be sending debug messages to stderr (for example #4034) and it seems to be expected behavior, you have to uncheck Fail on standard error option in the Advanced section, else your build will constantly fail. No worries, if an actual error happens, like a package fails to download, the build task will fail, because Composer will exit with an error code.
Now the project will contain the packages from Composer, we could do similar for fetching NPM packages or running Grunt tasks with the difference that these tasks are already created and you don’t have to execute them manually.
Next up, running tests.
Once again, PHPUnit doesn’t have predefined tasks either, so we have to manually execute it using command line. I actually discovered few issues with PHPUnit’s test results, but I will explain it throughout this part.
Anyways, once again we need to create a new command line task which will be an inline script. I will paste the contents below and explain it afterwards:
$XslPatht = New-Object System.Xml.Xsl.XslCompiledTransform
Write-Host $_.Exception -ForegroundColor Red
Alrighty, so first off we simply run phpunit command. For it to run successfully, you need to have a phpunit.xml definition existing in the project root. Example of such definition would be:
<?xml version="1.0" encoding="UTF-8"?>
<log type="junit" target="Test/Logs/junit.xml"/>
This is going to tell PHPUnit to run all tests within Test directory and store the results into JUnit compatible xml file. However as it turns out, PHPUnit’s JUnit compatible file isn’t really JUnit compatible (funny, right?). Hence the second part of the PowerShell script, which transforms the PHPUnit generated XML into JUnit compatible XML (you can read more about it here or here). In order to transform the PHPUnit file we need to create an XSL Transform file with following contents:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:copy-of select="." />
I chose to store it into Test folder under phpunit2junit.xsl name.
Once this is set up, all you have to do is to create a Task which will collect and upload the test results to VSTS. From the task selection we add Publish Test Results task (can be found under Test category). And we configure it for the JUnit test format and give it the path of where the file will be stored (in my case it was Test\Logs\junit-fixed.xml).
Now we have the PHPUnit configured and test results are going to show up in VSTS with each build. Thanks to it, we could also choose to automatically create bugs whenever a test fails and so on.
The last part is to publish the project. In this case, we are going to publish the artifacts to VSTS first and then publish the project to our server.
This step is optional, what it does is that it takes the built project and publishes it to VSTS or some sort of share. You would for example configure this so your built project is available from the VSTS to QA team who may want to deploy it manually or so. You would also use these to store some extra logs, screenshots or any other files in general.
Publishing to Azure Web App
In order to publish the project into App Service, all you have to do is to add the build task called Deploy AzureRM App Service, connect it to your Azure Subscription, choose the website to deploy to, optionally a deployment slot and you are good to go!
So now we have setup a basic DevOps cycle with deployment to Azure Web Apps using VSTS, ain’t it cool? Additionally, you could just choose to deploy the application to an IIS enabled server like a VM or an on-prem one, or deploy your project on a Linux server using SSH file copy! The great thing is that these build tasks are already ready for you!
Another practical use could be building WordPress plugins. Especially the packaging and publishing part can be pain in some cases – like when using Composer packages in your plugin. Eventually, the entire Subversion part of publishing could be just hidden into one of the build tasks.
VSTS vs. App Service custom deployment
You might have heard that Azure App Service already supports customizable deployment by using your own deployment scripts, which are also really powerful and do the job for very simple applications (even the Composer extension leverages it). But say, you need to run the unit tests or you would like to use Composer with App Service on Linux – VSTS is your best friend. And thanks to the ability to have a custom build agent, you can chain any tool into the build process.
I am actually thinking about making an extension for Composer into the VSTS Marketplace which would remove the need of creating a custom build agent (at least for Windows).