PHPdoc for dynamic magic properties (or methods)

Question

I recently created a class to create HTML elements. Instead of bothering by creating a method for every existing HTML element and attributes, I decided to use magic methods __get and __call. So with my code I can basically do this:

$signUpForm->insert->input->type('text')->name('firstName')->maxlength(100)->disabled
$signUpForm->insert->input->type('email')->name('emailAddress')->maxlength(100)

etc.

But since I decided to keep this "magic" and simple, I could also do this:

$signUpForm->insert->magic->trick('rabbit')->accessory('hat') which would result into:

<magic trick='rabbit' accessory='hat'>

This is all good since in my opinion it cuts down a lot of boilerplate code and does exactly what I need to do. I don't want a class to enforce HTML standards, I want a class to facilitate HTML, given you know how to use it (and honestly the code to do this is tiny)

So my question is, considering this class can accept any undefined property or methods, is there any way to specify this behavior in PHPDoc? I tried the following without any luck:

/**
 * @property HtmlElementAttribute *    Insert a new HTML element attribute
 * @method   HtmlElementAttribute *    Insert a new HTML element attribute
 */

I don't know if this is just a PHPStorm thing but I couldn't find any similar scenario anywhere...

Also if you are wondering why I would do such a thing, it is to keep track of certain HTML aspects in my PHP code (e.g. IDs declared in a form, or elements inside a form). This can allow me to have visibility in my HTML before its send to the end user.

Answer 1

The question is still languishing in the unanswered list, so I'm going to answer it.

For good code intelligence in PhpStorm or Sublime when using auto-magical methods like __get() and __call(), you need to include an @property or @method line for each implicit property or method you add. I know this sucks but it's the cost of using such methods.

Please consider when using __get() if you're really getting enough bang for your buck. It might be right for your app, in which case it's fine. We usually use it when we're trying to do further processing or abstraction on object data (such as camel-case name conversion). You save some code (which PhpStorm will write for you anyway) but you'll need to write the PhpDoc DocBlock lines in the class.

Consider including all of the lines, if for no other reason, than to document your class. With implicit properties you're not only making it hard for the IDE to know what methods and attributes are valid members, but you're making it difficult for the next maintainer. Those docblock lines might seem superfluous but they are great documentation.