🎜{tip} Il s'agit d'un aperçu de haut niveau des ressources et collections de ressources . Il est fortement recommandé de lire les autres sections de ce document pour mieux comprendre comment mieux personnaliser et utiliser la ressource. 🎜

<?php
    namespace App\Http\Resources;
    use Illuminate\Http\Resources\Json\ResourceCollection;
    class UserCollection extends ResourceCollection{ 
     /**
     * 将资源集合转换成数组。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */   
     public function toArray($request) 
        {       
         return [          
           'data' => $this->collection,            
           'links' => [           
                'self' => 'link-value',     
                  ],     
                ];   
           }
         }

use App\User;
use App\Http\Resources\UserCollection;
Route::get('/users', function () { 
   return new UserCollection(User::all());
  });

Resource Collection

<?php
    namespace App\Http\Resources;
    use Illuminate\Http\Resources\Json\JsonResource;
    class User extends JsonResource{  
      /**
     * 指示是否应保留资源的集合键。
     *
     * @var bool
     */    
   public $preserveKeys = true;
 }

Bien sûr, en utilisant la méthode ci-dessus, vous ne pourrez pas ajouter de métadonnées supplémentaires et les renvoyer avec la collection. Si vous avez besoin d'une réponse de collection de ressources personnalisée, vous devez créer une ressource dédiée pour représenter la collection :

use App\User;
use App\Http\Resources\User as UserResource;
Route::get('/user', function () {
    return UserResource::collection(User::all()->keyBy->id);
  });

Vous pouvez facilement définir les métadonnées que vous souhaitez renvoyer dans la réponse dans la classe de collection de ressources générée :

<?php
    namespace App\Http\Resources;
    use Illuminate\Http\Resources\Json\ResourceCollection;
    class UserCollection extends ResourceCollection{  
      /**
     * collects 属性定义了资源类。
     *
     * @var string
     */   
     public $collects = 'App\Http\Resources\Member';
    }

Vous pouvez retourner une collection définie de ressources dans une route ou un contrôleur :

<?php
    namespace App\Http\Resources;
    use Illuminate\Http\Resources\Json\JsonResource;
    class User extends JsonResource{  
      /**
     * 将资源转换成数组。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */   
      public function toArray($request) 
         {      
           return [          
             'id' => $this->id,            
             'name' => $this->name,            
             'email' => $this->email,            
             'created_at' => $this->created_at,            
             'updated_at' => $this->updated_at,     
             ];  
          }
       }

Protéger les clés de collection

Lors du retour d'une collection de ressources à partir d'une route, Laravel réinitialisera les clés de la collection afin qu'elles soient dans un ordre numérique simple. Cependant, l'attribut preserveKeys peut être ajouté à la classe de ressources pour indiquer si les clés de collection doivent être préservées : preserveKeys 属性添加到资源类中，指示是否应保留集合键：

use App\User;
use App\Http\Resources\User as UserResource;
Route::get('/user', function () { 
   return new UserResource(User::find(1));
 });

当 preserveKeys 属性被设置为 true, 集合的键将会被保护:

/**
 * 将资源转换成数组。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){ 
    return [    
        'id' => $this->id,        
        'name' => $this->name,        
        'email' => $this->email,        
        'posts' => PostResource::collection($this->posts),        
        'created_at' => $this->created_at,        
        'updated_at' => $this->updated_at,    
       ];
    }

自定义基础资源类

通常，资源集合的 $this->collection 属性会自动填充，结果是将集合的每个项映射到其单个资源类。假定单一资源类是集合的类名，但结尾没有 Collection 字符串。

例如，UserCollection 将给定的用户实例映射到 User 资源中。若要自定义此行为，你可以重写资源集合的 $collects 属性：

use App\User;
use App\Http\Resources\User as UserResource;
Route::get('/user', function () {
    return UserResource::collection(User::all());
 });

Writing Resources

use App\User;
use App\Http\Resources\UserCollection;
Route::get('/users', function () {
    return new UserCollection(User::paginate());
  });

{  
  "data": [    
          {           
             "id": 1,            
             "name": "Eladio Schroeder Sr.",            
             "email": "therese28@example.com",      
          },        
          {          
            "id": 2,            
            "name": "Liliana Mayert",            
            "email": "evandervort@example.com",       
           }    
         ],   
    "links":{      
              "first": "http://example.com/pagination?page=1",        
              "last": "http://example.com/pagination?page=1",        
              "prev": null,        
              "next": null   
             },   
    "meta":{       
             "current_page": 1,       
             "from": 1,        
             "last_page": 1,        
             "path": "http://example.com/pagination",        
             "per_page": 15,        
             "to": 10,        
             "total": 10   
            }
}

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [   
          'id' => $this->id,        
          'name' => $this->name,        
          'email' => $this->email,        
          'secret' => $this->when(Auth::user()->isAdmin(), 'secret-value'),        
          'created_at' => $this->created_at,        
          'updated_at' => $this->updated_at,  
          ];
      }

🎜{tip} Si vous uniquement Pour ajouter des ressources associées uniquement lorsque l'association est chargée, consultez la documentation sur les associations conditionnelles. 🎜

'secret' => $this->when(Auth::user()->isAdmin(), function () {
    return 'secret-value';
  }),

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [  
           'id' => $this->id,        
           'name' => $this->name,        
           'email' => $this->email,        
          $this->mergeWhen(Auth::user()->isAdmin(), [         
             'first-secret' => 'value',            
             'second-secret' => 'value',        
           ]),       
          'created_at' => $this->created_at,        
          'updated_at' => $this->updated_at,    
        ];
    }

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [     
        'id' => $this->id,        
        'name' => $this->name,        
        'email' => $this->email,        
        'posts' => PostResource::collection($this->whenLoaded('posts')),        
        'created_at' => $this->created_at,        
        'updated_at' => $this->updated_at,  
         ];
    }

Data Wrapping

Par défaut, lorsque la réponse de la ressource est convertie en JSON, la ressource de niveau supérieur sera encapsulée dans la clé data. Ainsi, une réponse typique de collecte de ressources ressemble à ceci : data 键中。因此一个典型的资源集合响应如下所示：

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [     
        'id' => $this->id,        
        'name' => $this->name,        
        'expires_at' => $this->whenPivotLoaded('role_user', function () {    
                return $this->pivot->expires_at;       
                 }),   
             ];
         }

你可以使用资源基类的 withoutWrapping 方法来禁用顶层资源的包裹。通常，你应该在  AppServiceProvider  或其他在程序每一个请求中都会被加载的 服务提供者 中调用此方法：

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [   
          'id' => $this->id,        
          'name' => $this->name,        
          'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () { 
                     return $this->subscription->expires_at;       
                 }),    
            ];
       }

{note} withoutWrappin 方法只会禁用顶层资源的包裹，不会删除你手动添加到资源集合中的 data 键。

包裹嵌套资源

你可以完全自由地决定资源关联如何被包裹。如果你希望无论怎样嵌套，都将所有资源集合包裹在 data 键中，那么你需要为每个资源都定义一个资源集合类，并将返回的集合包裹在 data 键中。

当然，你可能会担心这样顶层资源将会被包裹在两个 data 键中。请放心， Laravel 将永远不会让你的资源被双层包裹，因此你不必担心被转换的资源集合会被多重嵌套：

/**
 * 将资源转换成数组
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
 public function toArray($request){
     return [ 
            'data' => $this->collection,        
            'links' => [          
              'self' => 'link-value',      
              ],   
            ];
     }

数据包裹和分页

当在资源响应中返回分页集合时，即使你调用了 withoutWrapping 方法， Laravel 也会将你的资源数据包裹在 data 键中。这是因为分页响应中总会有 meta 和 links 键包含着分页状态信息：

<?php
    namespace App\Http\Resources;
    use Illuminate\Http\Resources\Json\ResourceCollection;
    class UserCollection extends ResourceCollection{   
       /**
     * 将资源集合转换成数组
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */    
     public function toArray($request) 
        {      
          return parent::toArray($request);  
         }   
     /**
     * 返回应该和资源一起返回的其他数据数组
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */   
     public function with($request) 
        {    
            return [         
               'meta' => [                
               'key' => 'value',           
              ],      
             ];   
         }
     }