Currently Being Moderated

Command Line Tools Support

VERSION 3

Created on: Jan 21, 2011 5:10 PM by Elena Shaverdova - Last Modified:  Feb 4, 2011 4:51 PM by Elena Shaverdova

Introduction

Command Line Tool Support is  designed to enable usage of command line tools of various frameworks inside the IDE.

 

From this tutorial you will learn:

  • How to execute commands in the console.
  • How to load a standard external framework.
  • How to create a Symfony project.
  • How to execute Symfony commands and use the Output console interactively.
  • How to create a custom framework description:           
    • How to create a framework commands description xml file.
    • How to define framework commands in the description file.

 

 

Prerequisites

To complete this tutorial you need PHPStorm 2.0 or higher  installed on your computer.

 

Console Commands

First of all, let's consider some examples of running console commands. Console commands can be executed, with the working folder in the root of your project. Invoke the tool with Ctrl+Shift+X and try:

echoJavaHomePopup.png

The command output is shown in the dedicated tab:

echoJavaHomeToolWindow.png

 

Macros are also supported, so you can use $ProjectFileDir$ instead of the full path to the project, or $PhpExecutable$ instead of the php configured in the project settings, and so on. Another useful macro $Prompt$ which displays a string input dialog. Example of macro usage:

phpVersionPopup.png

Macro is replaced with actual value:

phpVersionToolWindow.png

Loading a Standard External Framework

Now it’s time to let’s add support of a framework to get use of its commands. Let’s, for example, load Symfony.

  1. First of all, download the required Symfony version (1.1 or newer).
  2. Choose Settings | Command Line Tool Support and press the Add button. Three options are offered:
  3. frameworkToAddOptions.png

  4. Choose Symfony and provide the path to its $Symfony_home$/data/bin/symfony file. The description of Symfony commands is loaded and saved in a file inside your project settings . In the Settings dialog box, the description looks as follows:

 

symfonyLoaded-2.png

    • The Tool Path field contains the common part of all framework commands. These common parts are “php  $path_to_symfony$ “ in Symfony or  “$Zend_Framework_Tool_home$/bin/zf.bat” in Zend Framework Tool.
    • A common Tool Path can be annoyingly long, so we provide an Alias, which is a string to be used instead of the full Tool Path.
    • By selecting or clearing the Enable checkbox, you can easily have framework commands included or excluded from tool’s auto completion without deleting the description file. Now the Enable checkbox is selected, so symfony commands are provided in auto completion:

symfonyAutocompletion.png

 

Using Symfony

First of all, we need to create a Symfony project, which is a mandatory prerequisite for executing Symfony commands.

 

Creating a Symfony Project

Press Ctrl +Shift+X and type:

symfonyGenerateProject.png

The command has two parameters:

  • Mandatory name
  • Optional author

Before the command execution, the $ProjectName$ macro will be exploded to the actual project name, and the framework alias s will be changed to Invoke Path. In our case, it is ""C:\php\php.exe" C:\sf\data\bin\symfony”.

 

Running Symfony Commands

Now that we have a Symfony project, let’s see how we can use Symfony commands.

 

Creating a Frontend Application

To start, let’s create a frontend application without escaping output.

Press Ctrl +Shift+X and type:

symfonyGenerateAppOption.png

Note that options after commands are also supported. In our case the --escaping-strategy=false option defines that output is not escaped.
The command execution result is displayed in the Output console.

 

Using the Output Console Interactively

The Output console is interactive. To see how to derive advantage from this possibility, let’s run the command that removes the data available through a configured data source.
Press Ctrl+Shift+X and type:

doctrineDropDb.png

The Output console informs about the possible consequences of executing the command and asks you to confirm or reject your decision by pressing y or N:

symfonyDropDb 2.png

 

Loading and Enabling a Custom Framework

As you can see, command loaders are provided only for Symfony and  Zend Framework Tool. You might ask, “What about other frameworks? “.  Other frameworks and tools are supported via custom framework descriptions. You can create and load an xml file where the required commands will be stored, just like Zend Framework Tool and Symfony commands. Let’s create a definition for the Pear tool.

 

Creating a Custom Tool Description

  1. Choose Settings | Command Line Tool Support, press Add, and select Custom Framework.
  2. Name the framework Pear,  specify pear as the Alias and the Invocation Path. If pear is not in your $PATH, set the Invocation Path to its path.
  3. pearCreation.png

  4. After you save the settings and close the Command Line Tool Support dialog box, a description file Pear.xml is created and opened in the editor.  Let’s consider the structure of the framework description with more details.

 

Exploring Framework Description

The file contains only a framework element with the following contents:

The attributes invoke, alias and enabled correspond to the values specified in the Command Line Tool Support dialog box. They are mandatory and should not be empty.

  • The name attribute corresponds to the name of the framework and its definition file.
  • The version attribute shows the version of commands description.

The name and version attributes should never be changed manually.

  • Optionally, the framework element can have a help child. Its content is shown in the documentation window invoked by Ctrl+Q when only the framework alias is typed.

Now let’s add a command definition to the description.

 

Adding Commands to Framework Description

Any command is described in the command child of the framework element. The command element itself  has the following children:

  • name – the command itself, mandatory, and non-empty;
  • help - an optional element, contains the text of the help message for command;
  • params – the command parameters and their default values.

 

Let’s define the config-get command.

firstPearCommand-2.png

The text of the command is:
<command>
    <name>config-get</name>
    <help>pear config-get [options] parameter [layer]&lt;br/&gt;Displays the value of one configuration parameter. The&lt;br/&gt;first argument is the name of the parameter, an optional second argument&lt;br/&gt;may be used to tell which configuration layer to look in. Valid configuration&lt;br/&gt;layers are &quot;user&quot;, &quot;system&quot; and &quot;default&quot;. If no layer is specified, a value&lt;br/&gt;will be picked from the first layer that defines the parameter, in the order&lt;br/&gt;just specified. The configuration value will be retrieved for the channel&lt;br/&gt;specified by the default_channel configuration variable.&lt;br/&gt;&lt;br/&gt;Options:&lt;br/&gt; -c CHAN, --channel=CHAN&lt;br/&gt; show configuration variables for another channel&lt;br/&gt;</help>
    <params>parameter layer[=null]</params>
</command>

 

In this example, the command element has the following children:

  • name – config-get, mandatory, and non-empty;
  • help - optional;

 

  • params – the config-get command has two parameters:     
    • The parameter parameter does not have a default value and therefore is mandatory.
    • The layer parameter  has a default value and therefore can be omitted.

    Commands without parameters may omit the params element. The default value of a parameter  may use IDE macro. Then all omitted parameters before it will be provided by their default values, and the macro will be exploded before execution. These are the only circumstances when provided default values are used. That`s why the Symfony description is safe to set the default values of all optional parameters to null.

Let’s invoke the new command to make sure its definition works:

pearConfigGet.png

Then let’s get the help on the command with Ctrl+Q:

pearHelp.png

Note that files with commands are saved and reloaded each time you invoke auto completion in the Command Line Tool Support popup.
The only thing left is copy other commands and framework help from the attached file. Now Pear support is ready to use.

 

Editing Framework Description

Some frameworks, for example, Symfony allow creating custom tasks. As a result, you need to change the framework description accordingly.

Let’s create a simple hello task inside a Symfony project. We suppose that you have previously loaded and enabled Symfony and created a Symfony project.

  1. Press Ctrl+Shift+X and type:
  2. symfonyGenerateTask.png

    A new task class helloTask is created inside the lib/task directory.

  3. Open the helloTask class in the editor and make the  following simple changes to its execute function:
  4.  

    helloTaskCode.png

  5. Open the Symfony description file: choose Settings |  Command Line Tool Support and press the Open definition in editor button.
  6. Add a new hello command description:
  7. symfonyNewTaskDescription.png

    Command description :
    <command>
        <name>hello</name>
        <help>My first task with no parameters.</help>
    </command>

     

  8. To test the new command, type:
  9. invokeNewCommand.png

    The result of executing the command is shown in the Output console:

    HelloTaskOutput.png

 

Troubleshooting

If you get any  troubles while editing description file  and auto completion does not offer you expected commands, open the Validation tab of Command Line Tools Console. This tab shows  info about problems with parsing description files. You can also get information about the description format from schema file at .idea/commandlinetools/schemas/frameworkDescriptionVersion1.1.xsd.  Its path is provided in the generated description file, and the editor validates the file against the schema automatically.

Attachments:
Average User Rating
(0 ratings)




LEOPiC LEOPiC  says:

Is there a chance of running commands using WebStorm and not PHPStorm? I'm thinking compiling .sass/.scss files and the like

Dmitriy Zavalkin Dmitriy Zavalkin  says in response to LEOPiC:

Look on Settings->External Tools.

Luis Cordova Luis Cordova  says:

is there a way to make a chain of commands like if i want to do in sequence git add . && git commit -a "custom message"

 

please let me know

More Like This

  • Retrieving data ...

More by Elena Shaverdova