PHP Fractal - Faites de votre API JSON Pretty, toujours!

Cet article a été évalué par des pairs par Viraj Khatavkar. Merci à tous les pairs examinateurs de SitePoint pour avoir obtenu le contenu de SitePoint à son meilleur!

---

Si vous avez déjà construit l'API, je parie que vous êtes habitué à la sortie des données directement en réponse. Cela peut ne pas être nocif s'il est fait correctement, mais il existe des alternatives pratiques qui peuvent aider à résoudre ce problème.

L'une des solutions disponibles est fractale. Il nous permet de créer une nouvelle couche de transformation pour le modèle avant de retourner le modèle en réponse. Il est très flexible et facile à intégrer dans n'importe quelle application ou cadre.

points clés

• PHP Fractal est une solution qui permet aux développeurs de créer de nouvelles couches de transformation pour leurs modèles avant de les retourner en réponses, ce qui rend les données JSON plus faciles à gérer et cohérentes.
• Fractal est flexible et facile à intégrer dans n'importe quelle application ou cadre. Il fonctionne en utilisant le transformateur pour convertir des structures de données complexes en formats plus simples et en utilisant le sérialiseur pour formater la sortie finale.
• Fractal permet également l'inclusion de sous-ressources (relations) dans la réponse lorsqu'elle est demandée par l'utilisateur, ajoutant une autre couche de flexibilité et de contrôle au rendu des données.
• L'utilisation de fractal peut optimiser les performances de la requête en chargeant des relations à la fois, résolvant ainsi les problèmes N 1 que le chargement paresseux éloquent rencontre souvent.

Installation

Nous utiliserons l'application Laravel 5.3 pour créer l'exemple et intégrer le package fractal avec lui, alors allez-y et utilisez l'installateur ou créez une nouvelle application Laravel via Composer.

<code>laravel new demo</code>

ou

<code>composer create-project laravel/laravel demo</code>

Ensuite, dans le dossier, nous avons besoin du package fractal.

<code>composer require league/fractal</code>

Créer une base de données

Notre base de données contient des utilisateurs et des tables de rôles. Chaque utilisateur a un rôle et chaque rôle a une liste d'autorisation.

<code class="language-php">// app/User.php

class User extends Authenticatable
{
    protected $fillable = [
        'name',
        'email',
        'password',
        'role_id',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];

    /**
     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
     */
    public function role()
    {
        return $this->belongsTo(Role::class);
    }
}</code>

<code class="language-php">// app/Role.php

class Role extends Model
{
    protected $fillable = [
        'name',
        'slug',
        'permissions'
    ];

    /**
     * @return \Illuminate\Database\Eloquent\Relations\HasMany
     */
    public function users()
    {
        return $this->hasMany(User::class);
    }
}</code>

Créer un transformateur

Nous créerons un transformateur pour chaque modèle. Notre classe UserTransformateur ressemble à ceci:

<code class="language-php">// app/Transformers/UserTransformer.php

namespace App\Transformers;

use App\User;
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{
    public function transform(User $user)
    {
        return [
            'name' => $user->name,
            'email' => $user->email
        ];
    }
}</code>

Oui, créer un transformateur est aussi simple! Il convertit simplement les données d'une manière que les développeurs peuvent gérer, et non à la laisser à l'ORM ou au référentiel.

Nous étendons la classe TransformorAbstrait et définissons la méthode de transformation, qui sera appelée à l'aide de l'instance utilisateur. Il en va de même pour la classe RoletRansformrer.

<code class="language-php">namespace App\Transformers;

use App\Role;
use League\Fractal\TransformerAbstract;

class RoleTransformer extends TransformerAbstract
{
    public function transform(Role $role)
    {
        return [
            'name' => $role->name,
            'slug' => $role->slug,
            'permissions' => $role->permissions
        ];
    }
}</code>

Créer un contrôleur

Nos contrôleurs doivent convertir des données avant de les renvoyer à l'utilisateur. Nous allons désormais gérer la classe USERSController et définir temporairement uniquement les opérations d'index et afficher.

<code class="language-php">// app/Http/Controllers/UsersController.php

class UsersController extends Controller
{
    /**
     * @var Manager
     */
    private $fractal;

    /**
     * @var UserTransformer
     */
    private $userTransformer;

    function __construct(Manager $fractal, UserTransformer $userTransformer)
    {
        $this->fractal = $fractal;
        $this->userTransformer = $userTransformer;
    }

    public function index(Request $request)
    {
        $users = User::all(); // 从数据库获取用户
        $users = new Collection($users, $this->userTransformer); // 创建资源集合转换器
        $users = $this->fractal->createData($users); // 转换数据

        return $users->toArray(); // 获取转换后的数据数组
    }
}</code>

L'opération d'index interrogera tous les utilisateurs de la base de données, créera une collection de ressources à l'aide de la liste d'utilisateurs et du convertisseur, puis effectuera le processus de conversion réel.

<code class="language-json">{
  "data": [
    {
      "name": "Nyasia Keeling",
      "email": "crooks.maurice@example.net"
    },
    {
      "name": "Laron Olson",
      "email": "helen55@example.com"
    },
    {
      "name": "Prof. Fanny Dach III",
      "email": "edgardo13@example.net"
    },
    {
      "name": "Athena Olson Sr.",
      "email": "halvorson.jules@example.com"
    }
    // ...
  ]
}</code>

Bien sûr, il n'a pas de sens de retourner tous les utilisateurs à la fois, et nous devons implémenter le téléavertisseur pour cela.

pagination

Laravel a tendance à simplifier les choses. Nous pouvons implémenter une pagination comme ceci:

<code>laravel new demo</code>

Mais pour que cela fonctionne avec Fractal, nous devrons peut-être ajouter du code pour convertir les données, puis appeler le téléavertisseur.

<code>composer create-project laravel/laravel demo</code>

La première étape consiste à paginer les données du modèle. Ensuite, nous créons une collection de ressources comme avant, puis configutons un téléavertisseur sur la collection.

Fractal fournit à Laravel un adaptateur Paginator pour convertir la classe LongtawarePaginator, qui fournit également un adaptateur pour Symfony et Zend.

<code>composer require league/fractal</code>

Notez qu'il ajoute des champs supplémentaires aux détails de la pagination. Vous pouvez en savoir plus sur la pagination dans la documentation.

comprend les sous-ressources

Maintenant que nous connaissons Fractal, il est temps d'apprendre à inclure des sous-ressources (relations) dans la réponse lorsqu'un utilisateur demande.

Nous pouvons demander d'inclure des ressources supplémentaires dans la réponse, par exemple http://demo.vaprobash.dev/users?include=role. Notre convertisseur peut détecter automatiquement ce qui est demandé et analyser le paramètre Inclure.

<code class="language-php">// app/User.php

class User extends Authenticatable
{
    protected $fillable = [
        'name',
        'email',
        'password',
        'role_id',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];

    /**
     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
     */
    public function role()
    {
        return $this->belongsTo(Role::class);
    }
}</code>

Le

$ disponible comprend la propriété indique au convertisseur que nous devrons peut-être inclure des données supplémentaires dans la réponse. Si le paramètre d'inclusion de requête demande le rôle utilisateur, il appellera la méthode incluse.

<code class="language-php">// app/Role.php

class Role extends Model
{
    protected $fillable = [
        'name',
        'slug',
        'permissions'
    ];

    /**
     * @return \Illuminate\Database\Eloquent\Relations\HasMany
     */
    public function users()
    {
        return $this->hasMany(User::class);
    }
}</code>

$ this- & gt; fractal- & gt; parseincludes line est responsable de l'analyse incluant les paramètres de requête. Si nous demandons une liste d'utilisateurs, nous devrions voir quelque chose comme ceci:

<code class="language-php">// app/Transformers/UserTransformer.php

namespace App\Transformers;

use App\User;
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{
    public function transform(User $user)
    {
        return [
            'name' => $user->name,
            'email' => $user->email
        ];
    }
}</code>

Si chaque utilisateur a une liste de rôles, nous pouvons changer le convertisseur en quelque chose comme ceci:

<code class="language-php">namespace App\Transformers;

use App\Role;
use League\Fractal\TransformerAbstract;

class RoleTransformer extends TransformerAbstract
{
    public function transform(Role $role)
    {
        return [
            'name' => $role->name,
            'slug' => $role->slug,
            'permissions' => $role->permissions
        ];
    }
}</code>

Lorsque

contient des sous-ressources, nous pouvons utiliser les relations Point Notation pour nicher . Supposons que chaque rôle ait une liste d'autorisations stockées dans un tableau séparé et que nous voulons répertorier les utilisateurs avec leurs rôles et autorisations. On peut faire inclure = role.Permissions.

Parfois, nous devons inclure certaines associations nécessaires par défaut, telles que les associations d'adresses. Nous pouvons le faire en utilisant la propriété de défaut de DefaultCluds dans le convertisseur.

<code class="language-php">// app/Http/Controllers/UsersController.php

class UsersController extends Controller
{
    /**
     * @var Manager
     */
    private $fractal;

    /**
     * @var UserTransformer
     */
    private $userTransformer;

    function __construct(Manager $fractal, UserTransformer $userTransformer)
    {
        $this->fractal = $fractal;
        $this->userTransformer = $userTransformer;
    }

    public function index(Request $request)
    {
        $users = User::all(); // 从数据库获取用户
        $users = new Collection($users, $this->userTransformer); // 创建资源集合转换器
        $users = $this->fractal->createData($users); // 转换数据

        return $users->toArray(); // 获取转换后的数据数组
    }
}</code>

L'une de mes choses préférées sur le package fractal est la possibilité de passer des paramètres pour inclure les paramètres. Un bon exemple dans la documentation est le tri dans l'ordre. Nous pouvons l'appliquer à notre exemple comme suit:

<code class="language-json">{
  "data": [
    {
      "name": "Nyasia Keeling",
      "email": "crooks.maurice@example.net"
    },
    {
      "name": "Laron Olson",
      "email": "helen55@example.com"
    },
    {
      "name": "Prof. Fanny Dach III",
      "email": "edgardo13@example.net"
    },
    {
      "name": "Athena Olson Sr.",
      "email": "halvorson.jules@example.com"
    }
    // ...
  ]
}</code>

La partie importante ici est la liste ($ ordonnance, $ ordonnance) = $ parambag- & gt; get ('ordonnance') ?: ['Created_at', 'desc'];, qui essaiera d'obtenir le paramètre de commande à partir de L'utilisateur inclut et l'applique au constructeur de requête.

Nous pouvons maintenant trier les listes d'utilisateurs incluses dans l'ordre en passant par des paramètres (/ rôles? Inclure = utilisateurs: commande (nom | ASC)). Vous pouvez en savoir plus sur l'inclusion de ressources dans la documentation.

Mais que se passe-t-il si l'utilisateur n'a pas de rôles associés? Il s'arrête et une erreur apparaît car elle attend des données valides au lieu de Null. Supprimons la relation de la réponse au lieu d'afficher sa valeur nulle.

<code>laravel new demo</code>

Chargement d'urgence

Étant donné que les retards éloquents chargent le modèle lors de l'accès, nous pouvons rencontrer des problèmes n 1 . Cela peut être résolu par une relation de chargement unique pour optimiser les requêtes.

<code>composer create-project laravel/laravel demo</code>

De cette façon, nous n'aurons pas de requêtes supplémentaires lors de l'accès à la relation modèle.

Conclusion

Je suis tombé sur Fractal tout en lisant "Building a API que vous ne détestez pas" de Phil Sturgeon, une lecture formidable et informative que je recommande fortement.

Avez-vous utilisé un convertisseur lors de la construction de votre API? Avez-vous un package préféré qui fait le même travail, ou utilisez-vous simplement json_encode? Veuillez nous le faire savoir dans la section des commentaires ci-dessous!

FAQ fractale PHP

Qu'est-ce que PHP Fractal et pourquoi cela compte?

PHP Fractal est un outil puissant qui aide à rendre et à transformer les données de l'API. Il est important car il fournit un moyen standardisé de sortir des structures de données complexes et imbriquées, garantissant que la sortie de données de l'API est cohérente, bien structurée et facile à comprendre. Cela permet aux développeurs d'utiliser plus facilement votre API et de réduire la possibilité d'erreurs.

Comment fonctionne la fractale PHP?

Fractal PHP fonctionne en prenant des structures de données complexes et en les convertissant en formats plus faciles à utiliser. Il est implémenté par deux composants principaux: le transformateur et le sérialiseur. Le transformateur est responsable de la conversion de données complexes en formats plus simples, tandis que le sérialiseur forme la sortie finale.

Qu'est-ce que le transformateur en fractale PHP?

Le transformateur dans PHP Fractal est une classe qui définit la façon dont les données d'application doivent être sorties dans la réponse de l'API. Ils prennent des structures de données complexes et les convertissent en formats plus simples et plus faciles à utiliser. Cela vous permet de contrôler avec précision les données incluses dans la réponse de l'API et comment elles sont structurées.

Qu'est-ce que le sérialiseur dans PHP Fractal?

Le sérialiseur en fractale PHP est responsable de la mise en forme de la sortie finale de l'API. Ils prennent les données qui ont été converties par le transformateur et les formatent en une structure spécifique. Cela vous permet de vous assurer que la sortie de l'API est cohérente et facile à comprendre.

Comment implémenter PHP Fractal dans mon projet?

La mise en œuvre de la fractale PHP dans un projet consiste à installer la bibliothèque fractale via Composer, à créer un transformateur pour les données, puis à utiliser la classe fractale pour transformer les données à l'aide du transformateur. Vous pouvez ensuite utiliser l'un des sérialiseurs de Fractal pour produire les données converties.

Puis-je utiliser PHP Fractal avec un projet PHP?

Oui, PHP Fractal est une bibliothèque autonome qui peut être utilisée avec n'importe quel projet PHP. Il ne s'appuie sur aucun cadre ou plate-forme spécifique, ce qui en fait un outil universel pour tout développeur PHP.

Quels sont les avantages de l'utilisation de la fractale PHP?

L'utilisation de la fractale PHP offre de nombreux avantages. Il garantit que la sortie de l'API est cohérente et bien structurée, ce qui facilite l'utilisation des développeurs. Il fournit également un moyen standardisé de transformer des structures de données complexes, en réduisant la possibilité d'erreurs et en rendant le code plus facile à maintenir.

Comment PHP Fractal se compare-t-il aux autres outils de conversion de données?

PHP Fractal ressort pour sa simplicité et sa flexibilité. Il fournit un moyen simple de transformer des structures de données complexes, et il permet une personnalisation élevée en utilisant le transformateur et le sérialiseur. Cela en fait un outil puissant pour tout développeur qui utilise des API.

Puis-je personnaliser la sortie de PHP Fractal?

Oui, PHP Fractal est hautement personnalisable. Vous pouvez créer des transformateurs personnalisés pour contrôler avec précision comment vos données sont converties, et vous pouvez formater la sortie de différentes manières en utilisant différents sérialisateurs. Cela vous permet d'ajuster la sortie de votre API à vos besoins spécifiques.

Où puis-je en savoir plus sur PHP Fractal?

Il existe de nombreuses ressources pour vous aider à en savoir plus sur PHP Fractal. Le site officiel de la Ligue PHP fournit une documentation complète et il existe de nombreux tutoriels et articles de blog en ligne. De plus, le référentiel GHUB Fractal PHP est un excellent endroit pour explorer le code et voir des exemples de la façon dont il est utilisé.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!