Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

 

DataObject Annotations: Because typing @property is boring

Want to work faster and access a wider array of object properties in the autocomplete feature of your IDE? Then consider DataObject Annotations. 

Read post

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.

Screen Shot 2016 03 29 at 12.02.59 PM

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.

About the author
Simon Erkelens

Simon is a developer at SilverStripe. When not at work, he's writing other programs or focusses on one of his modules he wrote or co-wrote. Or writing new things.

As a real backend developer, he's usually staring at a dark screen with code only. Although every now and then, he can be convinced to work on some frontend things or testing.

In real life, he looks nothing like the cow in his avatar, but he does love cows (both alive and medium rare)

Post your comment

Comments

  • Sounds good but how can i run it?

    I have installed it by composer, added lines to _config.php and after /dev/build?flush=all i can't see effect.

    I have also tried to run dev/build using cli-scipt.php as root but also without any results.

    How should i use it?

    Posted by Przemek, 07/04/2016 7:22pm (8 years ago)

  • maybe there are some extension for PHPStorm that will automatically will be generated properties for docblock ?

    Posted by Donatas, 29/03/2016 7:46pm (8 years ago)

RSS feed for comments on this page | RSS feed for all comments