Fasih: sumber API

• Pengenalan
• Menjana sumber
• Gambaran keseluruhan konsep
  • Sumber koleksi
• • Pakej Data
  • Penomboran
  • Atribut Bersyarat
  • Persatuan Bersyarat
  • Tambah Metadata
• Respon Sumber

Apabila membina API, anda sering memerlukan lapisan transformasi untuk menghubungkan anda The Eloquent model dan respons JSON sebenar dikembalikan kepada pengguna. Kelas sumber Laravel membolehkan anda menukar model dan koleksi model kepada JSON dengan cara yang lebih intuitif dan mudah.

Jana sumber

Anda boleh menggunakan perintah make:resource Artisan untuk menjana kelas sumber. Secara lalai, sumber yang dijana akan diletakkan dalam folder app/Http/Resources aplikasi. Sumber diwarisi daripada kelas IlluminateHttpResourcesJsonJsonResource:

php artisan make:resource User

Koleksi Sumber

Selain menjana sumber untuk menukar model tunggal, anda juga boleh menjana koleksi sumber untuk menukar koleksi model . Ini membolehkan anda memasukkan pautan dan maklumat meta lain yang berkaitan dengan sumber yang diberikan dalam respons. make:resource Artisan 命令来生成一个资源类。默认情况下生成的资源都会被放置在应用程序的 app/Http/Resources 文件夹下。资源继承自 IlluminateHttpResourcesJsonJsonResource 类：

php artisan make:resource Users --collection

php artisan make:resource UserCollection

资源集合

除了生成资源转换单个模型外，你还可以生成资源集合用来转换模型的集合。这允许你在响应中包含与给定资源相关的链接与其他元信息。

你需要在生成资源时添加 --collection 标志以生成一个资源集合。或者，你也可以直接在资源的名称中包含 Collection 向 Laravel 表示应该生成一个资源集合。资源集合继承自 IlluminateHttpResourcesJsonResourceCollection 类：

<?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,        
             ];   
         }
      }

概念综述

{tip} 这是对资源和资源集合的高度概述。强烈建议你阅读本文档的其他部分，以深入了解如何更好地自定义和使用资源。

在深入了解如何定制化编写你的资源之前，让我们先来看看在 Laravel 中如何使用资源。一个资源类表示一个单一模型需要被转换成 JSON 格式。例如，现在我们有一个简单的 User 资源类：

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

每一个资源类都定义了一个 toArray 方法，在发送响应时它会返回应该被转化成 JSON 的属性数组。注意在这里我们可以直接使用 $this 变量来访问模型属性。这是因为资源类将自动代理属性和方法到底层模型以方便访问。你可以在路由或控制器中返回已定义的资源：

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

资源集合

你可以在路由或者控制器中使用 collection

php artisan make:resource UserCollection

<?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());
  });

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

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

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

<?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,     
             ];  
          }
       }

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

/**
 * 将资源转换成数组。
 *
 * @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,    
       ];
    }

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

编写资源

{tip} 如果你还没有阅读 概念综述，那么在继续阅读本文档前，强烈建议你去阅读一下。

从本质上来说，资源的作用很简单。它们只需要将一个给定的模型转换成一个数组。所以每一个资源都包含一个 toArray 方法用来将你的模型属性转换成一个可以返回给用户的 API 友好数组：

<?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());
  });

关联

如果你希望在响应中包含关联资源，你只需要将它们添加到 toArray 方法返回的数组中。在下面这个例子里，我们将使用 Post 资源的 collection 方法将用户的文章添加到资源响应中：

{    
    "data": [  
          {          
            "id": 1,            
            "name": "Eladio Schroeder Sr.",            
            "email": "therese28@example.com",       
           },       
           {           
            "id": 2,            
            "name": "Liliana Mayert",            
            "email": "evandervort@example.com",       
           }    
          ]
 }

{tip}  如果你只想在关联已经加载时才添加关联资源，请查看文档 条件关联 。

资源集合

资源是将单个模型转换成数组，而资源集合是将多个模型的集合转换成数组。所有的资源都提供了一个 collection

<?php
    namespace App\Providers;
    use Illuminate\Support\ServiceProvider;
    use Illuminate\Http\Resources\Json\Resource;
    class AppServiceProvider extends ServiceProvider{   
     /**
     * 在注册后进行服务的启动
     *
     * @return void
     */  
       public function boot()  
         {      
           Resource::withoutWrapping(); 
          }   
     /**
     * 在容器中注册绑定
     *
     * @return void
     */  
      public function register()  
       {    
         //  
       }
    }

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

Sebagai contoh, UserCollection memetakan contoh pengguna yang diberikan kepada sumber User. Untuk menyesuaikan tingkah laku ini, anda boleh mengatasi atribut $collects bagi koleksi sumber:

{  
  "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    
      }
 }

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,  
          ];
      }

'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,  
         ];
    }

/**
 * 将资源转换成数组
 *
 * @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;       
                 }),   
             ];
         }

/**
 * 将资源转换成数组
 *
 * @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;       
                 }),    
            ];
       }

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

<?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',           
              ],      
             ];   
         }
     }

分页

你可以将分页实例传递给资源的 collection 方法或者自定义的资源集合：

return (new UserCollection(User::all()->load('roles')))       
         ->additional(['meta' => [             
                'key' => 'value',               
                 ]
              ]);

分页响应中总有 meta 和 links 键包含着分页状态信息：

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

条件属性

有些时候，你可能希望在给定条件满足时添加属性到资源响应里。例如，你可能希望如果当前用户是 「管理员」 时添加某个值到资源响应中。在这种情况下 Laravel 提供了一些辅助方法来帮助你解决问题。 when 方法可以被用来有条件地向资源响应添加属性：

use App\User;
use App\Http\Resources\User as UserResource;
Route::get('/user', function () { 
   return (new UserResource(User::find(1)))         
          ->response()                
          ->header('X-Value', 'True');
        });

在上面这个例子中，只有当 isAdmin 方法返回 true 时， secret 键才会最终在资源响应中被返回。如果该方法返回 false ，则 secret 键将会在资源响应被发送给客户端之前被删除。 when 方法可以使你避免使用条件语句拼接数组，转而用更优雅的方式来编写你的资源。

when 方法也接受闭包作为其第二个参数，只有在给定条件为 true

<?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,      
                ]; 
            }   
     /**
     * 自定义响应
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Illuminate\Http\Response  $response
     * @return void
     */  
     public function withResponse($request, $response)
         {     
            $response->header('X-Value', 'True'); 
         }
     }

🎜{note} withoutWrappin Kaedah ini hanya akan melumpuhkan pembungkusan sumber peringkat tertinggi dan tidak akan memadamkan kunci data yang anda tambahkan secara manual pada koleksi sumber. 🎜