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 :)
Related
This is a question about the autocompletion behavior in PhpStorm (and possibly other IDEs) in conjunction with PHP docblocks.
I have to groups of classes in my application. First there are individual classes for various products (CarProduct, FoodProduct etc.), all inheriting from BaseProduct, and the counterpart for individual contracts (CarContract, FoodContract etc.), all inheriting from BaseContract.
<?php
class BaseContract
{
/** #var BaseProduct */
private $product;
/**
* #return BaseProduct
*/
public function getProduct()
{
return $this->product;
}
}
Now I have an instance of CarContract, and I wanna get some CarProduct specific information:
<?php
/* PhpStorm thinks, this is BaseProduct */
$product = $carContract->getProduct();
/* hence, getSpeed() is not available for PhpStorm */
$product->getSpeed();
The autocompletion is not working as I like. There are two workarounds for this, but both are not nice:
Overload getProduct() in the subclass, just with updated #return docblocks
Add /** #var CarProduct $product */ everywhere, where I access the product of a CarContract
Is there a "usual" way to solve something like this, or are my workarounds the only solutions?
PhpStorm does not really allow/does not support doing something like: have the same named class defined elsewhere and just use it as a reference for overriding definitions of real class. You can do that .. but IDE will warn with "multiple definitions of the same class" and it may introduce some weird behaviour/unexpected warnings...
Here is a ticket that ask for such feature: https://youtrack.jetbrains.com/issue/WI-851 -- watch it (star/vote/comment) to get notified on any progress.
Your options are: you can provide correct type hint locally (to local variable) using #var -- you already know it and that's first that you would think of:
<?php
/** #var \CarProduct $product */
$product = $carContract->getProduct();
$product->getSpeed();
Another possible way: instead of overriding actual method .. you can try doing the same but with #method PHPDoc -- will work with your code:
<?php
/**
* My Car Product class
*
* #method \CarProduct getProduct() Bla-bla optional description
*/
class CarContract extends BaseContract ...
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.
How do I enable code completion for clases and methods I create in code for in netbeans 8.
Thanks,
Dion
You really should google this kinda thing, but I'm in the mood to answer a question :-)
Anyway, most IDE's read your code in pretty much the same way. I can't attest to NetBeans specifically (I use PHPStorm), but the general idea is to make sure you add docblocks to your classes, methods etc. The IDE reads these and can then provide decent code-completion.
<?php
namespace App;
/**
* Class MyClass
* Does some stuff
* #package App
*/
class MyClass extends SomeOtherClass
{
/**
* This is my var
* #var string
*/
public $myVar = 'some val';
/**
* This is my method
* #param string $yourString
* #return SomethingElse
*/
public function myMethod ($yourString)
{
$this->myVar = $yourString;
return new SomethingElse($this->myVar);
}
}
Have a look at the PHPdoc site for the tag syntax. Most IDE's will also have a way of generating this for you as well.
What is PHP Anotations and where can I learn more about it? I need simple example to understand it. I have googled around alot. Somehow i reached this point:
Example Code:
<?php
class AddressShipment{
/* Attributes of AddressShipment */
/**
* private TypePlaceShipment type
* #ORM\Id #ORM\Column #ORM\GeneratedValue
* #dummy
* #var long
*/
private $type;
/**
* private boolean lift
* #ORM\Column(type="boolean")
* #Assert\NotEmpty
* #var boolean
*/
private $lift;
/**
* private String comment
* #ORM\Column(type="string")
* #Assert\NotEmpty
* #var string
*/
private $comment;
?>
Can someone explain this a bit ? What are PHP Anotations? How can we use it ? What is the purpose of using it ?
It is basically for documentation generation.
Also IDEs which support php look up the annotations and give you information on what the function does, what it returns, what parameter it takes.
So if you make a php library, another person can read the annotations easily to know what it does without having to dig through your code and his IDE will recognize those annotations
here is an example of netbeans using this annotation from a function somewhere
You can learn by visiting this link:
http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_elements.pkg.html
Aside from providing documentation (e.g. http://www.phpdoc.org/ ) and providing hints for the IDE, some libraries use annotations to determine how to handle classes. One example is Doctrine which provides an Object Relational Mapper that can map objects to a database based on annotations (using its database abstraction layer).
In the given code fragment I recognize #ORM\Id, #ORM\Column and #ORM\GeneratedValue as some of the annotations that Doctrine uses. However, AddressShipment is not declared as an Entity with the appropriate annotation, so they're not correctly used for that purpose.
Zend Framework 2 utilizes Doctrine's annotation library to enable the creation of forms from annotations (including validations and filtering).
Under the hood Doctrine uses reflection to read these annotations. If you use annotation-dependent libraries in combination with certain PHP accelerators, then you need to take care to configure the accelerator not to discard the annotations when it caches the code.
(Take note before reading that in fact I know you are talking about how to use some php ORM framework documentation tags and where to find what they mean).
Annotations are just annotations in PHP world they are called "PHPDoc Tags" but unfortunately they are used for nothing more than some PHP IDE code autocompletion / intellisense / documentation generation.
PHPDoc by itself is a standard that raised from nowhere but opensource php documentation project many years ago and was positively received from php community and now even php reflection class supports them.
For example phpdoc tag #return specifies what will be php class method return type or php function return type.
#var specifies what is property type. PHPDoc has its own declaration rules. For example documentation must begin with /** and must and with */. You can find this standards on http://en.wikipedia.org/wiki/PHPDoc#Tags link.
In example below all tags with # symbol are legal and might be treated by some PHP IDE like Netbeans or Eclipse or even Sublime sometimes. But:
class planet
{
/**
* primary
* length 16
* #var string
*/
public $name;
/**
* type smallint
* #var integer
*/
public $order;
/**
* #var boolean
*/
public $water;
/**
* #var \galaxy\star
*/
public $star;
/**
* enum
* #var \galaxy\moon
*/
public $moons = array ();
But what is interesting in your question is that you also mentioned #ORM. This means you are using some ORM framework probably Doctrine with Symphony and you need to find what does these annotations mean for specific framework. This can be found easily in specific framework's documentation. They are so many that there is no clue to post them on here.
For example if you are planning to use Doctrine you can visit here http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/tutorials/getting-started.html
Or if you are using single file framework db.php which is database first style also and uses annotations as well you can visit here http://dbphp.net.
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;