I use docblocks to typehint class properties, and only recently realised that class properties may be grouped as such:
/**
* #var string
*/
private $firstname, $surname, $location;
Which is way easier to read, and shorter, than this:
/**
* #var string
*/
private $firstname;
/**
* #var string
*/
private $surname;
/**
* #var string
*/
private $location;
Would there be any reason not to do this?
I prefer 1st approach, because PSR-2 says "There MUST NOT be more than one property declared per statement.". There are good reasons for that, and here are some of my thoughts I guess authors of PSR-2 had too:
people don't expect to see more than one declaration per line (at least me and my collegues);
it's more difficult to change type of a variable, e.g. of $location from string to a Location class.
it's more difficult to read diffs: the line will be marked as changed by VCS if name of any variable changes, and reviewer will have to read the whole line. Such line has higher probability of changing;
it's not easy to comment a single variable from a group.
Related
I want to add a type of object in #property-read and also be able to access its attributes with PhpStorm suggestions.
Here's what I would like to do:
/**
* #property-read object{type: string, schema: string} $request_schema
* #property-read object{type: string, schema: string} $response_schema
*/
class ConfigApiRoutesSchema extends BaseSchema
{
...
}
The reason I'm doing this is because I want to access the attributes type and schema, like this:
$configApiRoutesSchema = new ConfigApiRoutesSchema();
$configApiRoutesSchema->request_schema->type // Here's the problem, type is not suggested
$configApiRoutesSchema->request_schema->schema // schema is also not suggested
This is exactly what I need, but unfortunately this doesn't work for some reason. One solution is to create two classes and specify them as types:
/**
* #property-read string $type
* #property-read string $schema
*/
class RequestSchema {}
/**
* #property-read string $type
* #property-read string $schema
*/
class ResponseSchema {}
/**
* #property-read RequestSchema $request_schema
* #property-read ResponseSchema $response_schema
* #
*/
class ConfigApiRoutesSchema extends BaseSchema {}
Now PhpStorm suggests both schema and type.
But it doesn't seem correct, since RequestSchema and ResponseSchema won't actually be used. So I wonder if there's any way of using annotation with objects without having to create a class to suggest its attributes.
Thank you.
Altho it is possible to specify the shape of arrays, for objects it is not possible to do so (yet). Such a syntax would have been be specified in PSR-5 and PSR-19, but this is not the case.
In the same manner it is not possible to specify the properties of a returned plain object from a method with the #return object annotion.
Apparently the syntax is supported by Psalm, but not in PhpStorm (at very least not yet).
Currently there is a public proposal on the PhpStorm YouTrack board. You might want to upvote that issue to increase it's chance of being included in the next PhpStorm version.
Is it possible to declare protected or private class #property using PhpDoc?
/**
* Class Node
* #package app\models
* #property string $name
*/
class Node
{
}
I don't think so. For #property, public is implied, even if it's read-only or write-only. The point of such tags is about documenting interfaces that can't be inferred. A private/protected variable is really internal to the class so it's only relevant to child classes which should be written as if they already know this. You can still leave a plain docblock immediately before you declare it, though.
I'm trying to document PHP class members with Doxygen (I'm not using PHPDocs because the project involves COCOA programming, so I can use the same tool for both parts).
/**
* This is brief description.
*
* This is detailed description.
*/
private $foo;
This code gets the documentation done right, but I would like to include in the docs the type the var should handle.
I tried to use \var and \property, but then Doxigen does not generate the doc for the var.
//THIS IS NOT WORKING!
/**
* This is brief description.
*
* This is detailed description.
* \var int
*/
private $foo;
I have seen this post:
Doxygen: how to describe class member variables in php?
Seems that \var is not working in Doxyegn, but the post is a bit old and maybe there is something I can do now.
I have follow the bug comments of this feature:
https://bugzilla.gnome.org/show_bug.cgi?id=626105.
In comment number 6 a solution is proposed, adding the var name after the type.
class Mine {
/**
* Definition of variable
* #var string $var
*/
private $var = array();
}
This is working for me.
Simple workaround which generates acceptable results is to add this input filter:
INPUT_FILTER = "sed -e 's/#var\s/#see /'"
Or even better to define an alias:
ALIASES += "var=#see"
It simply replaces #var command with #see command. It is not perfect, but it is very simple and relatively bulletproof.
Small disadvantage is that the type is somewhere in the description instead of the heading. On the other side, if only few properties has type defined, it makes documentation more consistent (headings look the same).
#type works for me:
/** #type string[] */
private $csvData;
/**
* command line parameters
* #type string[]
*/
private $parameters;
I recently started to add comments on properties declaration on my php classes. The main reason is that without thoses comments, NetBeans don't understand what to do with the properties and so i get no autocompletion. Here what it looks like :
/**
* #var MyClass what blabla about the instance.
*/
public $myClassInstance;
The question is : when I have more then 1 instance of the same class instanciated on properties, is there a way to "multi-comment" ? using only once #var for every property under it ? (as follow)
/**
* #var MyClass what blabla about the instance.
*/
public $myClassInstance;
public $myClassInstance2;
Ok, it seems stupid to do that at once, but it comes handy when declaring primary types for exemple, so it'll looks better and have less "trash" :
/**
* #var Integer blabla
*/
public $index;
public $start;
public $end;
I assume netbeans uses the phpDocumentor. From the docs it doesn't result that such a thing is possible.
There's no official standard for phpdoc comments, and especially their interpretation by IDEs. Probably your best bet in this case would be to have #var phpdoc for each variable separately.
Ok, thanks for your answers :) finally I ended up doing one line comments using Phpdoc structure like that :
/** #var Professionnel */
protected $auteur;
/** #var Categorie */
protected $categ;
So I have both things I looked for : less comments and autocomplete :)
Is there a way to hint WebIDE that a variable has some type?
I have to iterate an array of objects, and there's no auto-completion available.
This helps in ZendStudio:
/* #var ClassName $object */
I know there's a feature in JetBrains to declare an array of objects:
/**
* #return ClassName[]
*/
But this works only with function's return type.
/* #var ClassName $object */ is a non-valid PHPDOC comment and is not parsed in the current version of Web IDE. Use double asterisks to make it work:
/** #var ClassName $object */
Also, you can annotate $array in foreach($array as $var) with /** #var ClassName[] $array */ and $var type will be deduced automatically.
As already pointed out, PhpStorm will use regular phpdoc blocks:
/** #var ClassName $object */
However, since 2.1 it also supports Netbeans/Eclipse/Zend #var annotations:
/* #var $object ClassName */
Please note the comment starts with /* rather than /** (thus it won't show up if you generate actual documentation with phpdoc). Also, the arguments are swapped, though PhpStorm accepts any order:
/* #var ClassName $object */
Last but not least, they can precede almost any arbitrary line of code (technically, phpdoc blocks are restricted to certain items).
Edit: as of 2019, Netbeans/Eclipse/Zend #var annotations seem to be mostly abandoned. NetBeans 11 no longer supports them and in general they aren't supported by other IDEs. I suggest to use the other syntax.