README

A clean, scalable Api CRUD architecture for Laravel, built around a reusable Base Service and Base Controller with automatic:

• ✅ Model Resolution
• ✅ Resource Resolution
• ✅ Collection Handling
• ✅ Pagination
• ✅ Advanced Filtering (=, !=, >, <, >=, <=, LIKE, IN, BETWEEN, NULL checks, Date operations)
• ✅ Eager Loading Relationships
• ✅ API Response Formatting
• ✅ Auto-Validation using Form Requests
• ✅ Auto Creation of Model, Resource, Requests, Controller, Service, Migration using Command

Designed to eliminate repetitive CRUD logic while keeping your application clean and maintainable. Pass filters and relationships directly from your frontend to dynamically build optimized queries with full control over data retrieval.

📦 Installation

Install via Composer:

composer require rizkussef/laravel-crud-api

If needed, manually register the provider in:

config/app.php

Rizkussef\LaravelCrudApi\ApiCrudServiceProvider::class,

⚙️ Publish Configuration

php artisan vendor:publish --provider="Rizkussef\LaravelCrudApi\ApiCrudServiceProvider" --tag=config

This will publish:

config/api-crud.php

Example:

return [
    'paginate' => 15,
];

🏗 Architecture

App
 ├── Models
 │     └── User.php
 ├── Services
 │     └── UserService.php
 ├── Http
 │     ├── Controllers
 │     │      └── UserController.php
 │     ├── Requests
 │     │      ├── UserRequest.php
 │     │      └── UserUpdateRequest.php
 │     └── Resources
 │            └── UserResource.php

⚡ Artisan Generator Command

The absolute fastest way to get started is by using the built-in Artisan generator. This powerful command scaffolds a fully functional CRUD API endpoint in seconds!

php artisan api-crud:make {Model}

🎯 Example: Creating an Article API

php artisan api-crud:make Article

What happens behind the scenes? The command automatically generates all layers required for an API CRUD operation:

⚙️ Available Options

Once generated, just register your new endpoint in routes/api.php and you're fully operational!

Route::apiResource('articles', ArticleController::class);

🛠 Manual Setup (Step-by-Step)

1️⃣ Create a Service

namespace App\Services;

use Rizkussef\LaravelCrudApi\Services\ApiCrudService;

class UserService extends ApiCrudService
{
    // Add custom business logic here if needed
}

🔎 Automatic Resolution (Models, Resources, and Form Requests)

The architecture heavily relies on naming conventions to automatically resolve dependencies:

UserService → App\Models\User
UserService → App\Http\Resources\UserResource
UserController → App\Http\Requests\UserRequest (Used for store)
UserController → App\Http\Requests\UserUpdateRequest (Used for update)

No need to manually inject or define the Model, Resource, or Form Requests. ApiCrudController automatically validates inbound requests using the resolved Form Request before passing data to the Service.

2️⃣ Create a Controller

namespace App\Http\Controllers;

use App\Services\UserService;
use Rizkussef\LaravelCrudApi\Http\Controllers\ApiCrudController;

class UserController extends ApiCrudController {
    public function __construct(UserService $service)
    {
        parent::__construct($service);
    }
}

Just Inject the specific service for this controller.

� Filters & Relationships

The package includes powerful filtering and eager-loading capabilities. Pass filters and relationships from the frontend to dynamically build queries. They can be passed either as array parameters or as JSON-encoded strings.

Available Filter Operators

Comparison Operators

// Equal / Greater Than / Less Than
['age' => ['operator' => '=', 'value' => 25]]
['age' => ['operator' => '>', 'value' => 18]]
['age' => ['operator' => '>=', 'value' => 18]]
['age' => ['operator' => '<', 'value' => 65]]
['age' => ['operator' => '<=', 'value' => 65]]
['status' => ['operator' => '!=', 'value' => 'deleted']]

String Matching

// LIKE search (wildcard)
['name' => ['operator' => 'like', 'value' => 'John']]

// Starts with
['email' => ['operator' => 'starts_with', 'value' => 'admin']]

// Ends with
['email' => ['operator' => 'ends_with', 'value' => '.com']]

// Simple value (auto LIKE for strings)
['name' => 'John']  // Searches LIKE "%John%"

Array Operations

// Multiple values
['status' => ['operator' => 'in', 'value' => ['active', 'pending']]]

// Exclude values
['status' => ['operator' => 'not_in', 'value' => ['deleted', 'banned']]]

// Range
['price' => ['operator' => 'between', 'value' => [100, 500]]]
['price' => ['operator' => 'not_between', 'value' => [100, 500]]]

NULL Checks

['deleted_at' => ['operator' => 'null']]      // IS NULL
['verified_at' => ['operator' => '!null']]    // IS NOT NULL
['verified_at' => ['operator' => 'not_null']]
['published_at' => ['operator' => 'exists', 'value' => true]]   // IS NOT NULL
['published_at' => ['operator' => 'exists', 'value' => false]]  // IS NULL

Date Operations

['created_at' => ['operator' => 'date', 'value' => '2024-02-23']]
['created_at' => ['operator' => 'year', 'value' => 2024]]
['created_at' => ['operator' => 'month', 'value' => 2]]
['created_at' => ['operator' => 'day', 'value' => 23]]

Frontend Examples

Axios Example

import axios from 'axios';

const fetchUsers = async () => {
  const { data } = await axios.get('/api/users/Paginate', {
    params: {
      filters: {
        status: 'active',
        age: { operator: '>', value: 18 }
      },
      relationships: ['profile', 'comments'],
      per_page: 15
    }
  });
  
  console.log(data);
};

Backend Services Examples

Another Service Calling This Service

namespace App\Services;

use App\Services\UserService;

class ReportService
{
    public function __construct(private UserService $userService) {}

    /**
     * Generate active users report
     */
    public function getActiveUsersReport()
    {
        $filters = [
            'status' => 'active',
            'created_at' => [
                'operator' => 'date',
                'value' => now()->subMonth()->format('Y-m-d')
            ]
        ];

        $relationships = ['profile', 'department'];

        return $this->userService->index($filters, $relationships);
    }

    /**
     * Get premium users with pagination
     */
    public function getPremiumUsers($page = 1)
    {
        $filters = [
            'subscription_type' => 'premium',
            'last_payment_date' => [
                'operator' => '!=null'
            ]
        ];

        $relationships = ['subscription', 'profile'];

        return $this->userService->getPaginated(
            perPage: 50,
            filters: $filters,
            relationships: $relationships
        );
    }

    /**
     * Search users by multiple criteria
     */
    public function searchUsers($name, $department, $minAge)
    {
        $filters = [
            'name' => $name,
            'department_id' => $department,
            'age' => [
                'operator' => '>=',
                'value' => $minAge
            ]
        ];

        return $this->userService->index($filters, ['profile', 'department']);
    }
}

�🔁 Built-in CRUD Methods

The BaseCrudController provides:

• index() – List records
• getPaginated($perPage) - Paginate list of records
• show($id) – Show single record
• store(Request $request) – Automatically resolves and validates the incoming Request using the associated Form Request, then creates record
• update(Request $request, $id) – Automatically resolves and validates using the associated Update Form Request, then updates record
• destroy($id) – Delete record

Controller handles validation & response formatting. All business logic is handled inside ApiCrudService.

📄 Automatic Resource Handling

Single Item

return new UserResource($user);

Collection

return UserResource::collection($users);

Automatically handled by the base service.

No Resource

// No UserResource exists
return $user; // returns full user model data

If the corresponding Resource class does not exist, the base controller will return the raw model data instead of a resource.

📊 Example JSON Response

GET /users

{
  "data": [
    {
      "id": 1,
      "name": "John Doe"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15
  }
}

🧠 Best Practices

✔ Use the Artisan Generator Command to create all layers automatically.
✔ Keep business logic inside Model-specific services.
✔ Keep controllers thin.
✔ Extend ApiCrudService instead of modifying it.
✔ Use Resources for API formatting.
✔ Use filters and relationships to avoid N+1 query problems.

Example 1: Simple Business Logic with Filters

namespace App\Services;

use Rizkussef\LaravelCrudApi\Services\ApiCrudService;

class UserService extends ApiCrudService
{
    /**
     * Activate user
     */
    public function activate($id)
    {
        $user = $this->model->findOrFail($id);
        $user->update(['active' => true]);
        return $this->applyResource($user);
    }

    /**
     * Get active users in a department
     */
    public function getActiveDepartmentUsers($departmentId, $perPage = 15)
    {
        $filters = [
            'active' => true,
            'department_id' => $departmentId
        ];
        
        $relationships = ['department', 'profile'];
        
        return $this->getPaginated($perPage, $filters, $relationships);
    }
}

Example 2: Complex Filtering with Date Range

namespace App\Services;

use Rizkussef\LaravelCrudApi\Services\ApiCrudService;

class OrderService extends ApiCrudService
{
    /**
     * Get high-value orders in date range with customer details
     */
    public function getHighValueOrders($minAmount, $startDate, $endDate, $perPage = 20)
    {
        $filters = [
            'total_amount' => [
                'operator' => '>=',
                'value' => $minAmount
            ],
            'created_at' => [
                'operator' => 'between',
                'value' => [$startDate, $endDate]
            ],
            'status' => [
                'operator' => 'in',
                'value' => ['completed', 'shipped']
            ]
        ];

        $relationships = ['customer', 'items.product', 'payment'];

        return $this->getPaginated($perPage, $filters, $relationships);
    }

    /**
     * Search orders by customer name and status
     */
    public function searchOrders($customerName, $statuses)
    {
        $filters = [
            'customer_name' => [
                'operator' => 'like',
                'value' => $customerName
            ],
            'status' => [
                'operator' => 'in',
                'value' => $statuses
            ]
        ];

        return $this->index($filters, ['customer', 'items']);
    }
}

Example 3: Filtering with NULL Checks

namespace App\Services;

use Rizkussef\LaravelCrudApi\Services\ApiCrudService;

class ArticleService extends ApiCrudService
{
    /**
     * Get published articles with authors and comments
     */
    public function getPublishedArticles($perPage = 15)
    {
        $filters = [
            'status' => 'published',
            'published_at' => [
                'operator' => '!null'  // IS NOT NULL
            ]
        ];

        $relationships = ['author', 'comments.author', 'tags'];

        return $this->getPaginated($perPage, $filters, $relationships);
    }

    /**
     * Get articles pending review (no reviewer assigned)
     */
    public function getPendingReview()
    {
        $filters = [
            'status' => 'draft',
            'reviewer_id' => [
                'operator' => 'null'  // IS NULL
            ]
        ];

        return $this->index($filters, ['author']);
    }
}

🔌 Dependency Injection

ApiCrudService is bound in the container via the Service Provider, so it can be injected anywhere.

🔧 Extending

You can extend:

• ApiCrudController
• ApiCrudService
• Pagination configuration

And you can use:

• API Response Trait
• Filter Query Trait
• Relationship Query Trait

🛣 Example Routes

Route::apiResource('users', UserController::class);

👨‍💻 Author & Support

Developed by Rizk Ussef

A fullstack developer passionate about creating clean, maintainable architecture patterns and reusable solutions for building scalable applications across frontend and backend ecosystems.

Get in Touch

• GitHub: @rizkussef
• Email: rizk.ussef@gmail.com
• Issues & Feedback: GitHub Issues

🤝 Contributing

Contributions are welcome! If you find bugs or have feature suggestions, please open an issue or submit a pull request.

📄 License

MIT License - see LICENSE file for details.