A few days ago I needed to assemble together several disparate pieces of information about the current project. Our technology stack is complex, and people have different backgrounds, so I realised that a visual representation in UML would be the best fit.
The current article details how to prepare a working environment using Graphviz and PlantUML in PHPStorm, then goes through the process of creating a simple sequence diagram to use them.
Diagrams: the “why” and the “how”
Created by the Object Management Group, UML is the de-facto standard design language in the software community. If you are not familiar with it, or just need a quick refresher, this article on the developerWorks website is very good.
As I tried a couple of online services, it became increasingly clear that they were not fit for my complex set of interacting components. I then turned to my favorite diagramming, tool Graphviz. It turned out there was no straightforward editor on top of it to do sequence diagrams. Luckily, I pretty quickly found PlantUML, which uses Graphviz for all it diagrams but sequence ones. I was impressed by the amount of integrations it offers so I decided to give it a try, and was amazed with the speed of which I produced the end result.
In the next sections we’ll learn how to get our environment up and running, and then draw a quick example sequence diagram.
Installing Graphviz using brew worked perfectly for me.
$ brew install graphviz
If you prefer an alternate method, you can download the package instead.
Internally, our company uses PHPStorm as an IDE for developing PHP code, and IntelliJ idea for the Java bits. I will present details for the PHPStorm users, but the steps should be easy to replicate in other IDEs of the same vendor.
Let’s open the preferences and start looking for new plugins.
We need to search for “PlantUML” and install it.
After restarting the IDE, we notice there are new filetypes available for us to create:
Sequence Diagram example
Let’s create a new UML Sequence diagram, named “demo”. Notice how the
.puml extension was automatically added.
The diagram I actually needed to produce is very heavy, and not fit for the purpose of this quick introduction. Then I remembered checking the Clean Coders Yahoo group the other day, and found some Ruby sourcecode they were talking about. I thought it would be a good example to try our new diagram superpowers on, as it’s short.
The first step is to define the participants in our diagram. It’s easier to list them all in the beginning, because this way we can choose the order in which they appear.
We will now add the sequence of events. The PlantUML website has a great page on the various options available, so make sure to check it out.
The stock look and feel is nice and gets us far. I however felt the need to prettify the end result by introducing some nice formatting options. The manual page for the
skinparam command is very helpful.
After installing Graphviz and PlantUML extension for PHPStorm, we were able to produce a sequence diagram in a few minutes. You can take a look at the final version of the code as we obtained it. The advantage of having these tools available straight from the IDE is that the diagrams can be part of the project code, and be managed together.