Designing a Scalable Repository Structure in Laravel with queryFi

Introduction

When I was starting a new Laravel project, I often wondered what structure I should use.
Laravel is very well-structured, don't get me wrong, making it hard to mess things up.
However, there is a catch, how do we avoid putting all the logic we need into a controller, such as UserController.php?
In this article, we'll focus on this issue. I'll share my preferred structure to cover my use cases, along with some best practices, and explain how to integrate queryFi.

---

Getting started

Since you’re here, I’ll assume you already have a Laravel project or know how to create one, so we can skip that step. Just make sure the API is set up.

We’ll be using the following structure:

app
├── Repositories
|   ├── Interfaces
|   |   ├── EloquentRepositoryInterface.php
|   └── Eloquent
|       ├── BaseRepository.php
|       └── UserRepository.php
├── Resources
    ├── BaseResource.php
    └── ExtendedJsonResource.php

You can find the Resources folder here, plus a custom logger.

---

1. Install queryFi

# Backend
composer require z3rka/queryfi

# Frontend
npm i queryfi

---

2. Add repository Interfaces

<?php

namespace App\Repositories\Interfaces;

use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;

interface EloquentRepositoryInterface
{
    public function create(array $attributes = [], ?string $successMessage, ?string $errorMessage): JsonResource;

    public function all(Request $request, ?string $errorMessage): JsonResource;

    public function one(Request $request, Model $model, ?string $errorMessage): JsonResource;

    public function update(Request $request, Model $model, ?string $successMessage, ?string $errorMessage): JsonResource;

    public function destroy(Request $request, ?string $successMessage, ?string $errorMessage): JsonResource;
}

---

3. Add the base repository class

I’ll add only three methods here to keep things clean and avoid cluttering the space with repetitive code.
You can find the rest here.

<?php

namespace App\Repositories\Eloquent;

use Z3rka\Queryfi\HasRelations;

class BaseRepository implements EloquentRepositoryInterface {
    use HasRelations;

    public function __construct(protected Model $model)
    {
        //
    }

    public function create(array $attributes = [], ?string $successMessage, ?string $errorMessage): BaseResource
    {
        try {
            return new BaseResource(
                true,
                $successMessage,
                $this->model->create($attributes)
            );
        } catch (Exception $e) {
            return new BaseResource(
                false,
                $errorMessage,
                [
                    'error' => $e
                ]
            );
        }
    }

    public function all(Request $request, ?string $errorMessage): BaseResource
    {
        try {
            return new BaseResource(
              true,
              'Success',
              $this->processModel($request, $this->model)
            );
        } catch (Exception $e) {
            $this->spitError($e);
            return new BaseResource(
                false,
                "Fail",
                $this->model->get(),
                [
                    "error" => $e,
                ]
            );
        }
    }

    public function one(Request $request, Model $model, ?string $errorMessage): BaseResource
    {
        try {
            return new BaseResource(
              true,
              "success",
              $this->processModel($request, $model)
            )
        } catch (Exception $e) {
            $this->spitError($e);
            return new BaseResource(
                false,
                "Fail",
                $model,
                [
                    "error" => $e,
                ]
            );
        }
    }
}

Normally, to return something from a model you have to ->get() or to find and ->first(), that’s not the case here as we are using the queryFi package and we can do this:

$this->processModel($request, $this->model)

This automatically covers ->get() by default if no getter(check the getters here) is configured in the query.

---

4. User repository

<?php

namespace App\Repositories\Eloquent;
use App\Models\User;
use Z3rka\Queryfi\HasRelations;

class UserRepository extends BaseRepository
{
    use HasRelations;

    public function __construct(User $model)
    {
        parent::__construct($model);
    }
}

---

5. User controller

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Repositories\Eloquent\UserRepository;

class UserController extends Controller
{
    public function __construct(public UserRepository $userRepository)
    {
    }

    public function index(Request $request)
    {
      return $this->userRepository
                  ->all($request, "Ooops, there was an error fetching all the users.")
    }

    public function show(Request $request, User $user)
    {
      return $this->userRepository->one(
            $request,
            $user,
            "Ooops, there was an error fetching the user."
        );
    }
}

---

6. The api route

Route::resource('users', UserController::class)->only(['index', 'show'])

---

Once we have everything set up, we can make requests from the browser by passing query parameters directly, like:

url?where[name]=john&select=name&getter=first

Alternatively, we can use the queryFi TypeScript package on the frontend for a cleaner approach.

import { createQuery } from "queryfi";

const query = createQuery('/api/users', {
    baseUrl: "http://localhost:8000"
  })
  .where({
    id: 1
  })
  .first() // will return an object with the user if it exists.

The generated query will look like

http://localhost:8000/api/users?where[id]=1&getter=first

This piece of code will return the user with id = 1.
When you use .find(), the response will automatically be an object.
If you use .get(), it will return an array.

You can try it out in the playground to see how the response looks.

Since we’re using the HasRelations trait, we can chain frontend queries to transform the data directly on the backend before it’s returned, as shown here.

import { createQuery } from "queryfi";

const query = createQuery('/api/users', {
    baseUrl: "http://localhost:8000"
  })
  .where({
    id: 1
  })
  .select(['email', 'id', 'name'])
  .get() // will return an array with one entry if it exists.

For more methods you can use, check out the the queryFi documentation

---

END

And that’s it! ? Now you’ve got a solid and powerful starting point to build your APIs like a pro.
Go ahead, flex those coding muscles, and make something awesome! ??

Get in touch github, Linkedin, queryFi

The above is the detailed content of Designing a Scalable Repository Structure in Laravel with queryFi. For more information, please follow other related articles on the PHP Chinese website!