PHPdoc for dynamic magic properties (or methods)
I recently created a class for creating HTML elements. Instead of worrying about creating a method for every existing HTML element and attributes, I decided to use the __get and __call magic methods. 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)
and etc.
But since I decided to keep this "magic" and simple, I could also do this:
$signUpForm->insert->magic->trick('rabbit')->accessory('hat')
which will result in:
<magic trick='rabbit' accessory='hat'>
This is all well and good as it cuts a lot of boilerplate code in my opinion and does exactly what I need to do. I don't want the class to enforce HTML standards, I want the class to make HTML easier given how you use it (and honestly, the code for that is tiny)
So my question is, if this class can accept any undefined property or methods, is there a way to specify this behavior in PHPDoc? I tried the following with no 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 be doing such a thing, there are some aspects of HTML in my PHP code to keep track of (such as identifiers declared on a form or elements within a form). This might allow me to have visibility in my HTML before it is sent to the end user.
source to share
The question is still languishing on the unanswered list, so I'm going to answer it.
For good code intelligence in PhpStorm or Sublime when using automagical methods like __get()
and __call()
, you need to include @property
or @method
for every implicit property or method that you add. I know it sucks, but that's the cost of using techniques like this.
__get()
Consider when using if you are really getting enough hits for your dollar. This may be correct for your application, in which case it is fine. We usually use it when we are trying to do further processing or abstraction of the object's data (such as converting a camel's name). You save some code (which PhpStorm will write for you anyway), but you will need to write PhpDoc DocBlock lines in the class.
Consider including all lines, if not for some other reason than documenting your class. With implicit properties, you not only make it difficult for the IDE to know which methods and attributes are valid members, but you make it difficult for the next maintainer to work. These docblock lines may seem like overkill, but they are great documentation.
source to share