I'm trying to follow Zend coding standard for comments blocks for functions and I've stuck during PHP Function Doc Commentcustomization.
This is my current code look
/**
${PARAM_DOC}
#if(${PARAM_DOC})
*
#end
* #return ${TYPE_HINT}
${THROWS_DOC}
*/
The assumption for this is that it should add an asterisk only if ${PARAM_DOC} is not nullable, but this code doesn't work. It always adds an asterisk. The documentation of PhpStorm Variables doesn't contain any useful informations for my problem so I hope that somebody here can help me.
My PhpStorm version is 2019.3 EAP.
As the build-in PhpStorm for ${PARAM_DOC} description says
Parameters' doc comment.
Generated as a number of lines '* #param type name". If there are no parameters, evaluates to an empty content.
And Apache Velocity docs says
When VTL references a variable, such as $foo, the variable can get its value from either a set directive in the template, or from the Java code.
After that I understood that I'm making one important mistake. PhpStorm is based on Java and an empty String cant be automatically casted to Boolean beacuse ${PARAM_DOC} is just a Java String.
So solution for that turned out to be
#if (${PARAM_DOC} != "")
*
#end
Obvious but not quiet.
Related
So if I have a function and in the PHPDoc I specify it'll return a SqsProcessResult object, then I call a function to create a new one of those objects but that function's PHPDoc say return type of Object (as it's a generic factory function) PhpStorm throws up an orange warning.
Can I annotate or otherwise tell PhpStorm the return type will be SqsProcessResult?
Yes, you can .. but due to the nature of the issue it may not be cleanest/elegant solution (at least that's what others may say).
Few options:
#1. Just suppress this inspection for that line.
Place caret in the highlighted area and press Alt + Enter (or get the same menu via "light bulb" icon)
Find the most suitable entry .. and press Arrow Right key (or mouse click on the tiny triangle icon) to expand submenu
Once there -- choose Suppress for statement option -- a new inline PHPDoc comment will be added just above tat line that instructs PhpStorm to ignore that specific Inspection in the next line.
Will be something like this:
/** #noinspection PhpIncompatibleReturnTypeInspection */
return \Yii::createObject(...);
Pros: no warning from IDE side
Cons: extra PHPDoc comment to satisfy IDE (which is needed considering the circumstances)
#2. Use some intermediate variable that you can type hint in place.
Add something like this instead of that existing single line:
/** #var SqsProcessResult $res */
$res = \Yii::createObject(...);
return $res;
Pros: no suppression comment
Cons: extra variable (and still extra PHPDoc comment) for basically no reason
This one mainly can be used in longer methods where such variable (generic Object) will be created in the beginning/middle of the function body and then used later.
#3. Play with .metadata functionality and provide resolution logic for actual \Yii::createObject() (so IDE chooses the right class based on input parameter).
https://confluence.jetbrains.com/display/PhpStorm/PhpStorm+Advanced+Metadata
This is how quite a few tools working: IDE helper for Laravel, Symfony helpers, DI Container helpers etc
I have a number of files in PhpStorm that have one warning in them and I went that green tick! They are all from using BLOB which of course makes sense as load() is not a function set out in my project. Its a base php function from OCI-Lob.
Line of code is:
$zip->addFromString($result['FILE_NAME'], $result['FILE_BLOB']->load());
I have tried adding #var and #method comments (maybe not correctly) in various combinations such as:
/** #var $result['FILE_BLOB'] load */
I do not want to turn off this check project wide of course as its very useful everywhere else. I just want to suppress it for just this line or even better point it in the right direction somehow. It is annoying to have lots of yellow blocks instead of ticks. Maybe I am just fussy about this as the program is obviously unaffected. Does anyone know of any solution or workaround?
You could reference the blob in a separate variable and then put a hint on that variable:
/** #var OCI_Lob $fileBlob */
$fileBlob = $result['FILE_BLOB'];
$zip->addFromString($result['FILE_NAME'], $fileBlob->load());
Since $result['FILE_BLOB'] is an object it will be assigned by reference, so this should not cause a significant increase of your script's memory usage.
An other option would be to hint the whole results array as an array of OCI_Lob objects. Not pretty, but it will probably solve your code inspection issues as well:
/** #var OCI_Lob[] $result */
$zip->addFromString($result['FILE_NAME'], $result['FILE_BLOB']->load());
As far as I know it's not possible (yet) to hint specific array keys in PHPDoc comments, so this is the best I can come up with at the moment.
I searched via Google but couldn't find an answer to this. PhpStorm has many built in annotations for code completion but many are missing as well. I am pretty sure there is a way to create new annotations but couldn't find it anywhere within the settings. Or maybe it is an XML file somewhere. NetBeans has support for this feature.
In other words, how can I create new phpDoc annotations for completion in phpStorm 8 like #usesDefaultClass for phpUnit.
I have found this answer here: http://blog.jetbrains.com/webide/2013/02/phpdoc_and_code_templates/
Hope this will help you
PhpDoc Templates
PhpDoc templates are located under Settings | File Templates | Includes. Currently there are three templates named PHP Class Doc Comment, PHP Function Doc Comment and PHP Field Doc Comment. Any of these can be included into other templates via the #parse directive. For example, we can modify the original class template (Templates | PHP Class) to also include the class PHP Doc when a class is generated:
<?php
#parse("PHP File Header.php")
...
#parse("PHP Class Doc Comment")
class ${NAME} {
}
The same templates are used when:
A new PHP Doc comment is generated after we type /** and press Enter before a class, function (method) or class field.
We invoke Code | Generate | PHPDoc blocks or use the Add PHP Doc quick-fix for the inspection Missing PHP Doc.
Below is a list of variables that can be used in PHP Doc templates:
${NAME}
The element (class, function, field) name.
${NAMESPACE}
The name of the namespace the element belongs to without any leading or trailing backslashes, for example Core\Widgets. The variable value is empty if the element doesn’t belong to any namespace. A check like `#if (${NAMESPACE})` ... is possible.
${CLASS_NAME}
Contains a class name for class methods and fields. Will be empty for functions that do not belong to any class.
${TYPE_HINT}
For functions (methods), contains the return type of the function (method). For fields, evaluates to the field’s type if it can be found, for example, from a default value. Will be empty if the type cannot be retrieved from the code.
${STATIC}
Takes the value of “static” if the function or field is static, otherwise, an empty string. We can use this variable with the condition `#if (${STATIC})` ... to generate something specific for static class members.
${CARET}
Marks the position where the editor caret should be placed after the comment is added. Note: Works only if the comment is added after we type “/**” and hit Enter. Should be placed inside the comment, not on the first line /** or on the last line */. In all other cases the caret marker will be ignored.
${PARAM_DOC}
A generated PHP Doc fragment containing function (method) parameters in the form: “* #param type $name“. For example, if the function signature is foo ($x, $y), it will evaluate to:
#param $x
#param $y
${THROWS_DOC}
A generated PHP Doc fragment containing exceptions thrown from function (method) body in the form * #throws ExceptionName. One exception per line/#throws tag. For example:
#throws DOMException
#throws HttpException
Code Templates for Overridden/Implemented Methods
The following templates can be found under Settings | File Templates | Code: PHP Implemented Method Body and PHP Overridden Method Body. There are few parameters, considering that in most cases we will need either a simple call to a parent method or just our own comment (some version of TODO perhaps):
${NAME}
Method name.
${PARAM_LIST}
A comma-separated list of parameters. For example, if the original method signature is foo(Bar $bar, $y), the variable will take the value “$bar, $x” which can be used in a call to the parent method as `${NAME}(${PARAM_LIST})`”
${RETURN}
Either “return” or an empty string.
A Dollar Sign Variable: ${DS}
Solves the problem of putting a dollar sign $ anywhere within the template. Actually, the dollar sign is used both in PHP and in Velocity template engine taking care of code generation behind the scenes. So whenever we need a dollar sign, just use ${DS} as its equivalent. For example, if we want $this->foo() to be generated, we need to put ${DS}this->foo(). This may not look perfect but guarantees that there will be no conflicts.
In my code I use Registry pattern like that:
$data = Registry::get('classA')->methodOfClassA($param1, param2);
Registry class stores instances of some classes in internal array, so in any place of my code I can call class methods for handy functions like in line above.
But, the problem is that PHP-storm does not autocomplete when I type:
Registry::get('classA')->
And, that is worse, it does not go to declaration of the method "methodOfClassA" when I hover mouse cursor holding mac-button (analogue of control-button on windows)
I suppose, that IDE AI is not so good to recognise cases like that, but maybe there is some tricks to do that in a hard way? hardcoding classes+method names in some file and so on...
At least, I want it to understand to go to method declaration when I click method name...
Any advices?
http://confluence.jetbrains.com/display/PhpStorm/PhpStorm+Advanced+Metadata
This link describes it all -- it is already used by multiple projects/frameworks/code-generation helpers, like Magento, for example (some other can be found mentioned in the comments of the actual ticket).
For other situations you may want to check out DynamicReturnTypePlugin plugin (Settings | Plugins | Browse repositories...) -- have not tried myself and therefore cannot comment how good/fast/laggy it is.
You can always indicate the variable type in two steps:
/** #var $foo MyClass */
$foo = $this->get('MyClass');
$foo->bar(); // autocomplete works
Is there a way to customize php storm's way of generating the docblocks ?
By default, I would like to have unknown type vars considered as strings.
This is the default way of generating docblock
(using php storm 4.01)
/**
* #param $name
*/
private function test($name){
}
And I would like this instead if possible :
/**
* #param string $name
*/
private function test($name){
}
No, you cannot provide default type for generated #param.
PhpStorm provides correct type whenever it is possible to detect from function declaration. In your example it is not possible (it can be anything).
And I personally do not see a real reason why it needs to be a string (or any other type) by default. Unknown/missing type tells me that I need to finish editing this PHPDoc block so it reflects the actual/correct parameter type. With default type entered already such check is not possible (what if the type should be some class (e.g. Person) or array instead?)
P.S.
Kind of related (at least to the actual subject):
This is the Feature Request ticket for Editable PHPDoc Template (that can define what #tags and in what order should be used): http://youtrack.jetbrains.com/issue/WI-11111