Pre-release: TemplateStubs (IDE support for Page objects)

[mindplay.dk 295]

This module generates a "stubs.php" file containing PHP-classes with documentation for the properties of each Template, based on it's fields - which means IDE support (auto-complete, inspections, documentation) for templates in modern IDEs that perform static analysis, such as PhpStorm.

The output looks like this:

<?php

/**
 * Generated by TemplateStubs module 2013-04-13 15:29:33
 * This file may be overwritten at any time.
 */

namespace tpl;

use Page;

/**
 * "basic-page" template
 *
 * @property string $title Title
 * @property string $headline Use this instead of the Title if a longer headline is needed than what you want to appear in navigation.
 * @property string $summary Summary
 * @property string $body Body Content
 * @property string $sidebar Sidebar
 * @property Pageimages|Pageimage[] $images Images
 */
class basicpage extends Page
{}

To use the generated documentation, start your template-file like this:

<?php

/**
 * @var tpl\basicpage $page
 */

Documentation and more details on this page:

 

https://github.com/mindplay-dk/TemplateStubs

 

You can consider this an alpha-release - I haven't tagged a release yet, and some details like template-class naming convention may change before I tag release 1.0.

[mindplay.dk 295]

Some updates: a use-clause is now generated, pretty big oversight there. PageReference types are now documented with their pseudo-types, which means you'll be able to directly follow a reference to a related page (or list of child-pages) while still getting IDE support.

I simplified the class-name convention - "basic-page" now simply becomes "tpl\basic_page".

And the generated documentation can now be viewed on the configuration-screen - you will see it when you install the module.

[Soma 6,628]

Thanks for you work here mindplay, I'm sure this will be interesting and comes handy for people that use and like this stuff.

Personally I never felt the need for this in ProcessWire, as for the hand full of objects and variables I usually need that are always the same anyway. So in other words PW is so simple this is like having a description how to use a key on a door.

[mindplay.dk 295]

You only have a handful of Page objects and Fields? I think you misunderstood - this does not provide IDE support for ProcessWire (which still needs a lot of work in this area) but for your templates and fields. I'm sure you have more than a handful on complex sites, and I'm prertty sure they're not always the same?

It's not about simple or difficult, it's about proofing your work - knowing in advance if you misspelled a property-name, or not having to go back to find the name of a property on an admin-screen, it saves time. With inspections in PhpStorm, there is also the added benefit of being able to automatically find errors - if you have dozens of templates and you have to make a change like renaming or deleting a field, automatic inspections will instantly reveal which templates are affected.

Most of my day-to-day work is not little projects, but large complicated business-systems - while I used to be able to keep it all in my head, I'm not getting any younger. A good IDE will help you stay fast and accurate when you grow older, wait and see

[mindplay.dk 295]

PS: things are already simple - nothing wrong with making them simpler though, especially when it's no additional work or overhead for those using the module and working with an IDE.

For me, personally, having full IDE support for any piece of PHP software has become a sign of high quality - it means everything can be validated automatically, which usually means it has been. You can't expect a person to do the same for 10,000 lines of code on every release. And vice versa, if a computer can't infer the meaning of your code, how can you expect a person to?

Whether you have IDE support for the users who use an IDE or not, having IDE support means you have automatic safeguards and checks that cannot be performed by a person.

[mindplay.dk 295]

I've tagged release 1.0.0 and the module is now listed in the modules directory.

[bfncs 101]

Thanks for working on this. It works perfectly with PHPStorm and makes writing templates even faster and more precise than before.

Please keep up the good work!

[Rob 44]

...PageReference types are now documented with their pseudo-types, which means you'll be able to directly follow a reference to a related page (or list of child-pages) while still getting IDE support...

Hi - great module which will help me a lot, but I'm a bit confused about this point.

My stubs.php file is generating fine and documents all the fields in each template, but it is only documenting related page fielsd like this...

@property PageArray|Page[] $related_products

...meaning that I get code completion for al the core Processwire Page fields/methods but not my template fields.  Shoud it be generating like this...

@property tpl_product[] $related_products

...so that I get code completion for all the fields of my related page/template?

Is this a bug or do I need to change some config somewhere? I couldn't find anything.  I am perhaps misunderstanding how the phpdoc comments informs my IDE (PHPStorm) but as it stands, I get my first-level fields for a page but nothing for the related page fields.

I downloaded the module as master.zip from github so it should be the latest code.

[mindplay.dk 295]

You most likely didn't configure the allowed template for your Page-field? If so, it should work.

Check the "Input" tab in the Field editor, under "Template of Selectable Page(s)".

[Rob 44]

You most likely didn't configure the allowed template for your Page-field? If so, it should work.

Check the "Input" tab in the Field editor, under "Template of Selectable Page(s)".

Great, thanks, that makes perfect sense.

[mindplay.dk 295]

Just tagged version 1.0.2 which adds an "any" template, documenting all available Fields - this may be useful if you're writing code that works with any type of Page.

[pwFoo 294]

Hi mindplay,

with this module installed and added the following code to my (basic-page) template

<?php
/**
 * @var tpl\basic_page $page
 */  

code completion for things like "$page->title" should be work with Netbeans?

stubs.php file exists, folder is writable.

Netbeans suggest variable / object names like $page, $modules, but not the object properties (example $page->title)

[mindplay.dk 295]

I don't use NetBeans, I use Storm, but I would be very surprised if NetBeans doesn't support basic standard php-doc annotations like @var.

Maybe your IDE isn't set up to inspect the stubs.php file?

Check to make sure the contents of stubs.php is being updated and reflects your templates/fields?

Make sure the output matches your type-hint - this is configurable, e.g. "tpl\basic_page" is one option, but "tpl_basic_page" is also possible.

Just checked, the default is the "tpl_" prefix, and no namespace (for compatibility with older PHP versions) so check the module configuration, you can set the prefix and namespace as needed.

[pwFoo 294]

Hello mindplay,

stubs.php file wasn't generated correct. So I deleted it and regenerated it by submit at modules page.

Now my fields are added to stubs.php, but Netbeans ignore the fields at code completion...

I have to test some configuration settings and take a look at the Netbeans documentation.

Thanks

[mindplay.dk 295]

@pwFoo if this turns out to be a NetBeans issue, and if you figure it out, please post and let me know the solution - I can add it to the README to help others get started.

[pwFoo 294]

Strange... Netbeans have code completion for variables like $page, $pages, $padRender (test instance with PadLooper installed), but missed attributes and methods ($page->myField). 

Quick test with Visual Studio Code (Linux, 0.5) shows me code completion for attributes and methods ($page->title, $page->body ...) out of the box (it seems also without the TemplateStubs stubs.php file?!), but not variables like $padRender, $pages, ... 

At the moment I can't spend time to debug, but I'll reply when I solved my problem. 

[adrianmak 65]

$page variable is working find in phpstorm

However, there is no code autocomplete for other variables like $session, $pages, $users, $user, etc