Usage

Usage Examples

Once installed, you can immediately start using the dynamic API endpoints:

# List users with pagination
GET /api/users

# Get specific user with relationships
GET /api/users/1?select=*,posts(*),roles(*)

# Create new user
POST /api/users
{
    "name": "John Doe",
    "email": "john@example.com"
}

# Update user
PUT /api/users/1
{
    "name": "Jane Doe"
}

# Delete user (soft delete)
DELETE /api/users/1

# Search users
GET /api/users?s=john&status=eq.active

# Advanced filtering
GET /api/users?age=gt.18&created_at=between.2024-01-01,2024-12-31

API Endpoints

The package automatically registers RESTful API routes for dynamic database operations. The route prefix is configurable via config('record.api_prefix') (default: api/v1).

Route Configuration

// config/record.php
'api_prefix' => 'api/v1',

Examples:

• 'api' → /api/{table}
• 'api/v1' → /api/v1/{table}
• 'api/v2' → /api/v2/{table}
• 'records' → /records/{table}

Standard CRUD Operations

• GET /{prefix}/{table} - List records with filtering and pagination
• GET /{prefix}/{table}/{id} - Get specific record
• POST /{prefix}/{table} - Create new record
• PUT/PATCH /{prefix}/{table}/{id} - Update record
• POST /{prefix}/{table}/upsert - Upsert (create or update) record
• DELETE /{prefix}/{table}/{id} - Soft delete record

Advanced Operations

• POST /{prefix}/{table}/{id}/restore - Restore soft-deleted record
• DELETE /{prefix}/{table}/{id}/force - Permanently delete record
• POST /{prefix}/{table}/bulk - Bulk operations
• POST /{prefix}/{table}/bulk/create - Bulk create
• POST /{prefix}/{table}/bulk/update - Bulk update
• POST /{prefix}/{table}/bulk/delete - Bulk delete
• POST /{prefix}/{table}/bulk/upsert - Bulk upsert

RPC Functions

• GET|POST|PUT|PATCH|DELETE /{prefix}/rpc/{functionName} - Execute global functions
• GET|POST|PUT|PATCH|DELETE /{prefix}/{table}/rpc/{functionName} - Execute table-specific functions

Usage

• Middleware:
  • Add request.id to routes or groups: Route::middleware(['request.id'])->group(function () { ... });.
• Responses:
  • Resolve via container: $service = app('api.response');
  • return $service->success(['items' => []]);
  • All responses include meta.request_id when middleware is active.

Example Controller

use Illuminate\Http\Request;

class ExampleController
{
    public function index(Request $request)
    {
        $responses = app('api.response');
        return $responses->success(['message' => 'OK']);
    }
}

QueryHelpers Trait

The QueryHelpers trait provides powerful query filtering and manipulation capabilities for Eloquent models.

Usage

use Mylekha\RecordApi\Traits\QueryHelpers;

class YourModel extends Model
{
    use QueryHelpers;
}

Available Methods

• applyRequestFilters($request, $isArray = false, $orderBy = 'id') - Apply request-based filters

Supported Query Parameters

• s - Search all fields (e.g., ?s=cambodia)
• select - Specify columns including relationships (e.g., ?select=id,name,customer:id,name)
• with - Load related models (e.g., ?with=user,posts.comments)
• sortby - Column to sort by (e.g., ?sortby=name)
• order - Sort direction: asc/desc (e.g., ?order=asc)
• per_page - Enable pagination (e.g., ?per_page=20)
• limit - Limit results when isArray=true (e.g., ?limit=1000)
• lazy - Enable lazy loading (e.g., ?lazy=true)

Filter Operators

Supported syntax includes:

• Standard filters: eq, neq, gt, gte, lt, lte, in, not_in, between, not_between, like, ilike, contains, starts_with, ends_with, regex, match, imatch, date operators, and null/empty operators.
• Grouped logic: and=(...), or=(...).
• Advanced expression style: not.<operator> and operator(any|all).{...}.
• List styles: both id=in.(5,6,9) and legacy id=in.5,6,9.
• Driver guard: unsupported operators return 422 validation error with explicit message.

For complete operator matrix, grouped logic examples, and driver compatibility details, see:

• docs/api-documentation.md → Filter Operators and Grouped Logic.

Example Usage

// In your controller
public function index(Request $request)
{
    $results = YourModel::query()
        ->applyRequestFilters($request, true);
    
    return response()->json($results);
}

You can also use named arguments when calling the scope (PHP 8+):

$results = YourModel::query()->applyRequestFilters(
    request: $request,
    isArray: true,
    orderBy: 'created_at',
);