Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

shehabwaleed's avatar

Asking about the best way to structure a response pagination metadata

Hello everyone, I was discussing with a friend the best practice for formatting and structuring response pagination metadata. We are structuring the response using a helper class called ResponseHelper, which formats the JSON response into status code, message, and data. We were debating where to place the pagination metadata format.

The first approach is to handle it inside the ResponseHelper class, ensuring consistency throughout the entire application. However, he mentioned that this approach is not documented in Laravel, unlike collections. Additionally, we use JSON resources in controllers to manage data formatting.

The second approach is to handle the logic inside an abstract class called BaseCollection, creating a unique collection class and a JSON resource class for each model. For example, UserCollection for the user model, and so on. This would result in hundreds of empty collection classes.

0 likes
9 replies
amitsolanki24_'s avatar

You can also create response macros in boot method of your AppServiceProvider

 Response::macro('success', function (string $message, array $data = [], int $status =200) {
        return response()->json([
			'message' => $message,
          	'status'  => true,
          	'data' => $data,
        ], $status);
    });

    Response::macro('error', function (string $message, array $errors = [], int $status = 400) {
        return response()->json([
          	'errors'  => $errors,
			'status' => false,
          	'message' => $message,
        ], $status);
    });
2 likes
shehabwaleed's avatar

@vincent15000 Thank you for your answer, but I would like to ask about the best place to structure the pagination metadata for the response, should I put it inside my helper class, or inside a base collection, and create a collection class foreach model ?

1 like
martinbean's avatar

@shehabwaleed The “best practice” is to not re-invent the wheel when Laravel consistently formats responses for you if you use Eloquent API resources. There’s absolutely no reason to create custom “response helpers”.

Retrieve your models. Use a resource to return a consistently-formatted response:

class ArticleController extends Controller
{
    public function index()
    {
        $articles = Article::query()->paginate();

        // Return paginated collection of articles...
        return ArticleResource::collection($articles);
    }

    public function show(Article $article)
    {
        // Return single article...
        return ArticleResource::make($article);
    }
}
2 likes
shehabwaleed's avatar

@martinbean I understand your point. However, in my case, I want to return a unified response to the frontend, where all responses include message, status, and data. How can I handle this? The issue is that when I return a JSON response using API resources, the pagination data disappears.

martinbean's avatar

I understand your point. However, in my case, I want to return a unified response to the frontend

@shehabwaleed That’s literally the entire point of API resources.

all responses include message, status, and data

Why do you need “status” in the response body? You use HTTP status codes to indicate the, well, status of the request. You can also add metadata—such as a message if you really need to—to compliment the response data (https://laravel.com/docs/eloquent-resources#adding-meta-data) but again, this feels redundant. If I issue a request to say, create an article, and I get a 201 Created response with the article data in the body, then I don’t also need a “message” parameter saying “Article created” or whatever because I know the article was created based on the status code and response body.

1 like

Please or to participate in this conversation.