If you have ever written a blog post, you probably understand why writing a 350 page long book like The Fast Track is a lot of work. Trust me when I say that updating such a book is an entirely different endeavor. Making sure that all code snippets work as expected is tedious. Updating screnshots is even more laborious. But reading an obsolete book is frustrating for users.

When it comes to updating a book like "The Fast Track" for a new version of Symfony, you'd better be prepared for long hours of work. Hopefully, I anticipated most of the problems before I even started to write the first line of the first chapter a year and half ago. So I was well prepared.

But still, it took me so many hours of not so glamourous work. I was not even able to release the book for Symfony 5.1. But I managed to finish everything for Symfony 5.2 and I'm very happy with the results. I'm so excited to share some more details about what's new.

First, you must know that updating the book to Symfony 5.2 allowed me to find some bugs in Symfony before it was even released (the same happenned with the first version of the book). I like to think about the book as yet another end-to-end way to test the framework. Updating to Symfony 5.1 and then 5.2 early on also revealed some bugs and incompatibility in third-party bundles. Most of the time, I pinged people to ask them to allow PHP 8 and Symfony 5.2, but also to update their package dependencies. This is a process that takes a lot of time, waiting for problems to be resolved before being able to move to the next step.

Updating the book for Symfony 5.2 and using the latest best practices for that version was the main focus but I managed to do more than that:

  • The code was moved to PHP 8: Changing the version in composer.json and .symfony.cloud.yaml was easy enough, but I went a step further and switch to use PHP 8 native annotations whenever possible. If everything goes fine, I will be able to get rid of annotations in PHPDocs for Symfony 5.3 (I'm just waiting for some third-party to make the switch).
  • I'm always trying to find ways to ease the learning curve. The book is no exception. In the first version, I wanted to show how one can use many services easily for their project, using the best tool for the job (PostgreSQL for the main entity store, RabbitMQ for queues, Redis for cache, ...). But it comes at a price. When you are learning Symfony, you don't want to learn some adjacent technologies at the same time. In the 5.2 version, I've used another strategy. The book is using PostgreSQL for everything (which, by the way, is what I recommend for most projects), and a couple of chapters at the end of the book show how to use RabbitMQ and Redis. Best of both worlds!
  • Some third-party bundles released some major versions, so their chapters or sections were updated or rewritten accordingly; we now use EasyAdmin 3 and Panther 1.0 for instance.
  • All screenshots have been updated for Symfony 5.2. This one did not take me a lot of time as it's all automated.
  • Talking about automation, I have a bot that reads the book, does everything that you should do when reading the book like running commands, applying patches, adding new files, ... This has many advantages: ensuring that the code works, checking the impact of changing code in a chapter in all other chapters, having up-to-date screenshots, having a repository with the code as it should be at the end of each section of each chapter, and a few more. I have also updated my toolchain to manage multiple versions so that bumping to 5.3 should be a bit easier.
  • This version contains a lot of small and not so small tweaks in the text, with hopefully better explanations when I got feedback about confusing paragraphs, tips based on feedback, and missing notes from the first version. Two small examples: we were missing instructions about installation instructions for NodeJS and Yarn and we did not document how to switch to another environment on the CLI for Windows users.
  • I would have loved to write new chapters, but I think it is going to be for the next version. I did manage to add a whole section about using Xdebug for step debugging though as I realized that many developers are still using (like me) a bunch of print_r() and exit() calls in their code to debug them.

If you bought the PDF book via Leanpub or via the Symfony shop, you can download the new PDF version on Leanpub now.

Else, consider buying the book today to help Symfony or consider sponsoring me on Github.

You can also read it for free online as I've just published the English version on symfony.com.

Last, but not least, translation work will begin soon. As translators will "only" have to translate new paragraphs or paragraphs that changed, it should be a bit easier and faster than the first version.

Enjoy reading the book!

Published in #Community #Documentation #Symfony