README

A Laravel practice development package, ready to use out of the box. It simplifies handling responses, filters, services, and exception management.

Features

• Standardized JSON Response: Unified API response format with request ID tracking
• Query Filters: Elegant and reusable query filtering system
• Service Layer: Base service class with exception handling capabilities
• Exception Management: Comprehensive exception handling with localized messages
• Model Standardization: Enhanced Eloquent models with standardized JSON serialization
• Request Context: Automatic request ID generation and context management
• Artisan Commands: Generate filters and services with custom commands

Requirements

• PHP ^8.1
• Laravel ^12.0
• ext-json

Installation

Install the package via Composer:

composer require caleb/laravel-practice

The package will automatically register its service provider.

Configuration

Publish Language Files

php artisan vendor:publish --tag=practice-lang

Publish Stubs

php artisan vendor:publish --tag=practice-stubs

Usage

1. Response Trait

Use the Response trait in your controllers to standardize API responses:

<?php

namespace App\Http\Controllers;

use Caleb\Practice\Response;
use Illuminate\Http\Controller;

class UserController extends Controller
{
    use Response;
    
    public function index()
    {
        $users = User::all();
        return $this->success($users);
    }
    
    public function store(Request $request)
    {
        try {
            $user = User::create($request->validated());
            return $this->success($user);
        } catch (Exception $e) {
            return $this->error('Failed to create user', 422);
        }
    }
}

Response format:

{
    "code": 200,
    "msg": "success",
    "data": {...},
    "request_id": "uuid-string"
}

2. Query Filters

Create a filter class:

php artisan practice:make:filter UserFilter

Define your filter:

<?php

namespace App\Filters;

use Caleb\Practice\QueryFilter;

class UserFilter extends QueryFilter
{
    public function name($name)
    {
        $this->query->where('name', 'like', "%{$name}%");
    }
    
    public function email($email)
    {
        $this->query->where('email', $email);
    }
}

Use in your model:

<?php

namespace App\Models;

use Caleb\Practice\Standardization;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use Standardization;
}

Apply filters in controller:

public function index(UserFilter $filter)
{
    $users = User::filter($filter)->paginate();
    return $this->success($users);
}

3. Service Layer

Create a service class:

php artisan practice:make:service UserService

Define your service:

<?php

namespace App\Services;

use Caleb\Practice\Service;
use App\Models\User;

class UserService extends Service
{
    public function createUser(array $data)
    {
        if (User::where('email', $data['email'])->exists()) {
            $this->throwAppException('Email already exists', 422);
        }
        
        return User::create($data);
    }
    
    public function getUserById(int $id)
    {
        $user = User::find($id);
        
        if (!$user) {
            $this->throwAppException('User not found', 404);
        }
        
        return $user;
    }
}

Use in controller:

public function store(Request $request)
{
    $user = UserService::instance()->createUser($request->validated());
    return $this->success($user);
}

4. Model Standardization

Use the Standardization trait in your models:

<?php

namespace App\Models;

use Caleb\Practice\Standardization;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use Standardization;
    
    protected $casts = [
        'settings' => 'array',
        'created_at' => 'datetime',
    ];
}

Benefits:

• JSON serialization with JSON_UNESCAPED_UNICODE flag
• Dynamic per_page from request parameters
• Built-in filter scope for query filtering

5. Exception Handling

The package provides automatic exception handling with localized messages:

• ValidationException: Returns 422 with validation errors
• AuthenticationException: Returns 401 with error message
• PracticeException: Returns custom error code and message
• ModelNotFoundException: Returns 404 with "Resource not found" message
• ThrottleRequestsException: Returns 429 with rate limit message

Custom exceptions:

// Application exceptions (logged as DEBUG level)
$this->throwAppException('Custom error message', 422, $additionalData);

// External service exceptions (logged normally)
$this->throwExternalAppException('External service error', 503);

6. Request Context

The package automatically adds a unique request ID to each request context and includes it in all responses. This helps with request tracking and debugging.

Middleware

The package automatically registers the AddContext middleware which:

• Generates a unique UUID for each request
• Stores it in Laravel's Context
• Includes it in all JSON responses

Localization

The package supports multiple languages. Currently included:

English (en):

• System success/error messages
• Resource not found messages

Chinese (zh-CN):

• 系统成功/错误消息
• 资源未找到消息

You can publish and customize these messages:

php artisan vendor:publish --tag=practice-lang

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Author

• Caleb - caleb.meteor@gmail.com

Keywords

• Laravel
• Response
• Request ID
• Service
• Filter
• Exception Handler
• Model Standardization