README

🌍 Languages

🇺🇸 English (default)
🇷🇺 Русская версия

Introduction
Requirements
Installation
Configuration
Core Components
Usage Examples
Recommendations
Useful Links

Introduction

makaveli/laravel-crudler is a modular framework for creating CRUD operations in Laravel applications. It provides a unified approach to configuring all application layers: from validation and authorization to response formatting and routing. Each layer is configured declaratively through builders, making the code clean, testable, and easily reusable.

The package integrates tightly with makaveli/laravel-core (DTO, BaseRepository, BaseService) and makaveli/laravel-query-builder (filtering), uses laravel-logger for logging, and supports soft deletes through traits.

Key features:

Separation of concerns – each layer is responsible for its own task: validation, authorization, reading, writing, business logic, HTTP.
Declarative configuration – through builders and DTOs (e.g., RequestBuilder, ServiceBuilder).
Flexible hooks – in Action you can add logic before/after validation and before/after the service call.
Context support – validation can differ for create/update/delete.
Full integration with the makaveli ecosystem – DTOs, repositories, services, resources, logging.

Requirements

PHP 8.2 or higher
Laravel 10.10, 11.0 or 12.0
makaveli/laravel-core (installed automatically)
makaveli/laravel-query-builder (installed automatically)
makaveli/laravel-logger (installed automatically)

Installation

Install the package via Composer:

composer require makaveli/laravel-crudler

(Optional) Publish the configuration file if you want to change the default settings:
```
php artisan vendor:publish --tag=crudler-config
```
This will create a config/crudler.php file.
The CrudlerServiceProvider is registered automatically.

Configuration

The config/crudler.php file contains default settings for all layers. You can override error messages, success operation texts, and other parameters.

<?php

return [
    'repositories' => [
        'show_once_by_id_not_found_message' => 'Record not found!',
        'is_not_unique_message' => 'A record with this data already exists!',
    ],

    'services' => [
        'restore' => [
            'not_delete_message' => 'Record not found in the trash!',
            'success_message' => 'Record restored from the trash!',
            'error_message' => 'An error occurred while restoring!',
        ],
        'delete' => [
            'already_delete_message' => 'Record not found!',
            'success_message' => 'Record deleted successfully!',
            'error_message' => 'An error occurred while deleting the record!',
        ],
    ],

    'actions' => [
        'error_create_message' => 'An error occurred while adding!',
        'error_update_message' => 'An error occurred while updating!',
        'error_delete_message' => 'An error occurred while deleting!',
        'error_restore_message' => 'An error occurred while restoring!',
    ],

    'controllers' => [
        'success_create_message' => 'Record saved successfully!',
        'success_update_message' => 'Record updated successfully!',
        'success_delete_message' => 'Record deleted successfully!',
        'success_restore_message' => 'Record restored successfully!',
    ],
];

You can change these values according to your application's requirements.

Core Components

The package is divided into independent layers, each configured through its own builder and DTO. Below is a brief overview; full documentation for each layer is available in separate files.

Layer	Description	Documentation
Request	Validation of incoming data with support for tags (create/update/delete) and contexts.	request.md
Policy	Access control checks (can_view, can_update, can_delete, can_restore) via callables or aliases.	policy.md
Resource	API response formatting: main fields, lazy additional fields, custom methods.	resource.md
Repository	Data reading: pagination, filtering, fetching by ID, uniqueness checks, caching.	repository.md
Service	Data mutations: creation, update, deletion, restoration with field mapping from DTO.	service.md
Action	Orchestration of business operations: policy call, reading, service call, hooks before/after validation and before/after service call.	action.md
Controller	HTTP handling: standard methods crudlerList, crudlerShow, crudlerCreate, etc., DTO injection.	controller.md
Router	Route registration with automatic injection of CrudlerControllerDTO.	api.md

Each layer is configured in a class that implements ICrudlerConfig (or simply a separate configurator class). All builders (RequestBuilder, PolicyBuilder, ResourceBuilder, etc.) return DTOs that are then passed to the corresponding classes (CrudlerRequest, CrudlerPolicyResolver, CrudlerResource, etc.).

Usage Examples

1. Creating Module Configuration Classes

For more details about each layer, you can read this section.

2. Registering Routes

// routes/api.php
use App\Modules\MyModule\Crudler\MyModuleCrudler;
use App\Http\Controllers\MyModuleController;
use Crudler\Routing\CrudlerRoute;

CrudlerRoute::post('/items', [MyModuleController::class, 'crudlerCreate', fn() => MyModuleCrudler::FULL_CONTROLLER_CRUDLER()]);
CrudlerRoute::get('/items/{id}', [MyModuleController::class, 'crudlerShow', fn() => MyModuleCrudler::FULL_CONTROLLER_CRUDLER()]);

3. Controller

namespace App\Http\Controllers;

use Crudler\Controllers\CrudlerController;
use App\Modules\MyModule\Application\Actions\MyModuleActions;
use Core\Interfaces\IHttpContext;

class MyModuleController extends CrudlerController
{
    public function __construct(IHttpContext $http)
    {
        parent::__construct(MyModuleActions::class, $http);
    }
}

4. Action and Service

In MyModuleActions you define business logic, using CrudlerAction as the base class. The Service is created via ServiceBuilder, and field mapping via CrudlerMapper.

// Example simplified Action
use Crudler\Actions\CrudlerAction;

class MyModuleActions extends CrudlerAction
{
    public function __construct()
    {
        parent::__construct(
            service: MyModuleService::class,
            repository: MyModuleRepository::class,
            crudlerPolicyDTO: MyModuleCrudlerPolicy::handle(),
        );
    }
}

Full examples for each layer are provided in their respective documents.

Recommendations

Always create a configuration class for your module, implementing ICrudlerConfig (or just static methods). This centralises settings and simplifies reuse.
Use the builders for each layer – they provide a clear method chain and IDE autocompletion.
For fields that need to be computed (e.g., created_by), use closures in CrudlerMapper.
Don’t forget about hooks in the Action – they allow adding custom logic before/after validation and before/after the service call.
When working with soft deletes, ensure your model uses the SoftModelBase trait from laravel-core.
For lists, use ControllerListBuilder with the isGetAll() and isNotPaginateResponse() flags as needed.
Log successful and failed operations – pass slugs to successLog() and errorLog() methods in ActionItemBuilder.

Useful Links

Package repository: https://github.com/Ma1kaveli/laravel-crudler
Layer documentation:
- Request
- Policy
- Resource
- Repository
- Service
- Action
- Controller
- Router
Base dependencies:

makaveli / laravel-crudler

Maintainers

Package info

Statistics

Security