Command Line Interface
======================

Overview
--------

Many of the tasks that a developer executes during the building and maintenance of a web application can be handled by symfony's Command Line Interface (CLI). [Chapter 16](http://www.symfony-project.com/book/trunk/16-Application-Management-Tools) describes some of these tasks in detail, while this chapter lists them all with a brief description.

CLI core
--------

The `symfony` script is a PHP script that lies at the root of a project. The symfony command expects tasks, and some tasks require additional parameters. To call it, use the following syntax:

    $ cd myproject
    $ php symfony <TASK> [parameters]
    
>**Note**: The symfony CLI works only from the root of a symfony project

The [symfony sandbox](http://www.symfony-project.com/book/trunk/03-Running-Symfony#Installing%20the%20Sandbox) contains executables for Windows and *nix platforms that should allow an even faster call:

    $ ./symfony <TASK> [parameters]      #  *nix
    $ symfony <TASK> [parameters]        #  Windows
 
The examples of this chapter will use the `php` executable, but you can omit it if your project has the proper executables. 

To list all the possible tasks, call:

    $ php symfony

To display the installed version of the symfony package, type:

    $ php symfony -V

A few tasks have a shortcut, faster to write, that has the same effect.

    $ php symfony cc
    // does the same thing as
    $ php symfony clear-cache
    
When an exception occurs, you might want to get the stack trace and detailed explanation. Add the `-t` option before the task name to get the trace.

>**Note**: For the records, symfony uses a dedicated tool called [Pake][1] to manage common tasks. Pake is a php tool similar to the [Rake][2] command, a Ruby translation of the `make` command. Pake was built by the symfony team. It automates some administration tasks according to a specific configuration file called `pakefile.php`. But since you use the `pake` tool just by typing `symfony` in a command line, you don't even need to learn what pake does and how it works..


CLI tasks
---------

### Structure generation

    $ php symfony init-project <PROJECT_NAME>
    
Initializes a new symfony project (shortcut: `new`).
          
    $ php symfony init-app <APPLICATION_NAME>
    
Initializes a new symfony application (shortcut: `app`).    

    $ php symfony init-module <APPLICATION_NAME> <MODULE_NAME>
    
Initializes a new symfony module (shortcut: `module`).

    $ php symfony init-batch <SKELETON_NAME> [...]

Initializes a new batch file (shortcut: `batch`). You must select a batch skeleton to init, and then follow the prompts.

    $ php symfony init-controller <APPLICATION_NAME> <ENVIRONMENT_NAME> [<SCRIPT_NAME>] [true|false]

Initializes a new controller (shortcut: `controller`). The default script name follows the symfony convention.

Find more about these commands in [Chapter 16](http://www.symfony-project.com/book/trunk/16-Application-Management-Tools).

### Model generation

    $ php symfony propel-build-model

Generates the Propel classes for the current model, based on the schema files (YAML or XML) of your `config/` directory.

The connection settings used by the following commands are taken from the `config/propel.ini` configuration.  
    
    $ php symfony propel-build-sql
    
Generates the SQL code to create the tables described in the `schema.yml`, in a `data/schema.sql` file.

    $ php symfony propel-build-db
    
Creates an empty database based on the connection settings.    

    $ php symfony propel-insert-sql
    
Inserts the SQL code from `data/schema.sql` into the database.    
    
    $ php symfony propel-build-all

Executes `propel-build-model`, `propel-build-sql` and then `propel-insert-sql` all in one command.

Find more about these commands in [Chapter 8](http://www.symfony-project.com/book/trunk/08-Inside-the-Model-Layer).

### Schema management

    $ php symfony propel-build-schema [xml]
    
Creates a `schema.yml` from an existing database. If the `xml` parameter is added, the tasks creates a `schema.xml` instead of the YAML version.

    $ php symfony propel-convert-xml-schema
    
Creates YAML versions of the XML schemas found.
  
    $ php symfony propel-convert-yml-schema
    
Creates XML versions of the YAML schemas found.

### Data management

    $ php symfony propel-load-data  <APPLICATION_NAME> [<ENVIRONMENT_NAME>] [<FIXTURES_DIR_OR_FILE>]
    
Loads all data from default `data/fixtures/` directory unless otherwise specified. Environment is default to `dev`. The fixtures directory must be specified relative to the project's data dir, for example `fixtures` (default) or `testdata` or specify a single file `fixtures/file.yml`.    

    $ php symfony propel-build-all-load  <APPLICATION_NAME> [<ENVIRONMENT_NAME>] [<FIXTURES_DIR_OR_FILE>]

Executes `propel-build-all` then `propel-load-data`. Accepts same arguments as `propel-load-data`.

    $ php symfony propel-dump-data  <APPLICATION_NAME> <FIXTURES_DIR_OR_FILE> [<ENVIRONMENT_NAME>]
    
Dumps database data to a file in the fixtures directory in YAML format.

### Development tools

    $ php symfony clear-cache [<APPLICATION_NAME>] [template|config]

Clears the cached information (shortcut: `cc`) (find more in [Chapter 12](http://www.symfony-project.com/book/trunk/12-Caching)).

    $ php symfony clear-controllers
    
Clears the web directory of all controllers other than ones running in a production environment. Very useful before deployment to the production server.

    $ php symfony fix-perms
    
Fixes directories permissions, to change to `777` the directories that need to be writable. The permission can be broken if you use a checkout from a SVN repository.

    $ php symfony freeze
    $ php symfony unfreeze

Copies all the necessary symfony libraries into the `data/`, `lib/` and `web/sf/` directories of your project. Your project then becomes a kind of sandbox, i.e. a standalone application with no dependence and ready to be transferred to production via FTP. Works fine with PEAR installations as well as symbolic links. Unfreeze your project with the `unfreeze` task.

    $ php symfony sync <ENVIRONMENT_NAME> [go]
    
Synchronises the current project with another machine (find more in [Chapter 16](http://www.symfony-project.com/book/trunk/16-Application-Management-Tools#Deploying%20Applications)).   

### Tests

    $ php symfony test-unit <UNIT_TEST>
    
Launches a unit test located in the `test/unit/` directory. The parameter can be the name of a single unit test file (omitting the `Test.php` suffix), a group of unit test files, or a file path with wildcards. If no test name is given, all unit tests are run.

    $ php symfony test-unit
    
Launches all unit tests in harness mode.

    $ php symfony test-functional <APPLICATION_NAME> <TEST>

Launches a functional test for a given application. The `TEST` parameter can be the name of a single functional test file (omitting the `Test.php` suffix), a group of unit test files, or a file path with wildcards. 

    $ php symfony test-functional <APPLICATION_NAME>
    
Launches all functional tests of an application in harness mode.

    $ php symfony test-all 
    
Launches all unit and functional tests in harness mode.

Find more about testing in [Chapter 15](http://www.symfony-project.com/book/trunk/15-Unit-and-Functional-Testing).

### Project administration

    $ php symfony disable <APPLICATION_NAME> <ENVIRONMENT_NAME>

Forwards the user to the unavailable module and action in your `settings.yml` file and acts in the same way as if you had set the unavaiable setting in your `settings.yml` file. The advantage over the setting is that you can disable a single application for a single environment, and not only the whole project.

    $ php symfony enable <APPLICATION_NAME> <ENVIRONMENT_NAME>

Enables the application and clears the cache. 

    $ php symfony purge-logs

Clears the logs files in the log directory in applications and environments where the `logging.yml` specifies `purge: on` (which is the default value).

    $ php symfony rotate-log <APPLICATION_NAME> <ENVIRONMENT_NAME>
    
Forces a rotation of a log file if `rotate` is enabled for the log file in `logging.yml`. The rotation parameters are the `period` (the number of days a single log file lasts) and the `history` (the number of backup log files kept). Here is an example of `logging.yml` withrotation configutation:

    prod:
      rotate:  on
      period:  7       ## Log files are rotated every 7 days by default
      history: 10      ## A maximum history of 10 log files is kepts   

### Scaffolding and admin generation

    $ php symfony propel-generate-crud <APPLICATION_NAME> <MODULE_NAME> <CLASS_NAME>
    $ php symfony propel-init-crud <APPLICATION_NAME> <MODULE_NAME> <CLASS_NAME>
    
Generates a new Propel CRUD module based on a class from the model. The `generate` version copies the code from the framework to a new module, the `init` verson creates an empty module that inherits from the one in the framework. In this case, the generated code is visible only in the `cache/` folder (the generated actions and templates inherit from the framework).

    $ php symfony propel-init-admin <APPLICATION_NAME> <MODULE_NAME> <CLASS_NAME>
    
Initializes a new Propel admin module based on a class from the model

Find more about these commands in [Chapter 14](http://www.symfony-project.com/book/trunk/14-Generators).

### Plugin management

    $ php symfony plugin-install <CHANNEL_NAME>/<PLUGIN_NAME>
    
Installs a new plugin. To install a new plugin from the symfony wiki, use `http://plugins.symfony-project.com` as a channel name.
    
    $ php symfony plugin-upgrade <CHANNEL_NAME>/<PLUGIN_NAME>

Upgrades a plugin.

    $ php symfony plugin-upgrade-all

Upgrades all the plugins previously installed in local

    $ php symfony plugin-uninstall <CHANNEL_NAME>/<PLUGIN_NAME>
    
Uninstalls a plugin.    

Find more about plugins in [Chapter 17](http://www.symfony-project.com/book/trunk/17-Extending-Symfony).

Automatic completion
---------------------

The symfony wiki contains user-contributed configuration files to allow automatic completion of symfony commands. Check out the one that fits your CLI:

* [Bash completion](http://www.symfony-project.com/trac/wiki/BashCompletion)
* [Zsh completion](http://www.symfony-project.com/trac/wiki/ZshCompletion) 

[1]: http://www.pake-project.org/    "Pake"
[2]: http://rake.rubyforge.org/      "Rake"