OriginalBrownbear

How to Use Docker Containers for Builds

Sat, 20 Feb 2016 00:00:00 +0100

Docker Containers and Builds

The one thing, that you simply cannot go without when running builds, is 100% stability in the build environment. Docker is the obvious tool choice for achieving this in 2016. A few crucial things should be kept in mind when setting these things up though.

Avoid Host-Volumes

Host-Volumes, that is volumes created by mounting a host path into the container are your natural enemy when trying to achieve stability and portability for your build. They introduce the host environment into the container and this is not a theoretical issue at all! Just look at this recent question about running your MySQL database from a host volume and the hoops, I had to advise the author to go through, to make it work. Another classic issue arising from using host volumes is that the container will often run as the root user or at least a different user than your currently logged in user. This means that files created by the container, that you may want to retrieve from the volume later, will belong to root and will have to get their owner changed before you do anything else with them. Again, this requires actions on the host, impeding portability and hence long term stability of the build (reinstalling the host machine, switching cloud provider … you name it!).

The worst part though is, that using host volumes will not work with remote Docker hosts. Only if the machine you’re starting the build from is also running the Docker daemon, will you be able to use host volumes. Otherwise your build steps will need to include explicitly uploading the necessary files to the host before starting the container. Often times cloud providers of Docker daemons like Amazon ECS will not even offer this option.

Lock in Version Numbers

This next point I cannot stress enough. When setting up build environments people often add things like:

RUN apt-get install ruby

into their Dockerfile and it works just fine for them, … until it stops working. Adding a statement like the above to the Dockerfile tells Docker (technically apt in this case …) to install the latest Ruby version available for the Linux distribution used. Especially in the Ruby world this will lead to issues quickly in many cases, as a result of Ruby seemingly often favoring innovation over backwards compatibility. Eventually the ruby version installed by this might jump from 1.8.x to 1.9.x and all of a sudden your build will inexplicably break. This case might be somewhat easy to debug, but let me give you an example of how bad it can get:

A while back I created a build environment for running Selenium based tests against a very complex setup of multiple web applications. It took a while to set things up, but eventually 4 web server containers where being tested in the craziest spots imaginable, still the build was stable over hundreds of runs and me and the client were happy. What I did was specify installing the latest Selenium version to be installed instead of properly locking in the version. A few weeks later the client made some design changes to one of his sites and asked me to adjust the tests after his developers failed to do so and now one test case was failing erroneously. So I rebuild the setup from the Dockerfiles on my Laptop that I had previously deleted it from already to save some disk space and started working on it. To my surprise not only one, but more than half of the tests were failing right off the bat. At first I thought, maybe the client had recently broken something in the development versions of his apps, so I reverted to versions I knew to have passed the tests before. But no change, the same tests still kept breaking. I went at it debugging things, making some adjustments to the Dockerfiles, adjusting the tests, still I could not find the reason for things to have broken in the first place. The errors I saw indicated Selenium clicking the wrong elements where it had previously clicked the right ones thousands if not millions of times. Eventually I got a little tired of my laptop building Docker images a lot slower than the EC2 instance I developed this on initially, so I moved to working on that again. To my surprise tests instantly started passing again on the EC2 instance and then it hit me, the EC2 instance still had the old images. Something in the versions must have changed … I quickly found out Selenium had made a change breaking backward compatibility when it came to hovering elements, I locked in the version using the known to work Selenium version in the Dockerfile and things started working fine on my laptop too.

The moral of the story: Not locking in versions means having to troubleshoot tests and production code simultaneously. You should be able to trust your tests, the easiest way to achieve this is to simply make the build 100% deterministically. Lock in the version of you base Docker image, lock in the versions for everything you put into it and you’ll be fine. Whenever your tests break, you know it’s the code now thanks to your tests being stable and frozen in time.

A Clean Build has Two Or Four Steps

Build Image

The first step of a clean build should simply be sending a build context to the Docker daemon. You can send a tarball compressed by various methods of choice and the daemon will extract it’s contents and build the image. When deciding on how to setup your images you should try your best to keep things homogeneous in terms of paths across your projects to avoid headache with documentation and configuration. An example of how to do this can be found in this skeleton I created for a former employer. You can see a few folders each holding the build context for one container. All of which who require a default command different from their base image simply get this in the form of a run.sh bash script, that is then always added to the final image in the exact same way and at the end of the build via this snippet:

COPY run.sh /run.sh
RUN chmod +x /run.sh
CMD ["/bin/bash", "-lc", "/run.sh"]

Also you should ensure that if your run.sh produces any output, say a .jar, coverage reports or compiled documentation is saved to a specific folder. My suggestion would be /out. Read on to find out why :)

From the commandline building your container now simply becomes:

$ docker build -t username/tagname /path/to/build/context

Run Command

The next step is to run the container we just built. In the commandline this simply turns into running for the case of you only requiring the stdOut by run.sh:

$ docker run --rm -t username/tagname

You May Need More than StdOut!

Oftentimes just getting StdOut means that you get the exit status of your build and it’s direct console output, say the list of failed and passed tests. But what about that nice code coverage html report for example ? Files you will need to retrieve from the container after it exited. Also in this case you cannot use the --rm flag on the container run, given you don’t want to remove but access it once it has stopped.

So our run command in bash would come out to just:

$ docker run -t username/tagname

Also, let’s give the container a name so it’s easier to track the individual container once it stopped and we still want to access it:

$ docker run -t --name container_name username/tagname

Optional: Download Files

Downloading files from a container using the CLI is almost as easy as copying files in a shell using the docker cp command. Assuming whatever your previously created run.sh produced as output went to the /out folder in the container, you can now simply download the contents of it via:

$ docker cp container_name:/out /local/target/path/

Optional: Delete Container

Once you got your build result from the container, all you need to do is delete it. Otherwise it’s file system will still be kept on the Docker daemon host and quickly eat up its disk space. In the commandline you can simply do this by running:

$ docker rm -v container_name

the -v flag should not be forgotten here, since many base images your build could depend on have VOLUME statements in their Dockerfile. If you fail to explicitly delete any volumes that may have been created by these containers, you’ll create dangling volumes eating up disk space and being hard to remove.

Privileged Docker Containers

Mon, 15 Feb 2016 00:00:00 +0100

That –privileged Flag Looks Pretty Practical

Quite some time ago Docker in September 2013/Docker 0.6 announced proudly, that it is now possible to run Docker from within Docker. This was made possible by the new –privileged flag feature. An explanation, I posted as a Stackoverflow answer, on how you can do this you can find here. This feature allowed bypassing a prior constraint of using containers, they were unable to access the host system’s devices. A possible use case for this, aside from running Docker inside Docker, was allowing you to trivially use things like your web-cam and such from within Docker.

Devices and Standard Containers (Safe and Secure)

You can get a quick idea of the degree of containerization for a standard container by just running a standard Debian container bash and checking the visible hard disks and devices.

Just open a standard bash shell:

$ run -it debian:jessie /bin/bash -l
root@e4746be1718c:/#

Then check what devices are hard drives to you in there. On my trusty old Linux laptop I see something like this:

root@e4746be1718c:/# df -h
Filesystem                                                                                        Size  Used Avail Use% Mounted on
/dev/mapper/docker-8:1-28836281-7f45eabc67f92f0e056275f099a943bcf104c0b915e95b96fd31ba9144327b5c   99G  197M   94G   1% /
tmpfs                                                                                             7.7G     0  7.7G   0% /dev
tmpfs                                                                                             7.7G     0  7.7G   0% /sys/fs/cgroup
/dev/sda1                                                                                         440G  364G   54G  88% /etc/hosts
shm                                                                                                64M     0   64M   0% /dev/shm

So even the standard container is able to see my hard drive on /dev/sda1 apparently. If I check the contents of /dev though, this is what I get:

root@e4746be1718c:/# ls /dev
console  fd  full  fuse  kcore	mqueue	null  ptmx  pts  random  shm  stderr  stdin  stdout  tty  urandom  zero

The hard-drive at /dev/sda1 is not there, which in almost all conceivable use cases for Docker, is a very good and important thing, you’ll see!

Devices and Privileged Containers ( You’re running something as root, you better know what you’re doing! )

So let’s move on to the privileged case. In all of this please remember, the Docker daemon always runs as root! As pointed out in this Github ticket for the Docker project, there is no way around that! Even if you can run Docker commands as non-root, the daemon is always running as root and that’s what matters here! You simply cannot set the daemon to run as a non-root process for technological reasons. So lets see what we allow the privileged container, running from a process owned by root, to see and do on our host system.

Again open a standard bash shell, but this time run it in a privileged container:

$ run -it --privileged debian:jessie /bin/bash -l
root@8f766733df83:/#

So far so good, so lets see what we get for our hard drives this time around:

root@8f766733df83:/# df -h
Filesystem                                                                                        Size  Used Avail Use% Mounted on
/dev/mapper/docker-8:1-28836281-59c1349e06bfd1b6939dfa667e0203cacaf1466eaf50c56001d767028326504e   99G  197M   94G   1% /
tmpfs                                                                                             7.7G     0  7.7G   0% /dev
tmpfs                                                                                             7.7G     0  7.7G   0% /sys/fs/cgroup
/dev/sda1                                                                                         440G  364G   54G  88% /etc/hosts
shm                                                                                                64M     0   64M   0% /dev/shm

No changes here, but lets look at what devices we have available now:

root@8f766733df83:/# ls /dev
  autofs		 dm-6	  kvm		mem		    rfkill    stdout  tty2   tty32  tty45  tty58  uhid	      vcs7	   watchdog
  bsg		 dm-7	  loop-control	memory_bandwidth    rtc0      tty     tty20  tty33  tty46  tty59  uinput      vcsa	   watchdog0
  btrfs-control	 dm-8	  loop0		mqueue		    sda       tty0    tty21  tty34  tty47  tty6   urandom     vcsa1	   zero
  bus		 dri	  loop1		ndctl0		    sda1      tty1    tty22  tty35  tty48  tty60  vboxdrv     vcsa2
  console		 fb0	  loop2		net		    sda2      tty10   tty23  tty36  tty49  tty61  vboxdrvu    vcsa3
  cpu		 fd	  loop3		network_latency     sda5      tty11   tty24  tty37  tty5   tty62  vboxnetctl  vcsa4
  cpu_dma_latency  full	  loop4		network_throughput  sg0       tty12   tty25  tty38  tty50  tty63  vboxusb     vcsa5
  cuse		 fuse	  loop5		null		    sg1       tty13   tty26  tty39  tty51  tty7   vcs	      vcsa6
  dm-0		 hidraw0  loop6		port		    shm       tty14   tty27  tty4   tty52  tty8   vcs1	      vcsa7
  dm-1		 hidraw1  loop7		ppp		    snapshot  tty15   tty28  tty40  tty53  tty9   vcs2	      vfio
  dm-2		 hpet	  mapper	psaux		    snd       tty16   tty29  tty41  tty54  ttyS0  vcs3	      vga_arbiter
  dm-3		 input	  mcelog	ptmx		    sr0       tty17   tty3   tty42  tty55  ttyS1  vcs4	      vhci
  dm-4		 kcore	  media0	pts		    stderr    tty18   tty30  tty43  tty56  ttyS2  vcs5	      vhost-net
  dm-5		 kmsg	  mei0		random		    stdin     tty19   tty31  tty44  tty57  ttyS3  vcs6	      video0

Bam, that looks a little different from before doesn’t it ? Now our hard drive isn’t only there in name. We can actually access the device! This means, we should be able to mount it inside the container. Lets try it:

root@8f766733df83:/# mkdir /mountedhd
root@8f766733df83:/# mount /dev/sda1 /mountedhd/

And …

root@8f766733df83:~# ls /mountedhd/
app  boot  dev	home	    initrd.img.old  lib32  libx32      media  opt   root  sbin	       src  sys  usr  vmlinuz
bin  data  etc	initrd.img  lib		    lib64  lost+found  mnt    proc  run   screenshots  srv  tmp  var  vmlinuz.old

we got the host file system mounted inside the “container”, making it not a container at all!

Depending on your Docker host configuration you might even be able to see the contents of proc/1/ns/pid and simply nsenter into a shell in the host. And well … if things aren’t configured as the container likes … the container should have an easy time making the config a little more pleasing to it’s nefarious plans.

Bottom Line

Don’t use privileged containers unless you treat them the same way you treat any other process running as root. Newer Docker versions allow you more fine grained control over the containers device access anyhow, check this out for more documentation on container capabilities and rights management.

Corner Cases

If you want to try this out on EC or a VM additional steps might be needed to make the device descriptor appear. On EC2 all you need to do is run:

root@8f766733df83:/# file -s /dev/xvda1

and you got a descriptor of the host’s hd that you can mount.

On Virtualbox/Boot2Docker you need to make the logical volumes appear as proper devices:

root@8f766733df83:/# vgchange -ay

is your friend here. If this doesn’t work you might need to activate the needed kernel module for handling logical volumes the way we want it here:

root@8f766733df83:/# modprobe dm-mod

The fact that this actually works should scare you straight enough to not use privileged containers unless you have to btw ;)

It's not PHPUnit, PHP, Legacy Code or Obscure APIs ... it's you!

Sun, 03 Jan 2016 00:00:00 +0100

Introduction … Stop Making Excuses … The actual reason you don’t write tests …

It seems weird doesn’t it? You barely find any Ruby on Rails codebase not containing at least an attempt at a test suit, while a large number of PHP projects seem to run PHPUnit like vampires from sunlight.

So, how did this come about? Maybe unit-testing PHP is harder than re-writing WordPress in pure C? Not really … people just don’t know what they’re doing, that’s all … you’ll see. But … let’s look at the psychology behind this first.

The Nice Explanation

Ok, let’s start this out the nice way. PHP simply came before say Ruby on Rails in terms of being popular. For the sake of argument say … PHP was hyped a lot around 2000-2002. Back in those days, PHPUnit wasn’t even around. According to Wikipedia it had it’s initial release in March 2004.

So a reasonable argument could simply go along the lines of many PHP developers not having been introduced to unit-testing when they started out and the lack of adoption of TDD and the like in PHP projects is simply a collective bad habit I guess.

The not so nice way of putting it …

Honestly … I don’t buy the above. The problem is much different in my opinion, at least with some people. PHP simply is an incredibly easy language. It neither suggests nor enforces many good practices. When setting up your Rails project, Rails at least gives you a folder structure suggesting proper separation of your models, views, controllers and whatnot. PHP and many popular frameworks built on it, like say WordPress do not do that. You’re free to do whatever the hell you want! No clue on programming beyond trivial control flow … No Problem!

Just write some HTML, and whenever you feel like adding some dynamic behavior throw in the good old <?php //crappy code ?> every now and then and feel like a developer. This will work out surprisingly well up to a certain project size. Sooner or later though you’ll find yourself going back and forth between random bug A rendering some box in one corner of the screen wrong and random bug B throwing a notice every now and then. Your project simply will hit that point, no matter how careful you are. Some people can delay the onset of this longer by being paranoid and conscientious … others with bad concentration will hit it sooner.

Eventually the all have to face one fairly obvious fact, their skill-set simply does not allow for a project beyond a certain size X. This is not PHP’s fault, it’s the programmers fault, I’m sorry ( not really ) … it’s true.

You can test it all … just watch and learn …

So, lets look at some of the general issues people are having with this and see how you can work around them in the real world.

Example One: Crappy Global Function in the API

So lets assume you’re working with “WeirdoCMS”. WeirdoCMS has a fun little public function in it’s API that does some crazy magic, eventually accessing 21 different tables just to return you the number of FOOs …whatever those may be. Let’s call that function FooCount. Now you got yourself the task of fixing this thing in your WeirdoPlugin:

<?php

function evenNumberOfFoo(){
	return (bool)(FooCount() % 3) === false;
}

Damn … someone wasn’t even able to find the 2 on his keyboard it seems :/ Wouldn’t it be great if we could turn that 3 into the correct 2, while also preventing this from ever happening again with a test? It sure would be …

How to do it wrong

So people generally do this when faced with the above illustrated issue of having a trivial thing to test, but no idea of how to test it on account of the API interfacing with their code being all but trivial (remember 21 tables). The more motivated ones within the incompetent population might actually try to tackle this by actually setting up those 21 tables correctly only to run their example like so:

<?php

class CrappyTest extends \PHPUnit_Framework_TestCase
{
	public function TestEvenNumberOfFoo(){
		// 200 lines of code only the creator of this will ever understand but actually sets up 11 Foos
		$this->assertFalse(evenNumberOfFoo());
		// Another 200 lines of the above kind ... actually setting up 12 Foos
		$this->assertTrue(evenNumberOfFoo());
	}	
}

After actually having gone through this pain once, they’ll probably also not do it again and simply state that their project does not have the time and budget for unit-testing. Most will probably not even get this far, they’ll simply give up without shelling out those hundreds of lines of weird and crappy test code.

How to get it right

Step 1: Drop the Procedural Programming, we’ve entered the OOP era quite some time ago …

So let’s encapsulate our function in an object first, many will try this step anyways … just because everyone seems to be doing it. And let’s also try being a little full of ourselves and “apply correct OOP principles” while talking out of our behinds mostly … to put it mildly.

So instead of evenNumberOfFoo we now use:

<?php

class FooChecker 
{
	public function evenNumber()
	{
		return (bool)(FooCount() % 3) === false;
	}
}

That didn’t really accomplish much except for turning

<?php
$even = evenNumberOfFoo();

into the more verbose

<?php
$even = (new FooChecker)->evenNumber();

Apart from making the code longer we accomplished exactly nothing so far I fear … also the code is now a little slower with all that object instantiation overhead. That can’t be it with those OOP principles … this seems to make things even worse than before. We still can’t test this and now it’s longer and slower …

Step 2: Learn the word “Mocking” …

Now after some googling around you finally figure it out, you’re not the first person to run into the above issue. As a matter of fact, it seems half the PHP dev population has too. So you learn that using that magic Mocking thing, you can actually force FooCount() to return whatever you want it to apparently. But … again life is fll of disappointments :/ … seems you can only do this with actual class methods. Your API is given to you in the form of a men old global function though. You might start torturing Google a little more, but eventually you’ll find out … there is absolutely no way of mocking those global functions.

No unit-testing using WeirdoCMS it seems, it has it’s API presented to you in the form of global functions and there is just no way of mocking it and since that’s so unit-testing is just way too hard, impossible or time-consuming. You can even tell your boss that it’s not your fault, all those bugs suck … but hey WeirdoCMS apparently does not allow you to unit-test, so on to the next 40 regressions in your bug-tracker …

Sounds like you :)? Check out the next step, you’ll see … it’s gonna be all better soon :)

Step 3: Learn how to “mock”

Well, it doesn’t take a genius to figure out that if you can only mock and hence fake the return of your number of Foos when it’s given to you by a non-static class method, then you simply have to return it by a non-static class method. In come wrapping and dependency injection :)

So let’s wrap that function call in the form of a method call, lets do it like this:

<?php

class MyWeirdCMSApiWrapper {
	public function FooCount(){
		return FooCount();
	}
}

So with this we could turn out Class into this I suppose:

<?php

class FooChecker 
{
	public function evenNumber()
	{
		return (bool)((new MyWeirdCMSApiWrapper)->FooCount() % 3) === false;
	}
}

Still you simply can’t seem to figure out how to mock the FooCount … after all it seems you can only mock the return of the method on specific instances of the MyWeirdCMSApiWrapper and not on all instances. But as you’re only instantiating those object when calling the method you’re trying to test, your test setup simply cannot force them to return anything specific.

In comes dependency injection to the rescue. Something had to come to the rescue right? I mean … if you think about it, your new MyWeirdCMSApiWrapper() essentially is just a different public method being called. You just moved the issue, you did not fix it!

So, what is this dependency injection thing? Well, it just means that you do not instantiate objects inside of your methods (with exceptions obviously … otherwise you would never get any instances of anything I guess :)) or use global variables for the objects you’re trying mock, but just inject them via the constructor of your to be tested classes.

So instead of creating an instance of your API wrapper, you just pass it to the constructor of your class like so:

<?php

class FooChecker 
{
	private $apiWrapper;	

	public function __construct($apiWrapper){
		$this->apiWrapper = $apiWrapper;
	}	

	public function evenNumber()
	{
		return (bool)($this->apiWrapper->FooCount() % 3) === false;
	}
}

Now instead of a crappy test, we can actually make a nice test, by mocking that $apiWrapper we’re passing in. Enjoy the beauty of proper OOP design and testing :)

<?php

class GoodTest extends \PHPUnit_Framework_TestCase
{
	public function TestEvenNumberOfFoo(){
		$apiMock = $this->getMockBuilder('MyWeirdCMSApiWrapper')->getMock(); // create our naked Mock, it will return null for all public methods at this point!
		$apiMock->method('FooCount')->willReturn(11); // Make it return an odd Number, let's use 11. This is the actual mocking btw :)
		$subject = new FooCount($apiMock); // now create an instance of your to be tested Class. Let's call it subject, it being the subject of tests and all :)
		$this->assertFalse($subject->evenNumber()); // 11 is not even, we want it to return false and write our test accordingly.

		// Now lets do the even case too, just for completeness sake :)
		$apiMock = $this->getMockBuilder('MyWeirdCMSApiWrapper')->getMock(); We need a fresh mock here, the old one cannot be altered.
		$apiMock->method('FooCount')->willReturn(12); // 12 is even :)
		$subject = new FooCount($apiMock); // get us a fresh subject ... the old one is still suffering from always getting the 11 for the FooCount ...
		$this->assertTrue($subject->evenNumber()); // 12 is in fact even, we want it to return true and again write our test accordingly.
	}	
}

BAM! Sure the above suffers from duplicate code, but for now … this is a much nicer test than expected isn’t it and trivial to create too!

Working from this you could obviously start substituting your globals for injected dependencies, your singletons for class you can actually instantiate freely and wrap APIs nicely and well … you might actually stop bitching and start testing :)

To be continued …

Example Two soon … though seriously … the above should give you all the material you need to circumvent all those crappy and tricky testing spots shouldn’t it ? :)

vld.obrown.io - Fun with PHP Op-Codes

Wed, 23 Dec 2015 00:00:00 +0100

VLD.OBROWN.IO

After googling around for a bit, trying to find a nice and easy to use PHP Opcode compiler, I found Derick Rethan’s Vulcan Logic Disassembler. It did exactly what I wanted it to, but setup and use might not be for everyone and as I was looking to use this for educational purposes mostly, I created a quick web app for it. You can find it here: vld.obrown.io.

Nothing spectacular so far, but I’ll try to find time to add a little more content to it soon. So far it’s simply

Put PHP code into the left text-box
Click compile
Get opcode on the right after a few seconds

All presented nicely :P

Dockerize PhpUnit and Force Idea/PhpStorm to Use it!

Wed, 23 Dec 2015 00:00:00 +0100

Why???

Well … say you want to run your unit-tests against multiple PHP versions and still enjoy the comfort of your IDE + Xdebug :P

How ???

Easy once you know how, but a little fiddly the first time around :)

Step 1: Create a Docker Image with your Dependencies

As an example I’ll use a typical WordPress unit-test setup here. In my case I wanted to be able to run my Unittests with PHP7, but not have to pollute my Debian Jessie/Stretch install, with a non apt-packaged PHP7 alongside the PHP 5.6.16 that currently comes with it. Still I wanted this to run nicely from IDEA :)

All the code for the following can be found in here on GitHub.

So since we’re gonna be playing with WordPress we’ll need a few extensions on top of our standard PHP7 CLI docker image from the official repo. Also we need PHPUnit and XDebug. Lastly we are going to use the composer installation of PHPUnit, so we need composer also.

The resulting Dockerfile comes out to something like this:

FROM php:7-cli
MAINTAINER Armin Braun

RUN apt-get update && apt-get install -y mysql-client libmysqlclient-dev curl git \
    libfreetype6-dev libjpeg62-turbo-dev libmcrypt-dev libpng12-dev \
    && docker-php-ext-install iconv mcrypt \
    && docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install gd \
    && docker-php-ext-install zip \
    && docker-php-ext-install mysqli \
    && docker-php-ext-install opcache \
    && docker-php-ext-install mbstring 

#COMPOSER 
RUN curl -sS https://getcomposer.org/installer | php
RUN mv composer.phar /usr/local/bin/composer

#PHPUNIT
RUN composer global require "phpunit/phpunit"
ENV PATH /root/.composer/vendor/bin:$PATH
RUN ln -s /root/.composer/vendor/bin/phpunit /usr/bin/phpunit

#XDEBUG
RUN pecl install xdebug-2.4.0RC3 
RUN echo "zend_extension=xdebug.so\nxdebug.cli_color=1\nxdebug.remote_autostart=1\nxdebug.remote_connect_back=1" > /usr/local/etc/php/conf.d/xdebug.ini

So far so good :) We can now build this thing ( which I already did for you here: DockerHub under Tag: 7-cli-phpunit-xdebug ).

The import part in this is that you correctly link phpunit to be in the path. This is done in this part:

RUN ln -s /root/.composer/vendor/bin/phpunit /usr/bin/phpunit

… just trivially sym-linking the docker executable to something that is in the path for sure.

Also, and this is where it gets a little hacky for the time being unfortunately, we need to setup the networking for XDebug and the container itself. The XDebug part is where we need to force XDebug to send requests, via us echoing:

xdebug.remote_autostart=1
xdebug.remote_connect_back=1

into the xdebug.ini.

Step 2: Create our new PHP-executable

What we now need is for our dockerized PHP executable to behave as similarly as possible to a plain standard PHP executable on the host system.

This can be done via the following bash script, that you can fine here.

docker run -i --rm -v "${PWD}":"${PWD}" -v /tmp/:/tmp/ -w ${PWD} --net=host --sig-proxy=true --pid=host originalbrownbear/php:7-cli-phpunit php "$@"

What this does is:

Mount the current working directory into the container.
Make the container use the host’s pid space
Make the container use the host’s network adapter
Mount the hosts tmp folder into teh container, as PHPStorm copies a file there in some cases

If you’re using your own version and not one provided by me in GitHub, you need to make sure to

chmod +x

it so that PHPStorm can run it like any other executable.

Step 3: Setup PHPStorm/Idea correctly

This is relatively easy fortunately. Just point the PHP Interpreter setting at your bash script that you crated above, like this for example:

… and ignore the warning. This is nothing to worry about, the ini file is simply in the container and not accessible by PHPStorm.

Also set your PHPUnit settings like in the above and you’re pretty much there and should be able to run phpunit.xml files like with any other PHP + PHPUnit setup, while being able to easily jump around PHP versions.

The only difference in behavior I am currently seeing is, that I still need to manually make PHPStorm listen for incoming XDebug connections via the telephone icon set like this:

Pro Tip: Skip XDebug unless you actually need it!

In case you’re running most of your test runs without XDebug ( as you probably should … different topic though ), you shouldn’t necessarily use a container that has XDebug even installed for performance reasons. Even if the .so extension is loaded, but disabled otherwise the performance hit can be 50%+ easily for most applications!

In this case simply delete the XDebug part of the image build and create another bash script to run the second image without XDebug. All this can be found worked out in examples in the GitHub repo.

Update: How to Make This Work on Mac at Last :)

On mac our nice and easy bash script from above unfortunately turned out to not work, as discussed in the comments. Fortunately this could be resolved easily, like so:

#!/usr/bin/env bash
# beginning of "docker-machine env default" output
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://192.168.99.100:2376"
export DOCKER_CERT_PATH="/Users/brownbear/.docker/machine/machines/default"
export DOCKER_MACHINE_NAME="default"
# End of "docker-machine env default" output
/usr/local/bin/docker run -i --rm -v "${PWD}":"${PWD}" -w ${PWD} --net=host --sig-proxy=true --pid=host originalbrownbear/php:7-cli-phpunit php "$@"

simply paste the output of

$ docker machine env default

before the original version of the bash call and you’re good :) Only other thing you need to keep in mind is that:

Every directory you mount into a Docker container on a Mac needs to be in your users home folder!

… anything else just won’t work for permissions reasons it turns out.

PHP Performance - Inlining Redundancies

Sat, 19 Dec 2015 00:00:00 +0100

Micro-Optimization and PHP ???

Yes really!

Gotten to the point where adding that next caching for some database query simply stopped being helpful?

No clue why your crappy WordPress plugin takes up 50% or more of the page load time, even though you cut the database queries down to next to no query time?

This is for you …

When to Micro-Optimize ???

Easy … whenever there is no other way out of your performance problem. Sure hardware is a ton cheaper than developer time … but every now and then your project simply does not allow for that hardware upgrade for whatever reason …

Shipping your product to a bunch of customers maybe?

Already running the fastest CPU out there?

Your developers love you and work for free?

… so many possible reasons for why you might be reading this …

So let’s get to it …

No Free Lunch …

So you did it … your static code analysis tool is finally happy. All methods are less than 40 lines or whatever arbitrary maximum method length you though will make your code look nice.

Everything is nicely encapsulated in a million classes, every action your code takes fires of a trivial to understand series of small objects interacting all nice and readable … unfortunately your customers started to brutalize Google for a leaner competitor meanwhile … those ungrateful simpletons … not showing the least bit of appreciation for your code quality, for your readability … not even for your separation of concerns …

What did you think … that the load time of your site is just those darn database queries ?

… or maybe those darn regular expressions ?

… or is it all in your caching now? All those serialize/unserialize operations getting the best of you?

Sure those things are slow at times … we’ll look into those some other time though. For now, let’s try to find out how much we’re actually paying for all those tiny functions, methods, objects and redundant variables that make everything so nice and readable.

… those aren’t free … not at all.

Getting down to it …

Step 1: So not free eh? How much are they then? ( Gathering Data )

Well it depends … let’s gather some data I guess …

Since we might be dealing with the case of a broad and very heterogeneous user population, lets gather that data across multiple PHP versions. While we’re at it, we can also stop you from using all that crazy profiling I suppose … so lets also play with XDebug while we’re at it …

So multiple setups … good thing it’s 2015 and we have Docker to play with now.

So help yourself to some working docker daemon and the code we’re gonna be using here.

Hint:

git clone https://github.com/original-brownbear/php-performance-demos.git

So once we have that code, let’s run it. Since we’re mostly concerned with the effects of inlining ( or rather not inlining ) things here. That .sh file seems like a good start.

./inline.sh

Bam! … that’s enough data for one day I guess …

PHP 5.4


It took 1.4025449752808 s without inlining the function and with redundant local variables inside the function
It took 0.84425115585327 s without inlining the function and without redundant variables inside the function
It took 0.80232501029968 s with inlining the function and with redundant local variables
It took 0.51220011711121 s with inlining the function and without redundant local variables
It took 2.572212934494 s with using a class method and with redundant local variables
It took 1.9973518848419 s with using a class method and without redundant local variables
It took 2.8596611022949 s with using a class method with method parameters and with redundant input variables
It took 2.8738570213318 s with using a class method with method parameters and without redundant input variables
It took 5.4805200099945 s with using a class method with constructor parameters and without property declarations
It took 4.4061641693115 s with using a class method with constructor parameters and with private property declarations
It took 4.3610110282898 s with using a class method with constructor parameters and with protected property declarations
It took 4.3442859649658 s with using a class method with constructor parameters and with public property declarations

PHP 5.4 + XDebug


It took 6.619166135788 s without inlining the function and with redundant local variables inside the function
It took 6.9019331932068 s without inlining the function and without redundant variables inside the function
It took 2.0546748638153 s with inlining the function and with redundant local variables
It took 1.1751098632812 s with inlining the function and without redundant local variables
It took 9.0551729202271 s with using a class method and with redundant local variables
It took 8.1946280002594 s with using a class method and without redundant local variables
It took 10.072288990021 s with using a class method with method parameters and with redundant input variables
It took 9.2914588451385 s with using a class method with method parameters and without redundant input variables
It took 19.139733076096 s with using a class method with constructor parameters and without property declarations
It took 15.34263086319 s with using a class method with constructor parameters and with private property declarations
It took 15.49893116951 s with using a class method with constructor parameters and with protected property declarations
It took 15.300618171692 s with using a class method with constructor parameters and with public property declarations

PHP 5.5


It took 1.4747610092163 s without inlining the function and with redundant local variables inside the function
It took 0.86752104759216 s without inlining the function and without redundant variables inside the function
It took 0.95179986953735 s with inlining the function and with redundant local variables
It took 0.52045392990112 s with inlining the function and without redundant local variables
It took 2.7302191257477 s with using a class method and with redundant local variables
It took 2.0185148715973 s with using a class method and without redundant local variables
It took 2.8453660011292 s with using a class method with method parameters and with redundant input variables
It took 2.8968069553375 s with using a class method with method parameters and without redundant input variables
It took 5.2499659061432 s with using a class method with constructor parameters and without property declarations
It took 4.3478300571442 s with using a class method with constructor parameters and with private property declarations
It took 4.1988000869751 s with using a class method with constructor parameters and with protected property declarations
It took 4.214898109436 s with using a class method with constructor parameters and with public property declarations

PHP 5.5 + XDebug


It took 6.2536900043488 s without inlining the function and with redundant local variables inside the function
It took 4.9655790328979 s without inlining the function and without redundant variables inside the function
It took 2.0919289588928 s with inlining the function and with redundant local variables
It took 1.2138221263885 s with inlining the function and without redundant local variables
It took 8.6731350421906 s with using a class method and with redundant local variables
It took 7.4445428848267 s with using a class method and without redundant local variables
It took 8.8504319190979 s with using a class method with method parameters and with redundant input variables
It took 8.0068590641022 s with using a class method with method parameters and without redundant input variables
It took 15.685569047928 s with using a class method with constructor parameters and without property declarations
It took 14.428926944733 s with using a class method with constructor parameters and with private property declarations
It took 14.412018060684 s with using a class method with constructor parameters and with protected property declarations
It took 14.306435108185 s with using a class method with constructor parameters and with public property declarations

PHP 5.6


It took 1.4295959472656 s without inlining the function and with redundant local variables inside the function
It took 0.85520005226135 s without inlining the function and without redundant variables inside the function
It took 0.74695014953613 s with inlining the function and with redundant local variables
It took 0.49425292015076 s with inlining the function and without redundant local variables
It took 2.4544260501862 s with using a class method and with redundant local variables
It took 1.9607548713684 s with using a class method and without redundant local variables
It took 2.6875011920929 s with using a class method with method parameters and with redundant input variables
It took 2.6686630249023 s with using a class method with method parameters and without redundant input variables
It took 5.1677548885345 s with using a class method with constructor parameters and without property declarations
It took 4.1540579795837 s with using a class method with constructor parameters and with private property declarations
It took 4.1646270751953 s with using a class method with constructor parameters and with protected property declarations
It took 4.131668806076 s with using a class method with constructor parameters and with public property declarations

PHP 5.6 + XDebug


It took 6.1721510887146 s without inlining the function and with redundant local variables inside the function
It took 4.9106600284576 s without inlining the function and without redundant variables inside the function
It took 2.1572380065918 s with inlining the function and with redundant local variables
It took 1.2649810314178 s with inlining the function and without redundant local variables
It took 8.7360029220581 s with using a class method and with redundant local variables
It took 7.3417930603027 s with using a class method and without redundant local variables
It took 8.9390790462494 s with using a class method with method parameters and with redundant input variables
It took 8.3251278400421 s with using a class method with method parameters and without redundant input variables
It took 15.677669048309 s with using a class method with constructor parameters and without property declarations
It took 14.916995048523 s with using a class method with constructor parameters and with private property declarations
It took 14.911762952805 s with using a class method with constructor parameters and with protected property declarations
It took 14.528133869171 s with using a class method with constructor parameters and with public property declarations

PHP 7


It took 0.55066180229187 s without inlining the function and with redundant local variables inside the function
It took 0.23726606369019 s without inlining the function and without redundant variables inside the function
It took 0.37661790847778 s with inlining the function and with redundant local variables
It took 0.10790801048279 s with inlining the function and without redundant local variables
It took 1.2261588573456 s with using a class method and with redundant local variables
It took 0.92833209037781 s with using a class method and without redundant local variables
It took 1.3132491111755 s with using a class method with method parameters and with redundant input variables
It took 1.2214460372925 s with using a class method with method parameters and without redundant input variables
It took 2.2280390262604 s with using a class method with constructor parameters and without property declarations
It took 1.7811279296875 s with using a class method with constructor parameters and with private property declarations
It took 1.8180849552155 s with using a class method with constructor parameters and with protected property declarations
It took 1.8068678379059 s with using a class method with constructor parameters and with public property declarations

PHP 7 + XDebug


It took 5.1429510116577 s without inlining the function and with redundant local variables inside the function
It took 3.9954431056976 s without inlining the function and without redundant variables inside the function
It took 1.5582900047302 s with inlining the function and with redundant local variables
It took 0.64883804321289 s with inlining the function and without redundant local variables
It took 6.7732870578766 s with using a class method and with redundant local variables
It took 5.6968550682068 s with using a class method and without redundant local variables
It took 6.8934459686279 s with using a class method with method parameters and with redundant input variables
It took 6.4292969703674 s with using a class method with method parameters and without redundant input variables
It took 12.728615045547 s with using a class method with constructor parameters and without property declarations
It took 11.849714994431 s with using a class method with constructor parameters and with private property declarations
It took 12.050687074661 s with using a class method with constructor parameters and with protected property declarations
It took 11.997341871262 s with using a class method with constructor parameters and with public property declarations

So how did we do that? … we just ran this script leveraging Docker’s awesomeness.

for PHP_VERSION in "5.4" "5.5" "5.6" "7"
do
	echo -e "\nPHP ${PHP_VERSION}\n"
	docker run -t --rm -v "$PWD":/src php:${PHP_VERSION}-cli php /src/inline.php
	echo -e "\nPHP ${PHP_VERSION} + XDebug\n"
	docker run -t --rm -v "$PWD":/src originalbrownbear/php:${PHP_VERSION}-cli-xdebug php /src/inline.php
done

Mount the current working dir containing the inline.php test script into various docker containers and execute it in exactly the same way on each of them.

The test script itself just does one simple thing in various ways, it concatenates the strings ‘a’ and ‘b’ a bunch of times and depending on the test either very directly or buried deep in the stack …

So, what can we learn from this, let’s see …

Step 2: … WTF is This ??? ( Making Sense of the Data )

Step 2.1: Turn off XDebug …

Without even going into the details of each test run, you should be able to see why XDebug is probably the worst thing to have running while optimizing performance. It significantly skews the relative performance of various solutions to the same problem.

A few examples from the above data for PHP 5.6:

Using redundant local variables comes with a 1.43/0.86 ~ 1.66 times slower execution for concatenating ‘a’ and ‘b’ when running:

<?php

$a = 'a';
$b = 'b';

$a . $b;

instead of outright running:

<?php

'a' . 'b';

… when XDebug is not loaded.

Load XDebug and the advantage of removing those redundant variable assignments goes down to 6.17/4.91 ~ 1.26 speedup/slowdown.

The trouble with XDebug is not that it slows down overall execution, the trouble is it skewing relative performance relative to production systems! Either avoid using its profiling when micro-optimizing or at least be mindful of this effect!

Step 2.2: Understand the data …

Step 2.2.1 Redundant Local Variables are Slow and Hard to Read

Lets not get into the readability thing here … this is settled anyhow … You use the variable only once ? So why use a variable ? Why would you want me, the poor dude having to read your code, to be forced to understand that you’re just using that variable as a long-winded way of adding a comment? You don’t need to save that data to anywhere, you’re only using it once … so please make the code tell me that when I read it …

Also … apart from me being able to better understand your code … more importantly your PHP interpreter will be able to better understand it …

Just by the numbers the above example of adding pointless variable assignment to the concatenating of those two strings comes with a slowdown, depending on the PHP version of:

PHP 5.4: 66%

PHP 5.5: 68%

PHP 5.6: 66%

PHP 7.0: 139%!

So why is that so … everyone on StackOverflow tells me that these assignments are ‘optimized away’ anyhow?

First off … guess who does that optimizing and needs time for it … yes your CPU …

Second of all … PHP is constantly optimizing things behind the scenes and getting ever better at it as time goes by. Now it’s relatively trivial to see ‘a’ . ‘b’ and figure out that this will always come out to ‘ab’, reserve the respective amount of memory and get all the other crazy weird things behind the scenes right. But thing about optimizing $a . $b … there’s nothing to optimize there unless the interpreter knows what $a and $b are beforehand. It cannot know this without executing the code though for obvious reasons … ( cough … Halting problem ) Good thing you’re a human and know what’s going on in your code better than the machine … be so kind and tell it all that you know as directly as you can. It might reciprocate and help your customers as quickly as it can at some point down the line :)

Step 2.2.2 Function Calls ain’t Free …

The next thing to understand is, that function calls are not free at all compared to just running code line by line. Someone has to find out and keep track of what function means what … Sure this is all in some hash table with very fast lookup and very strong scaling behavior … then again if you do this a few thousand times it does add up …

So lets start out with the numbers on how using some function like

<?php

function concat_function(){
  return 'a' . 'b';
}

compares to just good old …

<?php

'a' . 'b';

Depending on the PHP Version the slow down comes out to:

PHP 5.4: 65%

PHP 5.5: 67%

PHP 5.6: 73%

PHP 7.0: 118%!

Again … the newer your PHP version the more of the under the hood progress made on the interpreter is wasted by adding additional function calls that mess up optimizations.

This is not to say that you should get carried away creating monstrous functions spanning hundreds of lines, rather see if that small function inside some long loop really needs to even be a function/method ? Maybe it can be inlined since it’s used in one spot only anyhow?

Also for even more obvious reasons … at least stop doing this to your coworkers:

<?php

function foo(){
	return bar();
}

Seriously … why is this still happening in so many projects on this planet? … Sure sometimes it’s just an outright compatibility/needing that alias thing … mostly this is just stupid though ..

Step 2.2.3 Objects do cost a lot!

Given you know about the expenses incurred from redundant variable assignments and function calls this shouldn’t come as a surprise to you, object instantiation and class methods come at a significant cost. More on this some other time, just keep above numbers in mind when coding your long loops.

Something like the below example ( obviously way over the top ), surely won’t be an issue used like 10 times throughout your app. Use it in that 10k iterations loop and it will show though …

<?php

class ConcaterConstructParamDeclared{
	private $a;
	private $b;
	public function __construct($a, $b){
		$this->a = $a;
		$this->b = $b;
	}
	public function concat(){
		return $this->a . $this->b;
	}
}

Step 3: Uff … won’t do it again … Promise! ( Avoiding Overhead when it matters )

Just knowing the above should give you a strong starting point to optimize away some of the demonstrated overhead from your code where it matters.

Instead of going overboard with these things though … keep your code clean, keep things modular … when the time comes to speed up those long loops or whatever, you’ll find them in no time.