How to create new phpDoc annotations in PhpStorm 8

Question

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.

Answer 1

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.