Should I use YAML/XML or annotation mapping in Doctrine 2?

Question

I use Doctrine 2 as ORM in Symfony framework. Using annotation-based mapping for entities, I would have to write lot of code (setters and getters, mapping information etc.). Using YAML/XML I won't have to write much just the column definition and metadata. In Doctrine documentation, they use mostly annotations in example with few using YAML or XML.

Should I use YAML/XML or annotations?

For annotations, I can find the documentation for every annotation at http://docs.doctrine-project.org/en/latest/reference/annotations-reference.html. I couldn't find the equivalents of annotation in YAML or XML though; how do I convert the annotations to equivalent YAML/XML expressions?

Answer 1

This is basically down to preference.

This is my view of things:

Pros of annotations:

• easier to work with, since they are close to what they describe (the properties)
• lots of examples use them, as you have already noticed

Pros of yaml/xml

• this keeps the domain objects clean, so absolutely nothing from the persistence layer leaks into the domain (even if in the form of a comment)

If you change the db or the domain, you still have to maintain them in either form, so there's no real advantage in any direction from that standpoint.

From a performance standpoint, in production you should be using doctrine's caching to cache the mappings, so they are equal here too.

Regarding this: "I would have to write lot of code, setters and getters, mapping information":

Doctrine requires private/protected properties, so you'll still be writing getters and setters. And you'll still be writing the mapping info, just in another place.

Personally, I'd go with annotations, since it's a lot easier to find examples and info if you need them.

Answer 2

There is one disadvantage about using Annotations. Since they are defined on the comments (which is weird), you will NOT be able to use precompilers (like Zend Guard) or some bytecode php caching extensions to enhance your code performance (some of them strip the comments). Because annotation is the only specification with this technical impairment, I would NOT recommend using it.

Also, writing 'functional' stuff on comments is just weird.

XML is much more verbose than YAML, but is also more widely known. Documentation examples for XML is the poorest amongst all the options.

YAML is more readable than any of the others, but it also relies on space identation (which some people don't like). Symfony uses YAML by default for its configurations, so many people that use Symfony opt to use YAML for the doctrine mappings -- which means YAML examples are well documented and there are lots of resources out there.

I personally prefer YAML. I can generate the entities automatically using the doctrine schema tools (meaning I don't have to write the getters/setters). I can also use the precompilers/bytecode cache options out there without worrying about having my comments stripped out.

---

Additional information:

If you're using PHP 7.0 or higher, you can't ever set opcache.save_comments = 0 on php.ini if you're using annotations. PHP has a native way to strip comments, which WILL BREAK your application. Guilherme Blanco, one of Doctrine's most active maintainers and the guy who developed the annotation retrieval classes that are used by most projects (Doctrine, Symfony) has spoken out AGAINST comment annotations (if you read the entire thread, you'll see he's very passionate about this). There has also been some extensive discussion on the issues with comment annotations on Reddit, and most people seemed to agree it's a bad idea.

Despite all of that, Symfony's official best practices book advices people to use Annotations. So, most Symfony bundles will probably use annotations as their metadata format.

Answer 3

I think this is a matter of own taste, I prefer the annotations.

I use annotation because if you want to know anything about a field its above the field, else you have to open a new file and search the rules you need.

Best way to figure it out it to create both cases. Then you look what your prefer.