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! 🚀💻
Top comments (0)