Chapitre 11 - Intégration avec Doctrine

Même si la personnalisation du widget peut nous permettre de réduire la liste des options disponibles, nous ne devons pas oublier de reporter cette réduction au niveau du validateur, comme montré dans le Listing 4-11. Comme le widget sfWidgetProperSelect, le validateur sfValidatorDoctrineChoice accepte une option query pour cibler les options valides pour un champ.

Listing 4-11 - Personnalisation du validateur sfValidatorDoctrineChoice

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    // ...
 
    $query = Doctrine_Query::create()
      ->from('Author a')
      ->where('a.active = ?', true);
 
    $this->widgetSchema['author_id']->setOption('query', $query);
    $this->validatorSchema['author_id']->setOption('query', $query);
  }
}

Dans le précédent exemple, nous avons défini un objet Query directement dans la méthode configure(). Dans notre projet, cette requête sera certainement utile en d'autres circonstances, il est donc préférable de créer une méthode getActiveAuthorsQuery() dans la classe AuthorPeer et d'appeler cette méthode depuis ArticleForm comme le montre le Listing 4-12.

Listing 4-12 - Refactorisation de Query dans le modèle

class AuthorTable extends Doctrine_Table
{
  public function getActiveAuthorsQuery()
  {
    $query = Doctrine_Query::create()
      ->from('Author a')
      ->where('a.active = ?', true);
 
    return $query;
  }
}
 
class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    $authorQuery = Doctrine::getTable('Author')->getActiveAuthorsQuery();
    $this->widgetSchema['author_id']->setOption('query', $authorQuery);
    $this->validatorSchema['author_id']->setOption('query', $authorQuery);
  }
}

Changer les validateurs

L'email étant défini comme un string(255) dans le schéma, symfony a créé un validateur sfValidatorString() restreignant la longueur maximale à 255 caractères. Ce champ est aussi supposé contenir des adresses email valides, le Listing 4-13 remplace le validateur généré par un sfValidatorEmail.

Listing 4-13 - Changement du validateur du champ email de la classe AuthorForm

class AuthorForm extends BaseAuthorForm
{
  public function configure()
  {
    $this->validatorSchema['email'] = new sfValidatorEmail();
  }
}

Ajouter un validateur

Nous avons vu dans la précédente partie comment modifier le validateur généré. Mais dans le cas du champ email, il serait utile de garder la validation de longueur maximale. Dans le Listing 4-14, nous utilisons le validateur sfValidatorAnd pour garantir la validité de l'email et vérifier la taille maximale possible pour le champ.

Listing 4-14 - Utilisation d'un validateur multiple

class AuthorForm extends BaseAuthorForm
{
  public function configure()
  {
    $this->validatorSchema['email'] = new sfValidatorAnd(array(
      new sfValidatorString(array('max_length' => 255)),
      new sfValidatorEmail(),
    ));
  }
}

L'exemple précédent n'est pas parfait, car si nous décidons de modifier par la suite la longueur du champ email dans le schéma de base de données, nous devrons penser à le faire également dans le formulaire. Au lieu de remplacer le validateur généré, il est préférable d'en ajouter un, comme le montre le Listing 4-15.

Listing 4-15 - Ajout d'un validateur

class AuthorForm extends BaseAuthorForm
{
  public function configure()
  {
    $this->validatorSchema['email'] = new sfValidatorAnd(array(
      $this->validatorSchema['email'],
      new sfValidatorEmail(),
    ));
  }
}

Changer un widget

Dans le schéma de base de données, le champ status de la table article stocke les statuts d'articles dans une chaine de caractères. Les valeurs possibles ont été définies dans la classe ArticlePeer, comme montré dans le Listing 4-16.

Listing 4-16 - Définition des statuts possibles dans la classe ArticlePeer

class ArticlePeer extends BaseArticlePeer
{
  static protected $statuses = array('draft', 'online', 'offline');
 
  static public function getStatuses()
  {
    return self::$statuses;
  }
 
  // ...
}

Lors de l'édition d'un article, le champ status doit être représenté comme une liste déroulante au lieu d'un champ texte. Pour ce faire, changeons le widget utilisé, comme le montre le Listing 4-17.

Listing 4-17 - Changement du widget pour le champ status

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    $this->widgetSchema['status'] = new sfWidgetFormSelect(array('choices' => ArticlePeer::getStatuses()));
  }
}

Pour être exhaustifs, nous devons également changer le validateur pour être sûrs que le statut choisi est bien présent dans la liste des options possibles (Listing 4-18).

Listing 4-18 - Modification du validateur du champ status

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    $statuses = ArticlePeer::getStatuses();
 
    $this->widgetSchema['status'] = new sfWidgetFormSelect(array('choices' => $statuses));
 
    $this->validatorSchema['status'] = new sfValidatorChoice(array('choices' => array_keys($statuses)));
  }
}

Supprimer un champ

La table article a tres colonnes spéciales, created_at, updated_at et published_at, dont la mise à jour est automatiquement gérée par Doctrine. Nous devons donc les supprimer du formulaire comme le montre le Listing 4-19, pour éviter que les utilisateurs les modifient.

Listing 4-19 - Suppression d'un champ

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    // ...
 
    unset($this->validatorSchema['created_at']);
    unset($this->widgetSchema['created_at']);
 
    unset($this->validatorSchema['updated_at']);
    unset($this->widgetSchema['updated_at']);
 
    unset($this->validatorSchema['published_at']);
    unset($this->widgetSchema['published_at']);
  }
}

Afin de supprimer un champ, il est nécessaire de supprimer son validateur et son widget. Le Listing 4-20 montre comment il est possible de les supprimer tous les deux en une action, en utilisant le formulaire comme un tableau PHP.

Listing 4-20 - Suppression d'un champ en utilisant le formulaire comme un tableau PHP

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    unset($this['created_at'], $this['updated_at'], $this['published_at']);
  }
}

Résumé

Pour résumer, le Listing 4-21 et le Listing 4-22 montrent les formulaires ArticleForm et AuthorForm personnalisés.

Listing 4-21 - Formulaire ArticleForm

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    $authorQuery = Doctrine::getTable('Author')->getActiveAuthorsQuery();
 
    // widgets
    $this->widgetSchema['content']->setAttributes(array('rows' => 10, 'cols' => 40));
    $this->widgetSchema['status'] = new sfWidgetFormSelect(array('choices' => ArticlePeer::getStatuses()));
    $this->widgetSchema['author_id']->setOption('query', $authorQuery);
 
    // validators
    $this->validatorSchema['slug']->setOption('required', false);
    $this->validatorSchema['content']->setOption('min_length', 5);
    $this->validatorSchema['status'] = new sfValidatorChoice(array('choices' => array_keys(ArticlePeer::getStatuses())));
    $this->validatorSchema['author_id']->setOption('query', $authorQuery);
 
    unset($this['created_at'], $this['updated_at'], $this['published_at']);
  }
}

Listing 4-22 - Formulaire AuthorForm

class AuthorForm extends BaseAuthorForm
{
  public function configure()
  {
    $this->validatorSchema['email'] = new sfValidatorAnd(array(
      $this->validatorSchema['email'],
      new sfValidatorEmail(),
    ));
  }
}

Utiliser doctrine:build-forms permet de générer la plupart des éléments en introspectant le modèle objet. Cette automatisation est utile pour plusieurs raisons :

• Cela rend la vie plus facile au développeur, lui épargnant un travail répétitif et redondant. Il peut alors se concentrer sur la personnalisation des validateurs et des widgets en fonction des règles métier spécifiques au projet.

• De plus, lorsque le schéma de base de données est mis à jour, les formulaires générés seront automatiquement mis à jour. Le développeur aura juste à adapter ses personnalisations.

La prochaine section décrira la personnalisation des actions et des templates générés par la tâche doctrine:generate-crud.

Sérialisation des formulaires

La précédente section nous montre comment personnaliser les formulaires générés par la tâche doctrine:build-forms. Dans la section courante, nous allons personnaliser le cycle de vie des formulaires, en commençant par le code généré par doctrine:generate-crud.

Valeurs par défaut

Une instance de formulaire Doctrine est toujours reliée à un objet Doctrine. L'objet Doctrine lié appartient toujours à la classe retournée par la méthode getModelName(). Par exemple, le formulaire AuthorForm peut seulement être lié à des objets appartenant à la classe Author. Ces objets sont soit des objets vides (une instance vide de la classe Author), soit les objets passés en premier argument au constructeur. Alors que le constructeur d'un formulaire « normal » prend un tableau de valeurs en premier argument, le constructeur d'un formulaire Doctrine prend un objet Doctrine. Cet objet est utilisé pour définir la valeur par défaut de chaque champ du fomulaire. La méthode getObject() retourne l'objet relié à l'instance courante, et la méthode isNew() permet de savoir si l'objet a été créé par le constructeur :

// création d'un nouvel objet
$authorForm = new AuthorForm();
 
print $authorForm->getObject()->getId(); // affiche null
print $authorForm->isNew();              // affiche true
 
// modification d'un objet existant
$author = Doctrine::getTable('Author')->find(1);
$authorForm = new AuthorForm($author);
 
print $authorForm->getObject()->getId(); // affiche 1
print $authorForm->isNew();              // affiche false

Gestion du cycle de vie

Comme nous l'avons observé au début de ce chapitre, l'action edit, montrée dans le listing 4-23, gère le cycle de vie.

Listing 4-23 - La méthode executeEdit du module author

// apps/frontend/modules/author/actions/actions.class.php
class authorActions extends sfActions
{
  // ...
 
  public function executeEdit($request)
  {
    $author = Doctrine::getTable('Author')->find($request->getParameter('id'));
    $this->form = new AuthorForm($author);
 
    if ($request->isMethod('post'))
    {
      $this->form->bind($request->getParameter('author'));
      if ($this->form->isValid())
      {
        $author = $this->form->save();
 
        $this->redirect('author/edit?id='.$author->getId());
      }
    }
  }
}

Même si l'action edit ressemble aux actions que nous avons pu décrire dans les chapitres précédents, nous pouvons remarquer quelques différences :

• Un objet Doctrine de la classe Author est passé en premier paramètre du constructeur du formulaire :

  $author = Doctrine::getTable('Author')->find($request->getParameter('id'));
  $this->form = new AuthorForm($author);

• Le format des attributs name des widgets est automatiquement défini de manière à récupérer les données soumises dans un tableau PHP nommé d'après la table liée (author) :

  $this->form->bind($request->getParameter('author'));

• Lorsque le formulaire est valide, un appel à la méthode save() crée ou met à jour les objets Doctrine reliés au formulaire :

  $author = $this->form->save();

Créer et modifier un objet Doctrine

Le code du Listing 4-23 gère en une seule méthode la création et la modification d'objets de la classe Author :

• Création d'un nouvel objet Author :

  • L'action index est appelée sans paramètre id ($request->getParameter('id') vaut null)

  • L'appel à la méthode find() renvoie dont null

  • L'objet form est alors lié à un objet Doctrine Author vide

  • L'appel à $this->form->save() crée un nouvel objet Author en conséquence quand un formulaire valide est soumis

• Modification d'un objet Author` existant :

  • L'action index est appelée avec un paramètre id ($request->getParameter('id') représentant la clé primaire de l'objet Author à modifier)

  • L'appel à la méthode find() retourne l'objet Author associé à la clé primaire

  • L'objet form est donc lié à l'objet précédemment trouvé

  • L'appel à $this->form->save() met à jour l'objet Author quand un formulaire valide est soumis

La méthode save()

Quand un formulaire Doctrine est valide, la méthode save() met à jour l'objet associé et l'enregistre dans la base de données. Cette méthode enregistre en fait non seulement l'objet principal, mais aussi les objets potentiellement reliés. Par exemple, le formulaire ArticleForm met à jour les tags connectés à un article. La relation entre les tables article et tag étant n-n, les tags reliés à un article sont stockés dans la table article_tag (en utilisant la méthode saveArticleTagList() générée).

Afin de certifier une sérialisation consistante, la méthode save() inclut toutes les mises à jour dans une transaction.

class articleActions extends sfActions
{
  public function executeCreate(sfWebRequest $request)
  {
    $this->form = new ArticleForm();
 
    if ($request->isMethod('post') && $this->form->bindAndSave($request->getParameter('article')))
    {
      $this->redirect('article/created');
    }
  }
}

Gestion des envois de fichiers

La méthode save() met automatiquement à jour les objets Doctrine, mais ne peut pas gérer les autres éléments tels que les envois de fichiers.

Voyons comment attacher un fichier à chaque article. Les fichiers sont enregistrés dans le répertoire web/uploads et une référence vers le fichier est gardée dans le champ file de la table article, comme le montre le Listing 4-24.

Listing 4-24 - Schéma pour la table article avec le fichier associé

// config/schema.yml
doctrine:
  article:
    // ...
    file: string(255)

Après chaque mise à jour du schéma, vous devez mettre à jour le modèle objet, la base de données et les formulaires associés :

$ ./symfony doctrine:build-all

Attention Soyez conscients que la tâche doctrine:build-all supprime toutes les tables du schéma et les recrée. Les données dans les tables sont donc réécrites. C'est pourquoi il est important de créer des données de test (fixtures) qui pourront être rechargées à chaque modification du modèle.

Le Listing 4-25 montre comment modifier la classe ArticleForm afin de relier un widget et un validateur au champ file.

Listing 4-25 - Modification du champ file du formulaire ArticleForm

class ArticleForm extends BaseArticleForm
{
  public function configure()
  {
    // ...
 
    $this->widgetSchema['file'] = new sfWidgetFormInputFile();
    $this->validatorSchema['file'] = new sfValidatorFile();
  }
}

Comme pour chaque formulaire permettant l'envoi d'un fichier, n'oubliez pas d'ajouter l'attribut enctype à la balise form dans le template (voyez le Chapitre 2 pour plus d'informations concernant la gestion d'envois de fichiers).

Le Listing 4-26 montre les modifications à appliquer lors de l'enregistrement du formulaire pour enregistrer le fichier sur le serveur et stocker son chemin dans l'objet article.

Listing 4-26 - Enregistrement de l'objet article et du fichier envoyé dans une action

public function executeEdit($request)
{
  $author = Doctrine::getTable('Author')->find($request->getParameter('id'));
  $this->form = new ArticleForm($author);
 
  if ($request->isMethod('post'))
  {
    $this->form->bind($request->getParameter('article'), $request->getFiles('article'));
    if ($this->form->isValid())
    {
      $file = $this->form->getValue('file');
      $filename = sha1($file->getOriginalName()).$file->getExtension($file->getOriginalExtension());
      $file->save(sfConfig::get('sf_upload_dir').'/'.$filename);
 
      $article = $this->form->save();
 
      $this->redirect('article/edit?id='.$article->getId());
    }
  }
}

Enregistrer le fichier envoyé sur le système de fichiers permet à l'objet sfValidatedFile de connaître le chemin absolu du fichier. Pendant l'appel à save(), les valeurs des champs sont utilisées pour mettre à jour l'objet associé et, comme pour le champ file, l'objet sfValidatedFile est converti en chaine de caractères grâce à la méthode __toString(), renvoyant le chemin absolu du fichier. La colonne file de la table article stocke ce chemin absolu.

Personnalisation de la méthode save()

Nous avons vu dans la section précédente comment enregistrer le fichier envoyé dans l'action edit. Un des principes de la programmation orientée objet est la réutilisabilité du code, grâce à son encapsulation dans des classes. Au lieu de dupliquer le code utilisé pour enregistrer le fichier dans chaque action utilisant le formulaire ArticleForm, il est préférable de le déplacer dans la classe ArticleForm. Le Listing 4-27 montre comment surcharger la méthode save() afin d'enregistrer aussi le fichier et éventuellement de supprimer un fichier existant.

Listing 4-27 - Surcharge de la méthode save() de la classe ArticleForm

class ArticleForm extends BaseFormDoctrine
{
  // ...
 
  public function save($con = null)
  {
    if (file_exists($this->getObject()->getFile()))
    {
      unlink($this->getObject()->getFile());
    }
 
    $file = $this->getValue('file');
    $filename = sha1($file->getOriginalName()).$file->getExtension($file->getOriginalExtension());
    $file->save(sfConfig::get('sf_upload_dir').'/'.$filename);
 
    return parent::save($con);
  }
}

Après avoir déplacé le code dans le formulaire, l'action edit est identique au code généré par doctrine:generate-crud.

class Article extends BaseArticle
{
  public function save($con = null)
  {
    if (!$this->getSlug())
    {
      $this->setSlugFromTitle();
    }
 
    return parent::save($con);
  }
 
  protected function setSlugFromTitle()
  {
    // ...
  }
}

Personnalisation de la méthode doSave()

Nous avons vu que l'enregistrement d'un objet était fait dans une transaction afin de garantir que chaque opération liée à l'enregistrement soit exécutée correctement. Lorsque la méthode save() est surchargée comme nous l'avons fait dans la section précédente pour enregistrer le fichier envoyé, le code exécuté est indépendant de cette transaction.

Le Listing 4-28 nous montre comment utiliser la méthode doSave() pour insérer dans la transaction globale le code enregistrant le fichier envoyé.

Listing 4-28 - Surcharge de la méthode doSave() dans le formulaire ArticleForm

class ArticleForm extends BaseFormDoctrine
{
  // ...
 
  protected function doSave($con = null)
  {
    if (file_exists($this->getObject()->getFile()))
    {
      unlink($this->getObject()->getFile());
    }
 
    $file = $this->getValue('file');
    $filename = sha1($file->getOriginalName()).$file->getExtension($file->getOriginalExtension());
    $file->save(sfConfig::get('sf_upload_dir').'/'.$filename);
 
    return parent::doSave($con);
  }
}

La méthode doSave() étant appelée dans la transaction créé par la méthode save(), si l'appel à la méthode save() de l'objet file() lance une exception, l'objet ne sera pas enregistré.

Personnalisation de la méthode updateObject()

Il est parfois nécessaire de modifier l'objet connecté au formulaire entre la mise à jour et l'enregistrement en base de données.

Dans l'exemple d'envoi de fichier, au lieu de stocker le chemin absolu du fichier envoyé dans la colonne file, nous voulons enregistrer le chemin relatif au répertoire sfConfig::get('sf_upload_dir').

Le Listing 4-29 montre comment redéfinir la méthode updateObject() du formulaire ArticleForm afin de changer la valeur de la colonne file après la mise à jour automatique, mais avant qu'elle soit enregistrée.

Listing 4-29 - Redéfinition de la méthode updateObject() de la classe ArticleForm

class ArticleForm extends BaseFormDoctrine
{
  // ...
 
  public function updateObject()
  {
    $object = parent::updateObject();
 
    $object->setFile(str_replace(sfConfig::get('sf_upload_dir').'/', '', $object->getFile()));
 
    return $object;
  }
}

La méthode updateObject() est appelée par la méthode doSave() avant d'enregistrer l'objet dans la base de données.