In the previous post we looked at the process of designing a build container, consisting of all the required build tools for generating a static website from source files. In order to see the result of the build process, we still need to design another container, which runs a simple web server, serving the static website (mainly .html, .css, .js and .jpg files).

Designing the blog container

We’ll use a light-weight install of Nginx as the base image and simply copy the website files to the default document root (/usr/share/nginx/html) (only after removing any placeholder files that are currently inside that directory). The complete file docker/blog/Dockerfile looks like this:

Recently a former colleague of mine, Lucas van Lierop, showed me his new website, which he created using Spress. Lucas took two bold moves: he started freelancing, and he open-sourced his website code. This to me was very inspiring. I’ve been getting up to speed with Docker recently and am planning to do a lot more with it over the coming months, and being able to take a look at the source code of up-to-date projects that use Docker is certainly invaluable.

Previously we looked at how to use the static site generator Sculpin to generate in-project documentation. When Sculpin builds the HTML files and assets it looks at what files are in the source/ directory and processes them based on certain rules (e.g. “parse Markdown files”, “format HTML files with Twig”, etc.). The purpose for my “living documentation” project is to also dynamically generate documentation based on PHP and configuration files from the main project. For example, consider extracting a Composer dependency diagram. I don’t want to manually copy the diagram and an HTML template to the source/ directory. I want Sculpin to generate a current diagram on-demand and wrap it inside a template.

Recently I’ve been reading the book Living documentation by Cyrille Martraire. I can warmly recommend this book to you. It basically provides a solution for the age-old problem of creating and maintaining accurate, up-to-date and useful project documentation. One of the key ideas is to generate documentation instead of writing it. This should help prevent duplication and outdated information that is not trust-worthy and would therefore be neglected. I’m currently looking for ways to technically accomplish such a thing with PHP projects. This should result in reusable tools which will make it easier and more fun to document future projects while writing the code.

TLDR;

• I won’t update A Year With Symfony anymore.
• The e-book is now freely available.

My first book, A Year With Symfony, was well received when I first published it on September 4th. At the time it seemed to be a welcome addition to the official Symfony documentation.

A lot of water has passed under the bridge since then. Several new Symfony components were released and we have now arrived at the next major version, 3.0. In the meantime I published one update of the book: a new chapter about Annotations.

Everybody is organizing their own PHP conference these days. It’s impossible to “catch ’em all”. There’s conferences clashing, conferences too far away, conferences too much like other conferences, etc.

Then there’s conferences that have never been there before, are quite original and are therefore spark everyone’s imagination. One such a conference is the Symfony Catalunya conference. This “international Symfony event” is being organized by the generally awesome and friend of the community Marc Morera. The concept seems to be pretty simple:

Leaving Qandidate, off to Coolblue

After I had a very interesting conversation with the developers behind the Broadway framework for CQRS and event sourcing the day wasn’t over for me yet. I walked about one kilometer to the north to meet Paul de Raaij, who is a senior developer at Coolblue, a company which sells and delivers all kinds of - mostly - electrical consumer devices. Their headquarters are very close to the new and shiny Rotterdam Central station. The company itself is doing quite well. With 1000+ employees they keep needing more office space.

Visiting Qandidate in Rotterdam

Last Thursday I had the honor of meeting (part of the) Broadway team: three very smart developers working for Qandidate in central Rotterdam: Gediminas Šedbaras, Willem-Jan Zijderveld and Fritsjan. A short walk from the train station brought me to their office, where we talked about CQRS, event sourcing and some of the practical aspects of using the Broadway framework.

As you may have read I’ve been experimenting with Broadway extensively during these last weeks. Knowing a lot about the theory behind it, it was really nice to see how everything worked so smoothly. I had some questions however, which have now been answered (thank you guys for taking the time to do this!).

In the first and second part of this series we’ve been doing quite a bit of work to separate concerns that were once all combined into one function.

The major “players” in the field have been identified: there is an HttpClient and a Cache, used by different implementations of CatApi to form a testable, performing client of The Cat Api.

Representing data

We have been looking at behavior, and the overall structure of the code. But we didn’t yet look at the data that is being passed around. Currently everything is a string, including the return value of CatApi::getRandomImage(). When calling the method on an instance we are “guaranteed” to retrieve a string. I say “guaranteed” since PHP would allow anything to be returned, an object, a resource, an array, etc. Though in the case of RealCatApi::getRandomImage() we can be sure that it is a string, because we explicitly cast the return value to a string, we can’t be sure it will be useful to the caller of this function. It might be an empty string, or a string that doesn’t contain a URL, like 'I am not a URL'.

The world is not a safe thing to depend upon

When you’re running unit tests, you don’t want the world itself to be involved. Executing actual database queries, making actual HTTP requests, writing actual files, none of this is desirable: it will make your tests very slow as well as unpredictable. If the server you’re sending requests to is down, or responds in unexpected ways, your unit test will fail for the wrong reasons. A unit test should only fail if your code doesn’t do what it’s supposed to do.