New Customizable Templates in PhpStorm 6 for Doc Blocks and Code
PhpStorm 6 brings a new set of customizable templates for PhpDoc blocks and overridden/implemented method body. Now we can decide what content these parts of code will initially have when they are generated automatically.
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: |
| ${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: |
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.
Still Need More?
Feel free to file a feature request in our issue tracker YouTrack. We appreciate any improvement suggestions!
