Метод additional

Метод additional класса JsonResource позволяет добавлять произвольные мета-данные к финальному JSON-ответу ресурса. Эти данные помещаются в корневой объект ответа наряду с основными данными ресурса. Метод принимает один параметр - массив с дополнительными данными, которые будут включены в ответ.

Синтаксис

<?php
	use Illuminate\Http\Resources\Json\JsonResource;
	
	class UserResource extends JsonResource
	{
		public function toArray($request)
		{
			return [
				'id' => $this->id,
				'name' => $this->name,
			];
		}
		
		public function with($request)
		{
			return [
				'meta' => [
					'version' => '1.0.0',
				],
			];
		}
	}
?>

Альтернативно, можно использовать метод additional в контроллере при создании ресурса:

<?php
	use App\Http\Resources\UserResource;
	use App\Models\User;
	
	$user = User::find(1);
	$res = (new UserResource($user))
		->additional(['meta' => ['version' => '1.0.0']]);
?>

Пример

Давайте создадим ресурс для модели User и добавим к нему дополнительную информацию о версии API и статусе ответа:

<?php
	namespace App\Http\Resources;
	
	use Illuminate\Http\Resources\Json\JsonResource;
	use Illuminate\Http\Request;
	
	class UserResource extends JsonResource
	{
		public function toArray(Request $request): array
		{
			return [
				'id' => $this->id,
				'name' => $this->name,
				'email' => $this->email,
			];
		}
		
		public function with(Request $request): array
		{
			return [
				'api_version' => 'v2.0.0',
				'status' => 'success',
			];
		}
	}
?>

Теперь используем этот ресурс в контроллере:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\User;
	use App\Http\Resources\UserResource;
	use Illuminate\Http\Request;
	
	class UserController extends Controller
	{
		public function show(Request $request, $id)
		{
			$user = User::find($id);
			$res = new UserResource($user);
			
			return $res;
		}
	}
?>

Результат выполнения кода при запросе к эндпоинту:

{
	"id": 1,
	"name": "John Doe",
	"email": "john@example.com",
	"api_version": "v2.0.0",
	"status": "success"
}

Пример

Используем метод additional динамически в контроллере для добавления разных мета-данных в зависимости от условий:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\Article;
	use App\Http\Resources\ArticleResource;
	use Illuminate\Http\Request;
	
	class ArticleController extends Controller
	{
		public function index(Request $request)
		{
			$articles = Article::all();
			
			$res = ArticleResource::collection($articles)
				->additional([
					'meta' => [
						'total' => $articles->count(),
						'request_time' => microtime(true),
						'authorized' => $request->user() ? true : false,
					],
				]);
			
			return $res;
		}
	}
?>

Результат выполнения кода:

{
	"data": [
		{
			"id": 1,
			"title": "First Article",
			"content": "Content of first article"
		},
		{
			"id": 2,
			"title": "Second Article",
			"content": "Content of second article"
		}
	],
	"meta": {
		"total": 2,
		"request_time": 1644324321.1234,
		"authorized": true
	}
}

Пример

Совмещаем метод additional с методом wrap для управления обёрткой ответа:

<?php
	namespace App\Http\Resources;
	
	use Illuminate\Http\Resources\Json\JsonResource;
	use Illuminate\Http\Request;
	
	class PostResource extends JsonResource
	{
		public function toArray(Request $request): array
		{
			return [
				'id' => $this->id,
				'title' => $this->title,
				'excerpt' => substr($this->content, 0, 50),
			];
		}
		
		public function with(Request $request): array
		{
			return [
				'server_time' => now()->toDateTimeString(),
				'api_version' => 'v3.0.0',
			];
		}
	}
?>

В контроллере добавляем обёртку и дополнительные данные:

<?php
	namespace App\Http\Controllers;
	
	use App\Models\Post;
	use App\Http\Resources\PostResource;
	use Illuminate\Http\Request;
	
	class PostController extends Controller
	{
		public function show(Request $request, $id)
		{
			$post = Post::find($id);
			
			$res = (new PostResource($post))
				->additional([
					'pagination' => [
						'prev' => $id > 1 ? $id - 1 : null,
						'next' => $id < 10 ? $id + 1 : null,
					],
				])
				->wrap('post');
			
			return $res;
		}
	}
?>

Результат выполнения кода:

{
	"post": {
		"id": 5,
		"title": "Fifth Post",
		"excerpt": "This is the excerpt of the fifth post..."
	},
	"server_time": "2024-01-15 14:30:25",
	"api_version": "v3.0.0",
	"pagination": {
		"prev": 4,
		"next": 6
	}
}

Смотрите также

метод toArray,
который определяет структуру данных ресурса
метод with,
который добавляет мета-данные из самого ресурса
метод wrap,
который управляет обёрткой данных ресурса
класс JsonResponse,
который формирует JSON-ответ в Laravel