interrobang Posted July 11, 2012 Share Posted July 11, 2012 I would like to see some more usage of PHPDoc comments. As a quick test I modified the Page class to include @property comments for all the magic properties, and it works great so far. My IDE now doesn't show warnings for things like $page->name and even gives me autocompletion. I think it would quite useful to include something like this for all the classes also listed in the cheatsheet. What do you think about it? Btw, my IDE is PHPStorm. This is how my Page.php header now looks like: EDIT: Updated the code example to include the cheatsheet comments: /** * ProcessWire Page * * Page is the class used by all instantiated pages and it provides functionality for: * * 1. Providing get/set access to the Page's properties * 2. Accessing the related hierarchy of pages (i.e. parents, children, sibling pages) * * ProcessWire 2.x * Copyright (C) 2010 by Ryan Cramer * Licensed under GNU/GPL v2, see LICENSE.TXT * * http://www.processwire.com * http://www.ryancramer.com * * @property int $id The numbered ID of the current page * @property string $name The name assigned to the page, as it appears in the URL * @property string $title The page's title (headline) text * @property string $path The page's URL path from the homepage (i.e. /about/staff/ryan/) * @property string $url The page's URL path from the server's document root (may be the same as the $page->path) * @property string $httpUrl Same as $page->url, except includes protocol (http or https) and hostname. * @property Page $parent The parent Page object or a NullPage if there is no parent. * @property int $parent_id The numbered ID of the parent page or 0 if none. * @property PageArray $parents All the parent pages down to the root (homepage). Returns a PageArray. * @property Page $rootParent The parent page closest to the homepage (typically used for identifying a section) * @property Template $template The Template object this page is using * @property FieldsArray $fields All the Fields assigned to this page (via it's template, same as $page->template->fields). Returns a FieldsArray. * @property int $numChildren The number of children (subpages) this page has. * @property PageArray $children All the children (subpages) of this page.* Returns a PageArray. See also $page->children($selector). * @property Page $child The first child of this page. Returns a Page. See also $page->child($selector). * @property PageArray $siblings All the sibling pages of this page.† Returns a PageArray. See also $page->siblings($selector). * @property Page $next This page's next sibling page, or NullPage if it is the last sibling.† See also $page->next($pageArray). * @property Page $prev This page's previous sibling page, or NullPage if it is the first sibling.† See also $page->prev($pageArray). * @property string $created Unix timestamp of when the page was created * @property string $modified Unix timestamp of when the page was last modified * @property User $createdUser The user that created this page. Returns a User or a NullUser. * @property User $modifiedUser The user that last modified this page. Returns a User or a NullUser. * @method string render() Returns rendered page markup. echo $page->render() */ class Page extends WireData { ... Link to comment Share on other sites More sharing options...
SiNNuT Posted July 11, 2012 Share Posted July 11, 2012 I think that would be a great idea. Link to comment Share on other sites More sharing options...
interrobang Posted July 12, 2012 Author Share Posted July 12, 2012 It seems there isnt't very much interest in this. Anyhow, Ryan, would you merge phpdocs like this example into you code if I send you a pull request on github? Link to comment Share on other sites More sharing options...
slkwrm Posted July 12, 2012 Share Posted July 12, 2012 I think this is a really good idea as it will help to adopt PW among PHP developers who use IDEs in their work (such as NetBeans, PHPStorm, Eclipse etc.). As a side effect it can potentially make more people here use IDE. Autocompletion is addictive Link to comment Share on other sites More sharing options...
ryan Posted July 13, 2012 Share Posted July 13, 2012 It all sounds good to me. I'm not against it. Though I don't use PHPDoc or any editor that supports it, so the comments you see in the code have always been for my reference (though I think the style is similar to PHPDoc). I'll be honest, I just can't think in code when I'm surrounded by a IDE that has lots to look at and is trying to do stuff for me. So I stick to VIM, full screen. I haven't figured out how to bring in a pull request without files getting deleted or tabs/linebreaks getting screwed up, so I'd prefer to just make any changes here manually. It sounds like what you are wanting is a @property tag for the class properties in Page.php? I'm happy to do this, but have a concern: most of these properties are not API accessible. You don't want these showing up in your IDE unless you are modifying or extending the Page class (which nobody has done yet as far as I know). Likewise, I think we need to be careful with phpdoc for any PW class properties if the intention is to have them show in your IDE. The reason for this is that the vast majority of API accessible properties are handled through PHP magic methods and not actually properties of the classes themselves. If you use the properties of the classes, you'd be getting an very incorrect view of the API. On the other hand, PHPDoc should be totally fine for public functions. Though there are many public functions that are not part of the public API (meaning, PW classes use them internally, but you shouldn't), so relying on an IDE for this stuff would again give an incorrect view of the API that could get one into trouble. I think it's better to use the cheatsheet and PW API documentation for this stuff. Though maybe there are also some phpdoc tags that can help clarify if a public function is for internal (core use). Link to comment Share on other sites More sharing options...
interrobang Posted July 16, 2012 Author Share Posted July 16, 2012 It all sounds good to me. I'm not against it. Though I don't use PHPDoc or any editor that supports it, so the comments you see in the code have always been for my reference (though I think the style is similar to PHPDoc). I'll be honest, I just can't think in code when I'm surrounded by a IDE that has lots to look at and is trying to do stuff for me. So I stick to VIM, full screen. You can work in fullscreen in PhpStorm, too. But I think a IDE is for advanced programmers like yourself of less use. I only know some PHP basics and I think a IDE can help me a lot to write better code in less time. It sounds like what you are wanting is a @property tag for the class properties in Page.php? I'm happy to do this, but have a concern: most of these properties are not API accessible. You don't want these showing up in your IDE unless you are modifying or extending the Page class (which nobody has done yet as far as I know). I want to add all properties and methods which are currently invisible because they are called via magic methods but are listed in the Cheatsheet. Basically I want the Cheatsheet available in my IDE I think I dont understand what you you are saying about most properties are not API accessible. Likewise, I think we need to be careful with phpdoc for any PW class properties if the intention is to have them show in your IDE. The reason for this is that the vast majority of API accessible properties are handled through PHP magic methods and not actually properties of the classes themselves. If you use the properties of the classes, you'd be getting an very incorrect view of the API.On the other hand, PHPDoc should be totally fine for public functions. Though there are many public functions that are not part of the public API (meaning, PW classes use them internally, but you shouldn't), so relying on an IDE for this stuff would again give an incorrect view of the API that could get one into trouble. I think it's better to use the cheatsheet and PW API documentation for this stuff. Though maybe there are also some phpdoc tags that can help clarify if a public function is for internal (core use). My IDE shows basically the same information as the APIGen documentation. I think there is no need to add better comments to the public methods. Yours work quite well in my IDE. If you are really concerned that we can see public functions that are not part of the public API you can maybe add a @access private or a @internal tag? The offical purpose of the @propery and @method tags is to add documentation for "magic" properties and methods. So I don't think we get a incorrect view of the API. See here: http://manual.phpdoc...operty.pkg.html http://manual.phpdoc...method.pkg.html I haven't completed the phpdoc-comments for all classes yet, but the most important classes are ready: https://github.com/b...f073ad2ea97d03a Link to comment Share on other sites More sharing options...
ryan Posted July 17, 2012 Share Posted July 17, 2012 The offical purpose of the @propery and @method tags is to add documentation for "magic" properties and methods. So I don't think we get a incorrect view of the API. Thanks, this is what I was looking for. This answers my concern. If you are really concerned that we can see public functions that are not part of the public API you can maybe add a @access private or a @internal tag? @internal sounds like what we need! I will put this on my to-do list. Thanks, Ryan Link to comment Share on other sites More sharing options...
interrobang Posted July 31, 2012 Author Share Posted July 31, 2012 Ryan, in my github repo (https://github.com/b31/ProcessWire) all my phpdoc changes are done. Do you want a pull request? Link to comment Share on other sites More sharing options...
ryan Posted July 31, 2012 Share Posted July 31, 2012 Sure, if it's not any trouble that'd be great. I tend to make changes manually (copy/paste or re-type) from pull requests just so I don't miss anything, but actually having the pull request is a good help thanks to GitHub's very clear diff tracking. Link to comment Share on other sites More sharing options...
lpa Posted October 10, 2014 Share Posted October 10, 2014 I can see that the support for magic methods is now in PW source code. But my question is why do I only get $config to give the hints in Eclipse? The other variables like $page, $template, $user don't show the magic method given documentation. Can someone confirm that this works with PW and Eclipse? How to make it happen? Link to comment Share on other sites More sharing options...
lpa Posted November 3, 2014 Share Posted November 3, 2014 Doesn't anybody use eclipse for PW development? I don't find a way to get the content assist in Eclipse to complete the variables like $page or $user. Link to comment Share on other sites More sharing options...
dotnetic Posted July 20, 2015 Share Posted July 20, 2015 How can I integrate this into PHPStorm? I am using version 9 right now. I want the autocompletition so bad. Pls help. Link to comment Share on other sites More sharing options...
interrobang Posted July 21, 2015 Author Share Posted July 21, 2015 You have to help PHPStorm to recognize ProcessWires API vars by including a PHPDoc section in your template file. I created a gist for you which includes all (?) available API vars, simply paste this in your template file: https://gist.github.com/phlppschrr/ea81285bdf56b497193b To get even better autocompletion I can recommend the TemplateStubs module 2 Link to comment Share on other sites More sharing options...
Pierre-Luc Posted August 1, 2015 Share Posted August 1, 2015 This absolutely needs to be merged! Link to comment Share on other sites More sharing options...
LostKobrakai Posted August 1, 2015 Share Posted August 1, 2015 I'm just testing the PHPStorm trial and it would be really nice to be able to use it's full potential. Link to comment Share on other sites More sharing options...
Pierre-Luc Posted August 1, 2015 Share Posted August 1, 2015 As a sidenote though, simply defining the classes will not give the full picture, but a good part of it. Some methods that are added through hooks via modules like PagePermissions or LanguageSupport for the Page object won't be seen. I found this out lately while toying with Reflection classes trying to automate the Cheatsheet. If anyone has any idea how to make this work, I'd be a taker. So far it doesn't seem possible unless the class explicitly adds the methods in its header docblock, and that itself has its own shortcomings. Link to comment Share on other sites More sharing options...
felix Posted August 2, 2015 Share Posted August 2, 2015 I'm not very familiar with the details of phpdoc but this sounds like it would fit your question (look at the answers): http://stackoverflow.com/questions/6395737/how-do-i-make-my-php-ide-understand-dependency-injection-containers 1 Link to comment Share on other sites More sharing options...
theo Posted November 24, 2016 Share Posted November 24, 2016 Not sure if this belongs here and maybe everybody knows it, but I just found out how to use code assistance of Netbeans IDE with Processwire code. Looks helpful to me / for beginners. /* @var $input ProcessWire\WireInput */ or in a class: /** @var ProcessWire\WireArray */ protected $pw = NULL; Hope it helps. Link to comment Share on other sites More sharing options...
Recommended Posts
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 accountSign in
Already have an account? Sign in here.
Sign In Now