Tutoriel pour apprendre à utiliser le framework Laravel 4

Je suis dans la table editeurs. Je regarde la table contacts et je me dis « j'ai là un numéro de téléphone ». En langage Eloquent on traduit ça par hasOne :

Pour traduire cela de façon concrète, on crée dans le modèle Editeur une méthode :

public function contact()
{
    return $this->hasOne('Contact');
}

Pour établir la relation, Eloquent part du principe que la clé étrangère est construite à partir du nom du modèle auquel on adjoint « _id », ce qui donne bien « editeur_id ». On a d'autres possibilités, regardez la méthode dans la classe Model :

public function hasOne($related, $foreignKey = null, $localKey = null)
{
    $foreignKey = $foreignKey ?: $this->getForeignKey();
 
    $instance = new $related;
 
    $localKey = $localKey ?: $this->getKeyName();
 
    return new HasOne($instance->newQuery(), $this, $instance->getTable().'.'.$foreignKey, $localKey);
}

Le deuxième paramètre permet de renseigner la clé étrangère si elle ne respecte pas la norme, donc on peut écrire par exemple :

public function contact()
{
    return $this->hasOne('Contact', 'editeur');
}

pour le cas où la clé étrangère se nomme « editeur ». Vous remarquez aussi qu'on dispose d'un troisième paramètre, il sert à renseigner le nom de l'ID de la table d'origine si celui-ci ne se nomme pas « id ». Le cas peut se présenter si vous utilisez Eloquent sur une table existante et que vous ne désirez pas tout changer. Je peux maintenant écrire cela :

$telephone = Editeur::first()->contact()->first()->telephone;

Et je trouve le numéro de téléphone de l'éditeur sélectionné. Eloquent génère ces deux requêtes :

select * from `editeurs` limit 1
select * from `contacts` where `contacts`.`editeur_id` = '1' limit 1

Avec le query builder ce serait plus laborieux pour obtenir le même résultat :

$editeur = DB::table('editeurs')->first();
$contact = DB::table('contacts')->where('editeur_id', $editeur->id)->first();
$telephone =  $contact->telephone;

Comme Eloquent est très conciliant vous pouvez même écrire cela :

$telephone = Editeur::first()->contact->telephone;

Ce qui rend la syntaxe particulièrement élégante et lisible !

Envisageons maintenant l'inverse. Cette fois je me place dans la table des contacts. Là je me dis « j'ai un numéro de téléphone qui appartient à un éditeur ». En langage Eloquent on traduit ça par belongsTo :

Pour traduire cela de façon concrète, on crée dans le modèle Editeur une méthode :

public function editeur()
{
    return $this->belongsTo('Editeur');
}

public function belongsTo($related, $foreignKey = null, $otherKey = null, $relation = null)
{
    // If no relation name was given, we will use this debug backtrace to extract
    // the calling method's name and use that as the relationship name as most
    // of the time this will be what we desire to use for the relatinoships.
    if (is_null($relation))
    {
        list(, $caller) = debug_backtrace(false);
 
        $relation = $caller['function'];
    }
 
    // If no foreign key was supplied, we can use a backtrace to guess the proper
    // foreign key name by using the name of the relationship function, which
    // when combined with an "_id" should conventionally match the columns.
    if (is_null($foreignKey))
    {
        $foreignKey = snake_case($relation).'_id';
    }
 
    $instance = new $related;
 
    // Once we have the foreign key names, we'll just create a new Eloquent query
    // for the related models and returns the relationship instance which will
    // actually be responsible for retrieving and hydrating every relations.
    $query = $instance->newQuery();
 
    $otherKey = $otherKey ?: $instance->getKeyName();
 
    return new BelongsTo($query, $this, $foreignKey, $otherKey, $relation);
}

On peut donc renseigner le nom de la clé étrangère si elle ne correspond pas à la norme :

public function editeur()
{
    return $this->belongsTo('Editeur', 'editeur');
}

Vous pouvez aussi avec le troisième paramètre indiquer le nom de la clé de la table editeurs si elle ne s'appelle pas « id ».

Je peux maintenant écrire cela :

$nom = Contact::find(5)->editeur()->first()->nom;

Et je trouve le nom de l'éditeur pour le contact sélectionné. Eloquent génère ces deux requêtes :

select * from `contacts` where `id` = '5' limit 1
select * from `editeurs` where `editeurs`.`id` = '5' limit 1

Comme Eloquent est très conciliant vous pouvez même écrire cela :

$nom = Contact::find(5)->editeur->nom;

Ce qui rend la syntaxe particulièrement élégante et lisible !

Commençons par nous situer dans la table des pays. Je me dis « j'ai beaucoup de villes » :

Pour traduire cela de façon concrète on crée dans le modèle Pays une méthode :

public function villes()
{
    return $this->hasMany('Ville');
}

Voyons cette méthode dans la classe Model :

public function hasMany($related, $foreignKey = null, $localKey = null)
{
    $foreignKey = $foreignKey ?: $this->getForeignKey();
 
    $instance = new $related;
 
    $localKey = $localKey ?: $this->getKeyName();
 
    return new HasMany($instance->newQuery(), $this, $instance->getTable().'.'.$foreignKey, $localKey);
}

Si la clé étrangère n'est pas renseignée, elle est construite à partir du nom du modèle. Dans notre cas on a donc « pays_id ». Vous avez aussi la possibilité de renseigner le deuxième paramètre si votre champ ne correspond pas à la norme :

public function villes()
{
    return $this->hasMany('Ville', 'pays');
}

Le troisième paramètre sert à indiquer le nom de la clé pour la table des pays si ce n'est pas « id », comme on l'a déjà vu pour les autres méthodes ci-dessus.

Je peux maintenant écrire cela :

Pays::find(4)->villes->each(function($ville)
{
    echo $ville->nom, '<br>';
});

Je trouve toutes les villes pour le pays d'id 5. J'itère dans la collection obtenue pour récupérer les noms des villes. Eloquent génère ces deux requêtes :

select * from `pays` where `id` = '4' limit 1
select * from `villes` where `villes`.`pays_id` = '4'

Dans mon cas j'obtiens ce résultat :

Ville 1
Ville 2
Ville 10

Vous pouvez évidemment avoir un résultat différent étant donné que j'ai rempli les tables avec des valeurs aléatoires.

Voyons maintenant la relation à partir de la table des villes :

Là je me dis que « j'appartiens à un seul pays ». On retrouve donc le belongsTo qu'on à déjà vu pour la relation de type 1:1. La situation est strictement la même et donc le traitement identique. Tout ce que j'ai dit ci-dessus est donc valable aussi pour la relation de type 1:n. En fait Eloquent est totalement ignorant du type de relation, son seul repère est la méthode utilisée. Donc quand vous employez la méthode belongsTo il ne sait absolument pas si vous avez mis en place une relation 1:1 ou 1:n et il n'en a pas besoin. Il agit de façon localisée.

Voyons maintenant une extension de hasMany avec hasManyThrough. Regardez cette partie de la base d'exemple :

On a la relation 1:n vue ci-dessus entre les pays et les villes. On a le même type de relation entres les villes et les auteurs. La méthode hasManyThrough permet de « traverser » la table des villes pour mettre directement en relation la table des pays avec celle des auteurs :

Autrement dit on veut tous les auteurs d'un pays. Pour traduire cela de façon concrète, on crée dans le modèle Pays une méthode auteurs :

public function auteurs()
{
    return $this->hasManyThrough('Auteur', 'Ville');
}

Voyons cette méthode dans la classe Model :

public function hasManyThrough($related, $through, $firstKey = null, $secondKey = null)
{
    $through = new $through;
 
    $firstKey = $firstKey ?: $this->getForeignKey();
 
    $secondKey = $secondKey ?: $through->getForeignKey();
 
    return new HasManyThrough(with(new $related)->newQuery(), $this, $through, $firstKey, $secondKey);
}

Analysons les paramètres :

1. C'est le modèle de destination, dans notre cas Auteur ;
2. C'est le modèle intermédiaire, dans notre cas Ville ;
3. Là on peut mettre la clé étrangère dans la table intermédiaire si elle n'est pas à la norme, nous on a bien pays_id ;
4. Là on peut mettre la clé étrangère dans la table finale si elle n'est pas à la norme, nous on a bien ville_id.

Maintenant on peut écrire ça :

Pays::find(4)->auteurs->each(function($auteur)
{
    echo $auteur->nom, '<br>';
});

J'obtiens ce résultat dans mon cas :

Auteur 2
Auteur 6
Auteur 13
Auteur 19
Auteur 14
Auteur 8
Auteur 15

Eloquent s'en sort avec deux requêtes dont une jointure :

select * from `pays` where `id` = '4' limit 1
select `auteurs`.*, `villes`.`pays_id` from `auteurs` inner join `villes` on `villes`.`id` = `auteurs`.`ville_id` where `villes`.`pays_id` = '4'

Maintenant comment faire l'inverse de hasManyThrough ? Pas besoin d'inventer quelque chose de nouveau, il suffit d'enchaîner deux belongsTo. Par exemple ce code :

Auteur::find(2)->ville->pays->nom;

va nous donner le nom du pays pour l'auteur d'id 2. Élégant non ?

Comme la relation est symétrique on a une seule méthode : belongsToMany. En effet si je me place du côté de la table des auteurs je me dis « j'appartiens à plusieurs livres » (bon c'est une image, il ne faut pas que les auteurs se sentent possédés par leurs œuvres ) et réciproquement du côté de la table des livres je me dis « j'appartiens à plusieurs auteurs » :

Pour concrétiser ça, on crée une méthode livres dans le modèle Auteur :

public function livres()
{
    return $this->belongsToMany('Livre');
}

Et évidemment on crée la réciproque auteurs dans le modèle Livre :

public function auteurs()
{
    return $this->belongsToMany('Auteur');
}

Regardez la signature de la méthode belongsToMany :

public function belongsToMany($related, $table = null, $foreignKey = null, $otherKey = null, $relation = null)

Les paramètres doivent vous être maintenant familiers parce qu'ils se répètent au fil des méthodes :

1. Là on met le nom du modèle de la table visée ;
2. Là on met le nom de la table pivot s'il n'est pas conventionnel, nous on a bien choisi auteur_livre (livre_auteur aurait aussi marché) ;
3. Là on met le nom de la clé étrangère de la table de départ s'il n'est pas conventionnel ;
4. Là on met le nom de la clé étrangère de la table d'arrivée s'il n'est pas conventionnel.

Maintenant si on veut connaître tous les titres des livres d'un auteur c'est facile :

Auteur::find(4)->livres->each(function($livre)
{
    echo $livre->titre, '<br>';
});

Dans mon cas j'obtiens :

Titre 8
Titre 24
Titre 7
Titre 39

Voici les requêtes générées :

select * from `auteurs` where `id` = '4' limit 1
select `livres`.*, `auteur_livre`.`auteur_id` as `pivot_auteur_id`, `auteur_livre`.`livre_id` as `pivot_livre_id` from `livres` inner join `auteur_livre` on `livres`.`id` = `auteur_livre`.`livre_id` where `auteur_livre`.`auteur_id` = '4'

De la même manière on peut récupérer le nom des auteurs d'un livre :

Livre::find(4)->auteurs->each(function($auteur)
{
    echo $auteur->nom, '<br>';
});

Ici j'obtiens :

Auteur 1
Auteur 13

Eloquent propose la méthode morphTo pour établir une relation polymorphique à partir de la table qui est du côté n. Il faut donc prévoir cette méthode dans le modèle Livre :

public function livrable()
{
    return $this->morphTo();
}

Voici la signature de la méthode morphTo :

public function morphTo($name = null, $type = null, $id = null)

Voyons les paramètres :

1. C'est le nom de la relation, et si on n'en donne pas c'est le nom de la méthode qui est utilisé ;
2. C'est le nom du champ qui récupère le type du modèle en liaison, mais si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _type » ; dans notre cas on a déjà livrable_type ;
3. C'est le nom du champ qui récupère la clé étrangère, et si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _id », dans notre cas on a déjà livrable_id.

Bon maintenant vous vous demandez peut-être pourquoi se donner autant de peine ? Regardez ce code :

Livre::take(5)->get()->each(function($livre)
{
    echo $livre->livrable->nom, '<br>';
});

Je prends les cinq premiers livres et dans une boucle je récupère le nom dans la table en relation. La méthode livrable va créer une instance du modèle correspondant, soit Editeur, soit Autoedite selon que le livre est en relation avec l'un ou l'autre. Voilà ce que j'obtiens :

Editeur 4
Editeur 4
Editeur 11
Autoedite 2
Autoedite 18

Voyons à présent la relation inverse avec morphMany. Par exemple pour les éditeurs, on doit ajouter la méthode dans le modèle :

public function livres()
{
    return $this->morphMany('Livre', 'livrable');
}

Voici la signature de cette méthode :

public function morphMany($related, $name, $type = null, $id = null, $localKey = null)

Voyons les paramètres :

1. C'est le nom du modèle de la table ciblée, dans notre cas Livre ;
2. C'est le nom de la relation, dans notre cas livrable ;
3. C'est le nom du champ qui récupère le type du modèle en liaison, et si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _type » ; dans notre cas on a déjà livrable_type ;
4. C'est le nom du champ qui récupère la clé étrangère, et si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _id » ; dans notre cas on a déjà livrable_id ;
5. C'est le nom de l'id de la table de départ, et dans notre cas on a « id », valeur par défaut.

Pour le fonctionnement c'est exactement comme un hasMany. On peut par exemple trouver les livres d'un éditeur avec ce code :

Editeur::find(4)->livres->each(function($livre)
{
    echo $livre->titre, '<br>';
});

Dans mon cas j'obtiens ça :

Titre 1
Titre 2
Titre 26

Du côté des deux tables on utilise la méthode morphToMany. Dans le modèle Categorie :

public function themes()
{
    return $this->morphToMany('Theme', 'themable');
}

Et dans le modèle Periode :

public function themes()
{
    return $this->morphToMany('Theme', 'themable');
}

Voici la signature de la méthode morphToMany :

public function morphToMany($related, $name, $table = null, $foreignKey = null, $otherKey = null, $inverse = false)

Pas moins que six paramètres :

1. C'est le nom du modèle de la table ciblée, dans notre cas Theme ;
2. C'est le nom de la relation, dans notre cas themable ;
3. C'est le nom de la table pivot construit à partir du deuxième paramètre auquel on ajoute « s », dans notre cas on a déjà themables ;
4. C'est le nom du champ qui récupère la clé étrangère ; si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _id », dans notre cas on a déjà themable_id ;
5. C'est le nom du champ qui récupère le type du modèle en liaison, si on n'en donne pas il est nommé à partir du nom de la relation auquel on ajoute « _type », dans notre cas on a déjà themable_type ;
6. ce dernier paramètre m'intrigue, je ne l'ai pas encore vraiment compris donc il méritera des tests complémentaires…

Je peux maintenant trouver tous les thèmes pour une catégorie :

Categorie::find(2)->themes->each(function($theme)
{
    echo $theme->nom, '<br>';
});

Ou pour une période :

Periode::find(2)->themes->each(function($theme)
{
    echo $theme->nom, '<br>';
});

Voyons maintenant la relation inverse morphedByMany. On se place cette fois du côté de la table des thèmes. On doit déclarer une méthode par table reliée :

public function categories()
{
    return $this->morphedByMany('Categorie', 'themable');
}
 
public function periodes()
{
    return $this->morphedByMany('Periode', 'themable');
}

La méthode morphedByMany a cette signature :

public function morphedByMany($related, $name, $table = null, $foreignKey = null, $otherKey = null)

Je ne commente pas ces paramètres qui sont les mêmes que ceux de la méthode morphToMany. On peut alors trouver par exemple toutes les catégories pour un thème :

Theme::find(2)->categories->each(function($categorie)
{
    echo $categorie->nom, '<br>';
});

Avec cette relation polymorphique s'achève ce tour d'horizon des relations traitées par Eloquent. Il existe aussi la méthode morphOne pour les relations de type 1:1 mais franchement c'est anecdotique étant donné la rareté de la chose ; elle n'est d'ailleurs même pas citée dans la documentation.

J'aborderai dans un prochain chapitre la gestion de tout ça. En effet quand on crée des relations, ça a évidemment une conséquence sur la manipulation des enregistrements dans les tables et ce n'est pas toujours rose .