Si vous avez essayé de créer votre propre widget, vous avez du vous apercevoir que le rendu est fait a l'intérieur de la fonction sfWidget->render(). Ce qui suffit pour des rendus simples, mais s'avère inapproprié lorsque votre champ de formulaire se complexifie. La structure vue-contrôleur du framework n'est pas respectée.

Pour compenser ce manque, j'ai créé un widget dont le rendu se fait via un composant (component) ou une vue partielle (partial). Ce widget est destiné à faciliter la création de champ de formulaire spécifiques pouvant utiliser entre autre AJAX, le profil de l'utilisateur, l'objet sfContext et sfRequest...

# /lib/widget/sfWidgetFormComponent.class.php
/**
 * sfWidgetComponent is a widget rendered on a component.
 * The component will recieve this vars :
 *  * $name        The element name
 *  * $value       The value selected in this widget
 *  * $attributes  An array of HTML attributes to be merged with the default HTML attributes
 *  * $errors      An array of errors for the field
 *  * $id          An unique id
 *  * $is_hidden   Is the field hidden ?
 *
 * @package    core
 * @subpackage widget
 * @author     Jerome TAMARELLE <http://jerome.tamarelle.net/>
 */
class sfWidgetFormComponent extends sfWidgetForm
{
  /**
   * Constructor.
   *
   * Available options:
   *  * module:       The module name
   *  * component:    The component name
   *  * context:      Current context object
   *
   * @param array $options     An array of options
   * @param array $attributes  An array of default HTML attributes
   * @see sfWidgetForm
   */
  protected function configure($options = array(), $attributes = array()) {
    $this->addRequiredOption('module');
    $this->addRequiredOption('component');
    $this->addOption('is_partial', false);
    $this->addOption('context', sfContext::hasInstance() ? sfContext::getInstance() : null);
  }

  /**
   * @param  string $name        The element name
   * @param  string $value       The value selected in this widget
   * @param  array  $attributes  An array of HTML attributes to be merged with the default HTML attributes
   * @param  array  $errors      An array of errors for the field
   * @return string The rendered component
   * @see sfWidgetForm
   */
  public function render($name, $value = null, $attributes = array(), $errors = array()) {
    try {
      $this->getOption('context')->getConfiguration()->loadHelpers('Partial');
    } catch (Exception $e) {
      throw new Exception('sfWidgetFormComponent requires &quot;context&quot; option to be an instance of sfContext.');
    }

    $vars = array(
      'name'        => $name,
      'value'       => $value,
      'attributes'  => $attributes,
      'errors'      => $errors,
      'id'          => $this->generateId($name),
      'is_hidden'   => $this->getOption('is_hidden'),
    );

    if($this->getOption('is_partial')) {
      return get_partial($this->getOption('module').'/'.$this->getOption('component'), $vars);
    } else {
      return get_component($this->getOption('module'), $this->getOption('component'), $vars);
    }
  }
}

sfWidgetFormComponent est un widget comme les autres ! Pour l'utiliser il suffit de l'ajouter à votre formulaire dans la fonction configure() de celui-ci.

# /lib/form/MyModelForm.class.php
class MyModelForm extends BaseMyModelForm {
  public function configure() {
    $this->setWidget('field',
      new sfWidgetFormComponent(array(
                      'module'=>'ajax',
                      'component'=>'myModelWidget'
    )));
  }
}

Il ne vous reste plus qu'à créer le composant qui conviendra le mieux à votre besoin !

• Widgets de l'API Symfony
• Plugins Symfony de la catégorie Widget
• Au Coeur des Widgets et Validateurs
• Personnaliser le code d'un widget
• Générer un formulaire en fonction de l'utilisateur

Le nouveau framework est en développement, mais si comme moi vous voulez explorer les fonctionnalités de ce trésor, voici comment bien démarrer sous Windows.

Le pack d'installation fournit un fichier check.php permettant de vérifier la compatibilité de votre environnement PHP avec les pré-requis du nouveau framework.

La distribution WAMP correspond quasiment à la configuration suggérée pour Symfony 2.0 (dans la version dev du 10/03/2010 en tout cas).

Symfony 2.0 requière PHP 5.3.1 alors que WAMP propose par défaut la 5.3.0

Contrairement à ce qui avait été annoncé, c'est PHP 5.3.1 qui est recommandé au lieu de la 5.3.0 (voir changelog).

Pour installer PHP 5.3.1 sous WAMP, téléchargez simplement l'add-on éponyme.

Lorsque l'installation est terminée, il vous faut sélectionner cette version de PHP dans le menu contextuel de WAMP (icône en bas à droite) :
> PHP > Version > 5.3.1

Si vous utilisez Propel, il vous faut aussi activer l'extension XSL (optionnel) :
>PHP > PHP extensions > php_xsl

Même pour le développement il est intéressant d'améliorer les performances d'exécution de PHP. Pour cela on peut installer l'accélérateur APC.

Téléchargez la dll de APC : php_apc-5.3-svn20100226-vc9-x86.zip

Extraire le contenu de l'archive dans C:\wamp\bin\php\php5.3.1\ext

Modifiez le fichier php.ini : > PHP > php.ini

extension=php_xsl.dll
;extension=php_zip.dll
extension=php_apc.dll

Si vous souhaitez déposer votre code en dehors du répertoire www de WAMP, il vous faut créer un Alias :
> Apache > Alias directories > Add an alias

Dans l'invite de commande, saisissez le nom de votre alias (par exmple : symfony2) puis l'emplacement du répertoire web de votre installation. Pensez à utiliser des slash (/) comme séparateur et à mettre un slash à la fin (par exemple : C:/Programmation/Symfony2/web/).

Il est aussi conseillé d'activer le module rewrite de Apache :
> Apache > Apache modules > rewrire_module

Accédez maintenant à la page http://localhost/symfony2/. Une page indiquant que Symfony est correctement installé doit s'afficher. Si vous avez une erreur du type "fichier *index.php non trouvé", modifiez le fichier .htaccess :

 <IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /symfony2
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteRule ^(.*)$ index.php [QSA,L]
 </IfModule>

• comment gérer plusieurs langues pour l'interface de vos modules d'administration en indiquant la langue dans l'URL
• et comment basculer en un clic d'une langue à une autre.

Basculer rapidement entre les langues.

Cet article est écrit pour Symfony 1.4 avec l'admin-generator Doctrine. Nous utiliseront également le plugin sfLanguageSwitchPlugin.

La première étape importante est d'activer i18n dans le fichier settings.yml de l'application :

all:
  .settings:
    # Enable internationalization
    i18n:            true
    default_culture: fr

Le paramètre default_culture ne semble pas avoir d'incidence.

Dans les applications développées sous Symfony, la langue d'une page peut être indiquée dans l’URL via l’attribut :sf_culture. Une route localisée ressemble à cela :

map:
  url:   /:sf_culture/map/:id
  requirements: { sf_culture: (?:en|es|fr) }
  param: { module: map, action: view }

Le paramètre requirements décrit un pattern à respecter pour le champ :sf_culture. Le simple ajout du paramètre :sf_culture dans l'URL modifie automatiquement la langue de l'utilisateur. Il n'y a pas besoin de passer ce paramètre pour générer l'URL avec les url_for(...) et autres link_to(...).

Pour prendre en compte ce paramètre dans les modules d’admin, j'ai créé des classes routing spécifiques. Deux fichiers dans le répertoire lib du projet ou de l'application (au choix) :

La classe sfI18NDoctrineRoute ajoute le paramètre :sf_culture aux routes.

/lib/routing/sfI18NDoctrineRoute.class.php

class sfI18NDoctrineRoute extends sfDoctrineRoute
{
  /**
   * @see sfRoute
   */
  public function __construct($pattern, array $defaults = array(), array $requirements = array(), array $options = array())
  {
    // Add the culture prefix to admin routes
    $pattern = '/:sf_culture' . $pattern;
    parent::__construct($pattern, $defaults, $requirements, $options);
  }
}

/lib/routing/sfI18NDoctrineRouteCollection.class.php

class sfI18NDoctrineRouteCollection extends sfObjectRouteCollection
{
  protected $routeClass = 'sfI18NDoctrineRoute';
}

Maintenant que vos classes sont crées, il faut modifier vos routes. Cela donne par exemple :

my_class:
  class: sfI18NDoctrineRouteCollection
  options:
    model:                MyClass
    module:               my_class
    prefix_path:          /my_class
    column:               id
    with_wildcard_routes: true

Essayer maintenant d'afficher votre module en modifiant le paramètre de langue :

http://localhost/app/fr/my_class

http://localhost/app/hu/my_class

Notez bien qu'il n'est ici pas nécessaire d'ajouter les fichiers XLIFF de langue dans le répertoire i18n de l'application. Les fichiers du plugin Doctrine sont directement utilisés.

Si vous souhaitez afficher une barre de choix de la langue, rien de plus simple grâce au plugin sfLanguageSwitchPlugin qui vous fourni un composant dédié.

Téléchargez sfLanguageSwitchPlugin et installez-le comme décrit dans la notice.

/apps/backend/config/settings.yml

all:
  .settings:
    enabled_modules:    [sfLanguageSwitch]
    i18n:                     true

/apps/backend/config/app.yml

all:
  # sfLanguageSwitchPlugin
  sfLanguageSwitch:
    flagPath: /sfLanguageSwitch/images/flag
    availableLanguages:
      en: { title: English }
      ar: { title: العربية}
      bg: { title: български език }
      ca: { title: Català }
      cs: { title: Česky }
      de: { title: Deutch }
      es: { title: Español }
      fi: { title: Suomen kieli }
      fr: { title: Français }
      hr: { title: Hrvatski }
      hu: { title: Magyar }
      id: { title: Bahasa Indonesia }
      it: { title: Italiano }
      lt: { title: Lietuvių kalba }
      lv: { title: Latviešu valoda }
      nl: { title: Nederlands }
      no: { title: Norsk }
      pl: { title: Polski }
      pt: { title: Português }
      ro: { title: Română }
      ru: { title: русский язык }
      sk: { title: Slovenčina }
      sl: { title: Slovenščina }
      sv: { title: Svenska }
      tr: { title: Türkçe }

(Wikipedia : Liste des codes langue)

Ajoutez maintenant le composant à votre layout :

/apps/backend/templates/layout.php

  <body>
    <?php include_component('sfLanguageSwitch', 'get'); ?>
    <?php echo $sf_content ?>
  </body>

Pour afficher sous forme de liste, juste un petit bout de code CSS :

/web/css/main.css

#lang li { display: inline; }

Si vous avez des remarques ou suggestions, n'hésitez pas ! Les commentaires sont là pour ça.

A quoi sert le paramètre with_show dans le fichier generator.yml ?

Aussi surprenante soit-elle, la réponse usuelle à cette question est :

Par défaut, à rien...

Alors comment afficher les détails d'un objet dans une page d'administration sans que celles-ci soient modifiables ? il est bien nécessaire d'activer l'action show. Les plugins sfDoctrineAdminGeneratorWithShowPlugin et sfPropelAdminGeneratorWithShowPlugin ont été créés pour compenser ce manque. Malheureusement ils ne fonctionnent que pour Symfony 1.2 et 1.3.

Paralysé par cette absence d'action show sous Symfony 1.4, je me suis lancé dans la correction du plugin sfDoctrineAdminGeneratorWithShowPlugin pour le rendre compatible.

Télécharger sfDoctrineAdminGeneratorWithShowPlugin pour Symfony 1.4

Pour installer le plugin, décompressez l'archive dans le répertoire plugin/ de votre projet Symfony.

Activez le plugin en modifiant le fichier config/ProjectConfiguration.class.php

$this->enablePlugins('sfDoctrinePlugin','sfDoctrineAdminGeneratorWithShowPlugin');

Générez le module d'administration :

./symfony doctrine:generate-admin --theme=adminWithShow application ClasseExemple

Activez l'action vue dans le fichier application/modules/classe_exemple/config/generator.yml

    with_show: true

Cela donne par exemple :

generator:
  class: sfDoctrineGenerator
  param:
    model_class:           ClasseExemple
    theme:                 adminWithShow
    non_verbose_templates: true
    with_show:             true
    singular:              ~
    plural:                ~
    route_prefix:          classe_exemple
    with_doctrine_route:   true

    config:
      actions: ~
      fields:  ~
      list:    ~
      filter:  ~
      form:    ~
      edit:    ~
      new:     ~
      show:    ~

Maintenant que l'action show est ajoutée, vous pouvez personnaliser à souhait votre module d'administration en modifiant le fichier generator.yml et/ou les templates. Toute la documentation utile est sur le site du framework.

1. Depuis la console (communément appelé CLI)
2. Depuis une adresse locale (localhost)
3. Depuis une requête AJAX (ou XMLHttpRequest JavaScript)
4. En mode debug
5. Contexte d'exécution

La fonction php_sapi_name retourne le type d'interface utilisée, par exemple "cli" ou "cgi". En analysant la valeur retournée par cette fonction vous pouvez donc facilement détecter une exécution dans la console PHP. Dans Symfony, ce sont les tâches qui sont généralement exécutées par cette interface.

if(php_sapi_name() == 'cli')
{
  // Code exécuté uniquement lorsque le script est appelé en ligne de commande (cli).
}

Symfony fait déjà cette détection par défaut dans le fichier app_dev.php pour empêcher l'exécution de l'application en mode debug depuis d'extérieur. Les adresses 127.0.0.1 et ::1 sont les adresses IP v4 et v6 normalisées de rebouclage sur la machine locale, la condition ci-dessous vérifie que la requête est transmise depuis l'une de ces deux adresses.

if (in_array($this->getRequest()->getRemoteAddress(), array('127.0.0.1', '::1')))
{
  // Code exécuté uniquement lorsque l'application est exécutée depuis une adresse locale.
}

Parmi les fonctionnalités magiques de Symfony, vous pouvez appelé la fonction sfWebRequest::isXmlHttpRequest() depuis vos sfAction(s). Vous saurez alors si la page a été appelée depuis JavaScript.

if($this->getRequest()->isXmlHttpRequest())
{
  // Code exécuté uniquement lorsque l'action est appelée depuis JavaScript
}

Lorsque votre application est exécutée en mode debug, la constante sf_debug prend la valeur true. Il vous est donc facile de n'afficher certaines informations que pour le développement et le débogage de votre application.

if(sfConfig::get('sf_debug'))
{
  // Code exécuté uniquement lorsque l'application est exécutée en mode debug
}

(Ajouté le 04/02/2010)

Pour éviter l'erreur « The "default" context does not exist. » lorsqu'on utilise i18n ou doctrine dans les models/widgets par exemple.

if(sfContext::hasInstance())
{
  $contexte = sfContext::getInstance();
  // Code exécuté uniquement lorsque l'application est exécutée avec un contexte (depuis une application).
}

Les usages sont multiples, par exemple :

• Auto-complétion d'un champ avec le plugin sfFormExtraPlugin,
• les événements issus de la base de données à afficher dans un calendrier FullCalendar,
• ou une galerie photos AJAX avec minishowcase.

Le plus simple pour envoyer du code JSON depuis Symfony est d'inclure les lignes suivantes à la fin du contrôleur :

function executeAction() {
  $data = array();
  // ... Création du tableau $data ...

  // Indispensable : définie le l'en-tête HTTP correspondant au format JSON.
  $this->getResponse()->setHttpHeader('Content-type', 'application/json');
  // Contenu transmis.
  $this->getResponse()->setContent(json_encode($data));
  // N'affiche aucune vue.
  return return sfView::NONE;
}

Simple à mettre en œuvre, cette méthode peut poser problème pour le débuggage de l'application.

• Le contenu JSON transmis n'est pas visualisable dans le navigateur à cause du content-type non reconnu.
• Si l'on laisse le content-type par défaut, le texte JSON transmis est parasité par la debug toolbar.

Pour rendre visible le format JSON au développeur, il faut adapter la réponse au contexte d'exécution de la page. Les données ne doivent être affichées lisiblement que lorsque le développeur affiche la page en mode débug, mais pas lorsqu'elle est appelée depuis JavaScript, même en mode débug. Pour cela, la méthode sfWebRequest::isXmlHttpRequest() est bien pratique.

Un petit aperçu du rendu dans le navigateur en mode débug, lorsque la page est appelée directement depuis la barre d'adresse du navigateur.

Aperçu du rendu JSON en mode débug.

1/3 Créez le composant JSON. Fichier app/app_name/modules/module_name/actions/jsonComponent.class.php

class jsonComponent extends sfComponent
{
  function execute($request)
  {
    if (sfConfig::get('sf_debug') && !$this->getRequest()->isXmlHttpRequest())
    {
      $this->setVar('data', $this->data);
    }
    else
    {
      $this->getResponse()->setHttpHeader('Content-type', 'application/json');
      $this->getResponse()->setContent(json_encode($this->data));
      return sfView::NONE;
    }
  }
}

2/3 Créez ensuite la vue associée. Fichier app/app_name/modules/module_name/templates/_json.php

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>JSON response</title></head>
<body>
  <h2>JSON</h2>
  <?php echo json_encode($sf_data->getRaw('data')); ?>
  <h2>Data structure</h2>
  <pre><?php print_r($sf_data->getRaw('data')); ?></pre>
</body>
</html>

3/3 Enfin appelez le composant depuis votre contrôleur. Fichier app/app_name/modules/module_name/actions/actions.class.php

function executeAction() {
  $data = array();
  // ... Création du tableau $data ...

  // Transmet la responsabilité de l'affichage au composant JSON
  return $this->renderComponent('module_name', 'json', array('data'=>$data));
}

Le composant peut être créé dans un module spécifique et appelé depuis un autre module.

Reste plus qu'à en faire un plugin ...

Deux articles pour aller plus loin :

• AJAX and JSON
• Symfony 1.2 The definitive guide | JSON