File Templates in PhpStorm

Tweet
When creating new files in PhpStorm, for example using the New | PHP File context menu, PhpStorm typically generates some default
contents for that file, for example a copyright header. This content is generated by File Templates. In this tutorial, we will see what these are
and how we can use them in our own projects.
File and Code Templates
Templates
Includes
Code
Creating and Modifying File and Code Templates
Using Velocity constructs in a Template
Prompting for Input when using a Template

File and Code Templates

PhpStorm ships with a number of File Templates. We can find them under IDE Settings | File and Code Templates. We can see the templates
that are available: there are templates for HTML files, HTML5, JavaScript, TypeScript and CoffeeScript, PHP and so on. I've also added one of
myself: Smarty Page for generating pages using the Smarty templating engine.
Templates can be created for any language, even languages not supported by the IDE. If it should be easy to add a readme.txt file to
our projects, we could create a File Template for that. If for some reason we would need to be able to quickly add an authors.xml file in
which our current username should be stored, we could do so too.

There are several tabs available: Templates, _ Includes_ and Code. These different tabs provide access to the different types of File and Code
Templates that are available and can be extended. Let's see what these types all mean.

Templates
The Templates tab contains the various file templates that are available when using the New | PHP File context menu (or Alt+Insert / CMD+N on
Mac OS X). They all generate a complete file and can contain plain text, #Includes (using the #parse directive) and special variables that will be
substituted in the resulting file. We'll see what these are in the #Creating and Modifying File and Code Templates section of this tutorial.

When we select a template, we can see its contents.The PHP File template, for example, contains nothing but a PHP open tag and renders the P
HP File Header.php #Include.

Includes
The Includes tab contains partial templates. An include can not be generated on its own, but can be used and re-used in various templates. They
can contain plain text, other #Includes (using the #parse directive) and special variables that will be substituted in the resulting file. We'll see what
these are in the #Creating and Modifying File and Code Templates section of this tutorial.

Code
The Code tab contains a special kind of templates. In the Generating Code section of the Working with the PhpStorm Editor Actions and
Navigation tutorial, we've seen that we can generate code within the editor, for example getters and setters in a PHP class. While we can not
create new code templates, we could alter them so code is always generated the way we like it.

Code templates can contain plain text, #Includes (using the #parse directive) and special variables that will be substituted in the resulting file.
We'll see what these are in the #Creating and Modifying File and Code Templates section of this tutorial. When selecting a code template, we can
see a number of additional pre-defined variables are available for use in our template.

Creating and Modifying File and Code Templates

PhpStorm uses the Velocity Template Language (VTL or just "Velocity") template language for File and Code templates, which supports various
constructs. We can add fixed text like markup, code and comments. We can use file template variables such as ${PROJECT_NAME} or ${FILE_
NAME} that will be replaced in the generated file with our project's name or the file name. Check the web help for a full list of available variables
for the various templates.
One character we may need in our PHP templates is the dollar sign ($). Since the Velocity template language also used the dollar sign
to denote a variable, we have to somehow escape it in our templates. We can use the ${DS} variable instead of just $ in our PHP
templates (or other templates where we need a $ printed).
Let's update one of the #Includes. Open the IDE Settings | File and Code Templates and click the Includes tab. We want to change the PHP
File Header that is being generated at the start of every PHP file that is generated. We can edit the template directly on the right.
If a backup of a template is needed, we could use the Copy Template button from the toolbar to create a copy first.
Instead of the default, let's change the PHP File Header template to:

/**
* ${PROJECT_NAME} - ${FILE_NAME}
*
* Initial version by: ${USER}
* Initial version created on: ${DATE}
*/

When we save the template and use New | PHP File context menu (or Alt+Ins
ert / CMD+N on Mac OS X) and pick the PHP File or PHP Class template, the
file that is generated now contains our modified header.

Creating File Templates can also be done from within the Editor. After
opening a file we want to use as a File Template, we can use the Tools
| Save File as Template... menu to export it as a File Template.

Using Velocity constructs in a Template

So far, we have seen our templates can contain plain text, #Includes (using the #parse directive) and variables that will be substituted in the
resulting file. The Velocity Template Language supports other constructs like if, foreach, etc. as well. A good example can be seen in the PHP
Class file template: when a namespace is defined, the generated file will contain a PHP namespace declaration. If not, it will be omitted.

<?php
#parse("PHP File Header.php")
#if (${NAMESPACE})
namespace ${NAMESPACE};
#end
class ${NAME} {
}

Prompting for Input when using a Template

Depending on what we want to achieve, we may want to prompt for input to a template. Imagine we wanted to create a File Template that can
generate a composer.json file. Our template could look like the following:

{
"name": "${USER}/${PROJECT_NAME}",
"description": "${Description}",
"minimum-stability": "dev",
"license": "proprietary",
"authors": [
{
"name": "${Author}",
"email": "${AuthorEmail}"
}
]
}

We're using some of the pre-defined variables: ${USER} will populate the template with the current username, ${PROJECT_NAME} will populate
the template with the current project name. However, where will ${Description}, ${Author} and ${AuthorEmail} come from?
When using a template that contains unknown variables, PhpStorm will prompt for them when creating a file based on the template.

The file that is generated using the template will contain the values that were entered by the user.

Tweet