= sfControlPanel plugin =

The `sfControlPanelPlugin` proposes a web interface to manage a symfony project. It allows you to browse your project's functional and file structure, execute tasks, modify data in the database, and even more. It is a great development tool for those who are not fond of the command line.

== Installation ==

  * Install the plugin
  
{{{
$ symfony plugin-install http://plugins.symfony-project.com/sfControlPanelPlugin
}}}

  * Enable the plugin `sfControlPanel` module on an application/environment base, via the `enabled_modules` setting of the `settings.yml` file.
    
  For instance, to enable the module for the `frontend` application in the `dev` environment, open the `apps/frontend/config/settings.yml` and add under the `dev` key:
    
{{{
dev:
  .settings:
    enabled_modules: [default, sfControlPanel]
}}}

  Be aware that it is not advised to enable the module on a production environment.

  * (*nix) Change the rights and owner of the project's files to allow your web server to modify them.

  * Clear the cache

{{{
$ symfony cc
}}}

  * Browse to the control panel module
  
{{{
http://localhost/frontend_dev.php/sfControlPanel
}}}

== Features ==

=== MVC overview ===

The home page of the `sfControlPanel` module is an overview of the project's functional structure. In this page, you can browse the project's MVC layers, and get direct access to the code of a model method, an action, or a template.

=== Task manager ===

The task manager is a web replacement for the symfony Command Line Interface. Not only does it allow the execution of a symfony task by a single click, it also provides a comprehensive interface for complex tasks and a way to execute any  tasks you want.

If you have PHP files in your `batch/` directory, you will also be able to execute them from this page.

=== Simple task executer ===

The `sfControlPanel/taskExecute` action can replace the symfony command line. Instead of clicking on task names in the task manager sidebar, you can type the task directly in the URL bar. The action expects a `freetask` parameter, that must contain the task name and parameters. For instance, to call the `clear-cache frontend` task, you can simply call the following URL:

{{{
http://localhost/frontend_dev.php/sfControlPanel/taskExecute/freetask/clear-cache frontend
}}}

If you want to make it shorter, edit your `routing.yml` and add a web command shortcut:

{{{
symfony_command:
  url:   /symfony/:freetask
  param: { module: sfControlPanel, action: taskExecute }
}}}

This way, you can call the same command as above by simply calling

{{{
http://localhost/frontend_dev.php/symfony/clear-cache frontend
}}}

=== Code browser ===

The `sfControlPanel` module proposes a code explorer for the files of your project. The file structure displayed on the left side on the window can be browsed the classical way, and syntax highlighting is automatically added to `.php` files.

=== Data reader ===

The `sfControlPanel` plugin proposes a data explorer that will use the connection settings of your `databases.yml` to connect to a database and display the list of tables it contains. Based on the admin generator, each table can be browsed, and each record can be edited or deleted, pretty much like what phpMyAdmin offers.

Each table explorer being automatically generated by symfony, you can add custom generator settings to alter which fields, filters, actions and sort criterias are used, the same way as you usually customized an admin generated theme. For that purpose, create a `sfControlPanel_generator.yml` file in the project's `config/folder`, and add in any generator customization you want. The primary labels are classes. 

So for instance, if your database contains an `article` table, you can customize the fields displayed in the `list` view by writing in the `config/sfControlPanel_generator.yml`:

{{{
Article:
  list: 
    display: [=title, nbComments, content]
}}}

== Restricting access ==

If you want to allow the `sfControlPanel` module in production, you should restrict access to it. Whether you use the `sfGuardPlugin` or another authentication solution, you will end up defining credentials for your users. If you want to allow access only to users having the `admin` credential, create a `sfControlPanel` directory in the ''application'' `modules/` directory with only the following content:

{{{
apps/
  frontend/
    modules/
      sfControlPanel/
        config/
          security.yml
}}}

And, in this `security.yml`, define the credentials you want:

{{{
all:
  is_secure: on
  credentials: [admin]
}}}

Clear the cache: your control panel module is now secure.

== Known limitations ==

If your routing policy is not compatible with the default rules (`/:module` and `/:module/:action`), you have to define specific rules for the `sfControlPanel` module by adding at the beginning of your `routing.yml`: 
{{{ 
sfControlPanel_index: 
  url:   /sfControlPanel 
  param: { module: sfControlPanel, action: index } 

sfControlPanel: 
  url:   /sfControlPanel/:action/* 
  param: { module: sfControlPanel } 
}}} 

The plugin is not compatible with projects having a custom directory structure.

The data explorer will not work for tables that have to primary key. This is a known limitation of the admin generator.