Skip to end of metadata
Go to start of metadata

 

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

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.

Icon

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 PHP 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.

Icon

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.

Icon

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:

When we save the template and use New | PHP File context menu (or Alt+Insert / 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.

Icon

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.

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:

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.

  • No labels