Annotations in PHP: They Exist

I came across this gem just now. My first thought was, “138 slides?! Man, I don’t have that kinda time.” But it turns out it’s a great presentation. Well worth a look.

Thanks for the link. However, I’m not a fan of using annotations for configuration. To me this article makes much more sense because it explains the why behind things. It’s good that PHP has a reflection method to read annotations but using it for anything more than creating documentation seems like misuse. Let annotations annotate and that’s it.

I am not a fan of annotations either, I like to write code than comments. But have to agree that they are helpful at times, so its always nice to keep them an option that they are available when you need them.

I understand the hangup that comments shouldn’t be code. Let’s suppose, instead, that PHP formalizes annotations into the language (like Java, C#, and others have done). Such as…


class User

No comments anymore, so this ought to alleviate that icky feeling.

Yet all we actually did was change the token used to denote an annotation. Were there any practical issues we solved by doing this? After all, docblocks were already treated specially. Internally, PHP already distinguishes a docblock from a comment. Opcode caches take docblocks into account, but ignore comments. Reflection also takes docblocks into account, but ignores comments.

Maybe it’s time we stop thinking of docblocks as comments and start thinking of them as a language construct. They already behave that way.

Well my idea is that annotation is just like comments. I dont consider them as actual code, since they are irrelevant to the language you are using. It feels like you are learning a markup language, it may be easier to learn than XML but it still does not feel as natural as writing code.

Actually, the comment-like syntax of annotations in PHP is the least serious problem. TomB mentions 7 reasons why they are bad and only the first one is alleviated by using a different (non-comment-like) syntax if such were available. Things like breaking separation of concerns and tight coupling are far more important here. They may seem convenient at first because of succinctness and keeping everything in one place but in the long run I much prefer my classes to be independent from configuration and doing stuff like defining dependency injection or validators via annotations is inflexible, requires learning a new metalanguage (or maybe a few) and feels just wrong.

I’ve just learned there’s a term Principle Of Least Astonishment :eek: that we should strive for, that is make the code as clear and obvious for other programmers as possible - and to me annotation meta-language magic effectively breaks the principle. I’ve found out a [URL=“”]library whose author decided to use annotations for configuring DI and what I find most valuable are the [URL=“”]comments here by other programmers who present very good reasons why this is a bad idea - I think this is a very good read and there’s lots of sound wisdom in it.