Docblock, Oh Docblock, wherefore art thou Docblock (hint: Zend Optimizer Plus lost them)

tl;dr> I make a terrible assumption about Zend Optimizer+ and am corrected by Dominic in the comments;

Terrible post title I know but its the best I could come up with.

I’ve just come up for air after spending the majority of the day debugging some issues on our current development sandbox.

Now our sandbox tends to be quite bleeding edge in some circumstances and as such we run a fair few bits of unstable code. On the sandbox in question we have been running PHP 5.4.11 and unfortunately we have struggled to get APC working with it just the way we need it to. The lack of APC tends to make this sandbox quite slow.

We recently saw that Zend have open-sourced their OptimizerPlus extension ( and that it was compatible with 5.4…. Fantastic, or so we thought.

So I added the new OptimiserPlus to the sandbox and everything was going swimmingly. That was until we had to run one of the utility scripts that we use to rebuild some of our data structures. These scripts make use of different parts of both Zend Framework and Doctrine which tend to rely on some heavy DocBlock annotations.

Now having used both APC and Zend Server knowing that they done affect this kind of functionality I had expected that OptimizerPlus would be fine…. Wrongo. It took me a good few hours of head scratching trying to figure out what had happened.

It turns out that OptimizerPlus suffers from the same flaws that eAccellerator does and strips Docblocks when caching the bytecode. This results in Reflection returning false when you call methods such as `getDocComment()`.

All in all its not the end of the world I just disable OptimizerPlus and have to wait till I can get APC working. Not my ideal scenario but I can live with it.

Something that does concern me is that there is currently an RFC that has gone to vote ( about integrating OptimizerPlus into the PHP 5.5 distribution. While this is great I do worry how many other things may break and will they be picked up and fixed for the 5.5 release.

Update: Since writing this post the RFC has finished being voted upon and has been approved. You can expect to see Optimizer Plus appearing bundled with PHP soon.

Update (15th Mar 13): Thanks to Dominics’ comment I now know that you can tell Optimizer+ to retain your Docblocks by setting your config using

zend_optimizerplus.save_comments (default "1")
	If disabled, all PHPDoc comments are dropped from the code to reduce the
	size of the optimized code. Disabling "Doc Comments" may break some
	existing applications and frameworks (e.g. Doctrine, ZF2, PHPUnit)

zend_optimizerplus.load_comments (default "1")
	If disabled, PHPDoc comments are not loaded from SHM, so "Doc Comments"
	may be always stored (save_comments=1), but not loaded by applications
	that don't need them anyway.

That’ll teach me to write a blog post without investigating more first.


4 thoughts on “Docblock, Oh Docblock, wherefore art thou Docblock (hint: Zend Optimizer Plus lost them)

  1. I’ve just seen this post and as an heavy annotations user (Doctrine, ZF2 Form Annotations and┬ámy own TjoAnnotationRouter) I find it pretty concerning that they are talking about including optimizer+ in 5.5 without this feature being available. I’m all for them including it but I think this should be addressed.

    On the flip side though, through my own work I discovered that annotation parsing (certainly through the facilities provided by ZF2) can be quite a performance hit so I figure they should be cached/”compiled” to PHP code on your production server anyway. So, so long as you can disable Optimizer+ on the dev server then it may not be a problem – but still annoying.

    1. From my understanding you will be able to disable it and implement a different cache if you choose to.

      Your right in the performance hit which is why tools like Doctrine try and cache the metadata generated into something like APC/Memcache. But at some point your docblocks will need to be read in order to populate that cache.

      On the whole its not the end of the world and its given me the chance to investigate alternatives ways to handle Annotation data and ways to improve performance.

      I definitely want to see it integrated but think that it may require more work before its an acceptable solution for me. What does concern is the possibility that it may introduce other unanticipated side effects. Something else to note is that the problems I’ve identified here are not present in Zend Server! Does that mean that they are not using Optimizer? or are they only open-sourcing an old version and keeping the most current version for themselves?

  2. It turns out that OptimizerPlus suffers from the same flaws that eAccellerator does and strips Docblocks when caching the bytecode.

    Uhh, no. The default is to not touch comments:

    php -i | grep comments
    zend_optimizerplus.load_comments => 1 => 1
    zend_optimizerplus.save_comments => 1 => 1

    Which means you’ve specifically told ZO+ to strip comments. And you’re getting what you asked for.

    1. Hi Dominic… Fantastic thank you for pointing this out. I will mention that I installed Optimiser using the defaults provided by the source which was at the time of my compiling to strip comments. That said I’ve now updated my config and its working. Once again thanks for pointing this out

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.