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.

Semmes

1) PHPDoc itself has no * wildcart support for method/property names, at all. Therefore you have to declare each method manually 2) In PhpStorm you can lower the priority of such warning messages or disable such inspection completely – Selfmortification

@Selfmortification thanks for confirming! – Semmes

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.

Tuberous

Thanks for the late answer - I sort of figured this out by now and forgot about this question :) For my specific usecase it would be pretty hard to add everything into DocBlocks so I accept that the IDE integration is not perfect for the sake of code simplicity. – Semmes

Roger that. I find that sometimes I've got classes such as session or post variable abstraction, where it would be ridiculous to add all the @properties. Yet, at other times, it's good. It certainly would be nice if there were to be a regex option to define valid property names. At least then we could benefit from type-o detection. – Tuberous

Definitely agree! in the meantime I'll try to ignore those red lines in Php storm and hope for the best :) – Semmes