Skip to content

caleb-meteor/laravel-practice

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Laravel Practice

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

Keywords

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

About

laravel practice 开箱即用的开发包,处理响应,filter,service,异常处理

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages