DataObject Annotations: Because typing @property is boring

SilverStripe and IDE Autocompletion

SilverStripe’s database setup in models is great, but it comes with a little issue. Most IDEs don't detect properties and relations automatically, because they are statically declared in an array, instead of declared as variables, like, for example, Symfony2.

To overcome this problem, DataObject and Page classes can be annotated with PHP docblocks, to tell the IDE that a specific method is available on a class, despite the variable not being declared.

Example of PHP docblock annotation on a Page class

The problem with these annotations becomes obvious once your class has not just three or four db fields. How about when you have thirty? You will have to type a lot of properties, methods, etc.

Most developers skip this tedious job, leaving the IDE thinking the method doesn’t exist, or the property is accessed via a magic method. While this is true, it is not the optimal way to go.

It’s not a problem—it’s a challenge

Because that much docblock typing quickly becomes tedious, annoying and boring, Martijn (known as “marvanni” on IRC) from the Netherlands came up with a solution: the IDE Annotator Extension.

This module builds the annotations for you, for selected modules in your SilverStripe project. You can find the module on Axyr Media’s github.

I have been working on and maintaining this module since he first published it on GitHub—polishing the code, but also adding features like owner recognition and, for example, has_many and many_many relationship detection.

A good developer takes a problem as a challenge, not a problem, and they accept that challenge. That’s exactly what this module is about. Fixing that annoying issue of having the “magic method” remark from your IDE. Or your IDE not understanding that
$this->MyManyManyRelation() is actually a method referring to the ManyManyRelation object.

At this moment, the module relies on requireDefaultRecords. Which is actually not the right way to go, but for now, it’s the only way to get the docblocks written during build. Multiple classes in one file will only create docblocks for the first class in the file. The others are ignored. That is a known issue at this moment.

To start the automatic annotations, you need to run dev/build on your local development version of your website.

Feel free to leave a PR or create an issue on the GitHub repo if you think something can be improved. We’re open to suggestions and improvements.

So, there you go. No more magic-method remarks from your IDE. And full support for many/belongs/has relations and extensions while building your new SilverStripe website.

Happy coding!

P.S. Be aware, this module actively alters the actual content of your files. It tries to look for the database fields and instantiates the assigned classes to find out what type they return. This is then built into a full docblock which is prepended before the class declaration. Effectively “typing” the docblocks for you.

P.P.S. It is important to understand that this module should only be run in dev-mode on your development machine, as it changes contents of a file. Although tested, changing the content of a file via a computed method is always a tricky situation which can cause issues. We suggest you use version control, so you can see exactly what the script does when it runs.