Jump to content

Auto Template Stubs


Robin S
 Share

Recommended Posts

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.

  • Like 4
Link to comment
Share on other sites

  • 5 months later...

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?

Link to comment
Share on other sites

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.  

Link to comment
Share on other sites

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. 

Link to comment
Share on other sites

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.

2021-02-01_124806.png.271ac6bfb3d624cfd896050f381be5ba.png

2021-02-01_124729.png.e90e5978bf0d189316fd4ef393520b44.png

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...

2021-02-01_124415.png.92227d1c307ca0660857a3cf88b11342.png

...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:

2021-02-01_124955.png.a26e1a8edcf707388d810fdd11e7e2d1.png

 

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

Link to comment
Share on other sites

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.

PhpStorm magic method.jpg

Link to comment
Share on other sites

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.

2021-02-01_142620.png.fd845df27441008df42ea26c536e1bea.png

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.

  • Like 1
Link to comment
Share on other sites

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.

  • Like 1
Link to comment
Share on other sites

  • 1 month later...

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.

  • Like 3
Link to comment
Share on other sites

  • 2 weeks later...
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.

Link to comment
Share on other sites

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.

  • Thanks 1
Link to comment
Share on other sites

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 🙂 

  • Like 1
Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share

×
×
  • Create New...