Auto Template Stubs

[Alpine418]

Any hint how to combine AutoTemplateStubs with custom page classes?

So I get autocomplete for the methods of my custom page class and the properties of the stubs of the same class together?

[Robin S]

10 hours ago, rjgamer said:

Any hint how to combine AutoTemplateStubs with custom page classes?

So I get autocomplete for the methods of my custom page class and the properties of the stubs of the same class together?

I've released v0.2.3 to add some support for this.

v0.2.3

1. Adds a setting to the module config: "Name stub classes for compatibility with custom Page classes". This option names the template stub classes using the same format as for custom Page class names. A side-effect of this is that your IDE may warn you that multiple definitions exist for your custom Page classes. This is because the stub class files generated by this module will always be distinct from any custom Page class files you create (overwriting the actual Page class files is not on the table for this module).

If you enable this option then you'll indicate the class name for $page in your template files like this (using the home template as an example):

/** @var HomePage $page */

2. For new installs the default path for stub files is now "/site/templates/AutoTemplateStubs/". This path is still configurable though.

[Alpine418]

Love ya! Thank you so much!

[MarkE]

As a PhpStorm user, I must say that this is a really helpful module. It works in ready.php, init.php etc. as well as template files (I use custom page classes a lot and always use /* @var ...*/ as it picks up the methods - now it picks up field names too!).

Just one query - the only place it doesn't seem to work (ironically) is on $this within classes, even using the documentor /* @var $this ClassnamePage */

Any suggestions on this?

[Robin S]

2 hours ago, MarkE said:

Just one query - the only place it doesn't seem to work (ironically) is on $this within classes

I'm not sure I understand. This module is specifically for code hints in template files - it doesn't do anything for any other files you might have in your site.

If you are using custom page classes then see the notes in the readme about that, but again this only has an effect on the template file. When you are editing any other class file, module file, etc then this module isn't going to do anything. But PhpStorm should automatically understand the $this keyword in a class context anyway.  

[MarkE]

1 hour ago, Robin S said:

it doesn't do anything for any other files you might have in your site.

I think it does if you are using custom page classes and include a documentor statement for any page variables that have classes. Try it and see. 
 

PhpStorm understands any methods for $this but not any fields. 

[Robin S]

52 minutes ago, MarkE said:

PhpStorm understands any methods for $this but not any fields.

Where are you typing "$this"? In a template file?

If you have a custom Page class HomePage then in your "home.php" template file you put this line at the top:

/** @var HomePage $page */

Then you access any fields or methods of the HomePage class from $page. AutoTemplateStubs gives you code assistance for the fields and the HomePage methods.

In a template file $this refers to a TemplateFile object. It doesn't give you access to fields or methods of the HomePage class.

If you are typing "$this" in the file for a class that extends Page (e.g. HomePage.php) then you are working in file that this module is not designed to support. But PhpStorm automatically gives you code assistance for methods in the class...

...and even though it wasn't something I had in mind when this module was developed (because custom Page classes didn't exist then) you do get assistance for field names too:

 

If this doesn't answer your question please give me more explanation of what you're wanting to do. Maybe screenshots would help.

[MarkE]

2 minutes ago, Robin S said:

Where are you typing "$this"? In a template file?

Not in a template file - that's in a custom page class . Other documented page variables in this context will recognise fields.

5 minutes ago, Robin S said:

..and even though it wasn't something I had in mind when this module was developed (because custom Page classes didn't exist then) you do get assistance for field names too:

That's what I meant - except in my case it is better for documented page variables other than $this. The autocomplete works in all cases, but the $this-> fields are shown as accessed by the magic method. As you can see in the pic, $this->paymentAmount is accessed via magic method, but not for $payment->paymentAmount. A minor point since it is a bonus to get all the field help everywhere and not just in template files. Originally I didn't install the module because I thought it would only work in template files, but with custom page classes it seems to work everywhere (including in ready.php etc.) which is great! So the module description rather undersells it, I think.

[Robin S]

1 hour ago, MarkE said:

As you can see in the pic, $this->paymentAmount is accessed via magic method, but not for $payment->paymentAmount.

It looks like PhpStorm doesn't let you override the variable type in a PHPDoc comment when it already knows the type based on the source code.

When you get a field value via $page->field_name it is accessed via the __get() magic method, so what PhpStorm is telling you in the case of $this->paymentAmount is actually more accurate than for $payment->paymentAmount, where we are sort of tricking PhpStorm through PHPDoc comments into treating overloaded properties as "real" properties of the Page object.

These things aren't fixable issues for the module but are about how your specific IDE understands the code.

[MarkE]

8 hours ago, Robin S said:

These things aren't fixable issues for the module but are about how your specific IDE understands the code.

I was starting to guess that .... but nevertheless, it is a great module and actually a lot more useful than the module description implies as it does cover more than just templates if you use custom page classes (which I do for practically every template other than basic pages). Many thanks for the module and your thoughtful help.

EDIT: Now I understand, I could just turn off the notification in the Settings->Editor->Inspections->PHP->Undefined->Undefined property, but I think I'll live with it.

[Robin S]

v0.2.5 released. In this release stub files will always be created in and deleted from an "AutoTemplateStubs" directory and you can choose where this directory will be created. This avoids the risk that somebody accidentally configures an existing unrelated directory as the stubs directory. Please update to this new version for safety's sake.

[MarkE]

On 2/1/2021 at 1:42 AM, Robin S said:

It looks like PhpStorm doesn't let you override the variable type in a PHPDoc comment when it already knows the type based on the source code.

Actually it's not a PhpStorm issue at all. Just me being a bit dim. The @property definitions are in the Page class in AutoTemplateStubs, which extends Page. My code is in an identically-named class which extends DefaultPage, so I guess PhPStorm assumes they are different classes. If I copy the @property definitions into my DefaultPage extension then PhpStorm gets it OK.

[Robin S]

3 hours ago, MarkE said:

Actually it's not a PhpStorm issue at all. Just me being a bit dim.

I don't think you're being dim - you're just running up against a necessary limitation of what the AutoTemplateStubs module does. The module is only ever going to operate on files in the AutoTemplateStubs directory that it has created itself. As a matter of safety it's not going to get into the business of modifying/overwriting/deleting files that you have created, such as your custom Page class files.

When custom Page classes are not in use AutoTemplateStubs creates stubs for class names like "tpl_basic_page", which don't exist anywhere else in the codebase. They're not "real" classes that do anything - they're just a way to tell the IDE about overloaded properties when you use a PHPDoc comment to (falsely) state that $page is an instance of class tpl_basic_page.

But if you are using custom Page classes then two things apply:

1. There are necessarily going to be two different class files using the same class name - the "real" class file that you create, and the "fake" class file that AutoTemplateStubs creates. Your IDE will probably warn you somewhere that there are multiple definitions for the same class name. 

2. Your IDE "knows" that $this is your custom Page class, and it's likely to "prefer" what it knows about $this from the custom Page class file over anything that is contained in the AutoTemplateStubs stub file.

You can manually copy over the PHPDoc comments from the AutoTemplateStubs stub file to your custom Page class file if you find that's useful, but nothing is going to be kept in sync so you won't be getting the "auto" part of AutoTemplateStubs.

[MarkE]

Thanks.

6 minutes ago, Robin S said:

You can manually copy over the PHPDoc comments from the AutoTemplateStubs stub file to your custom Page class file if you find that's useful, but nothing is going to be kept in sync so you won't be getting the "auto" part of AutoTemplateStubs.

I realise that - just saves a bit of typing with big templates ?