دليل Laravel 13 المتقدم لبناء API

ينقل هذا الدليل Laravel API من أول استجابة JSON إلى خدمة متعددة الإصدارات تدعم المصادقة والفلترة والتفويض والاختبار والتوثيق. ينصب التركيز على القرارات والتنفيذ الكامل اللازمين لبناء عقد API مستقر، وليس على خصائص متفرقة في إطار العمل.

نطاق الدليل: هذا دليل تعليمي تطبيقي لأنماط Laravel API المتقدمة. يشرح كيف تعمل أجزاء إطار العمل معًا، ولا يفرض بنية واحدة تصلح لكل التطبيقات.

نُظم الدليل كمرجع تقني متدرج. يعالج كل قسم جانباً من جوانب تصميم API، ويعرض المحتوى الكامل لكل ملف تطبيق أُنشئ أو تغير في تلك المرحلة. يستخدم التنفيذ Laravel 13 وPHP 8.3 حتى تبقى جميع الأمثلة متوافقة مع بعضها.

ملاحظة Laravel 13: يتطلب Laravel 13 إصدار PHP 8.3 أو أحدث. يسجل هيكل التطبيق الحديث مسارات API ومعالجة الاستثناءات في bootstrap/app.php؛ لذلك استُبدلت أنماط RouteServiceProvider وAuthServiceProvider وapp/Exceptions/Handler.php القديمة في هذا الدليل.

الإصدارات المختبرة: Laravel 13.26.1 وPHP 8.3+ وSanctum 4.3.3 وScribe 5.11.0. وهي الإصدارات المثبّتة في ملف القفل للمشروع المرجعي.

المتطلبات والإعداد الأولي

• PHP 8.3 أو أحدث، وComposer، وMySQL، وGit
• معرفة أساسية بمسارات Laravel والمتحكمات وEloquent والترحيلات والتحقق
• Postman أو أي عميل HTTP آخر

composer create-project laravel/laravel:^13.0 orders-hub
cd orders-hub
php artisan install:api
php artisan migrate

اضبط قاعدة بيانات MySQL باسم orders_hub في .env، ثم طبّق الملفات المعروضة قسماً بعد قسم.

يأتي Laravel 13 بمتحكم أساسي مصغر. ولأن الأقسام اللاحقة تستخدم دوال التفويض داخل المتحكمات، فعّل Traits المطلوبة من البداية:

app/Http/Controllers/Controller.php

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Validation\ValidatesRequests;

abstract class Controller
{
    use AuthorizesRequests, ValidatesRequests;
}

خارطة الدليل

1. استجابات JSON موحدة وحالات HTTP صحيحة
2. اختبار API باستخدام Postman
3. تصميم عناوين قائمة على الموارد
4. هيكلة API متعدد الإصدارات
5. المصادقة بالرموز باستخدام Laravel Sanctum
6. إلغاء الرموز وتسجيل الخروج الآمن
7. تصميم استجابات مستقرة
8. الحقول والعلاقات الشرطية
9. تحميل العلاقات عند الطلب
10. فلاتر استعلام قابلة لإعادة الاستخدام
11. الموارد المتداخلة وفلترة العلاقات
12. ترتيب آمن يتحكم به العميل
13. إنشاء الموارد باستخدام POST
14. حذف الموارد باستخدام DELETE
15. الاستبدال الكامل باستخدام PUT
16. التحديث الجزئي باستخدام PATCH
17. تفويض الموارد باستخدام Policies
18. التحكم في الوصول بصلاحيات Token
19. صلاحيات دقيقة على مستوى الحقول
20. إدارة طلبيات العملاء
21. إدارة المستخدمين بأمان
22. تطبيق مبدأ الحد الأدنى من الصلاحيات
23. معالجة موحدة لأخطاء API
24. إنشاء توثيق API باستخدام Scribe
25. استخدام تنسيق واحد لجميع الاستجابات
26. اختبار تنسيق الاستجابة
27. قائمة ما بعد الدليل

كيف تقرأ هذا الدليل

كل قسم يذكر ما ستحصل عليه، ثم يولّد الأصناف، ثم يعرض الكود، وينتهي بطلب يمكنك تنفيذه.

الملفات الجديدة تُعرض كاملة، والملفات التي رأيتها من قبل تظهر على هيئة diff: + سطر مضاف و- سطر محذوف.

التحقق من كل نقطة

php artisan migrate:fresh --seed
php artisan route:list --path=api
php artisan serve

أرسل دائماً Accept: application/json. للمسارات المحمية، سجّل الدخول أولاً ثم أرسل رمز Sanctum بالشكل Authorization: Bearer YOUR_TOKEN.

1. استجابات JSON موحدة وحالات HTTP صحيحة

في الأساس الأول لبناء API سنبدأ بتطبيق Laravel جديد، ثم نضيف مسار API بسيطاً يعيد استجابة JSON منظمة مع حالة HTTP الصحيحة 200 OK.

يستهدف التنفيذ Laravel 13 وPHP بإصدار ^8.3 وSanctum بإصدار ^4.3.

ما الذي سنبنيه؟

عند إرسال طلب GET /api/login سنحصل على:

{
  "message": "Hello, Login!",
  "status": 200
}

محتوى الاستجابة بصيغة JSON، وحالة استجابة HTTP الفعلية هي أيضاً 200.

1. إنشاء المشروع

إذا أردت تنفيذ الدليل من مشروع نظيف، أنشئ تطبيق Laravel 13:

composer create-project laravel/laravel:^13.0 orders-hub
cd orders-hub
php artisan install:api

يستخدم المشروع المرجعي قاعدة بيانات MySQL باسم orders_hub. حدّث ملف .env ببيانات جهازك:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=orders_hub
DB_USERNAME=root
DB_PASSWORD=

لا يتعامل هذا التنفيذ الأولي مع قاعدة البيانات بعد، ولذلك سيعمل المسار قبل الحاجة إلى تشغيل migrations.

2. إنشاء Trait للاستجابات

أنشئ الـTrait عبر Artisan:

php artisan make:trait Traits/ApiResponses

أبقِ البادئة Traits/. فبدونها يضع make:trait الملف داخل app/ مباشرة، لأن المجلدين app/Concerns وapp/Traits غير موجودين في مشروع جديد.

هذا هو محتوى الملف كاملاً.

app/Traits/ApiResponses.php

<?php

namespace App\Traits;

use Illuminate\Http\JsonResponse;

trait ApiResponses
{
    /**
     * Return a successful response.
     */
    protected function ok(string $message): JsonResponse
    {
        return $this->success($message, 200);
    }

    /**
     * Return a success response whose payload status matches the HTTP status.
     */
    protected function success(string $message, int $statusCode = 200): JsonResponse
    {
        return response()->json([
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }
}

الدالة ok() اختصار لاستجابة ناجحة بحالة 200، وهي تستدعي success() التي تنشئ محتوى JSON وترسل رمز الحالة نفسه إلى Laravel.

المعامل الثاني في response()->json() مهم؛ فمن دونه قد يحتوي جسم الاستجابة على الرقم 200 بينما تكون حالة HTTP مختلفة. جمع القيمتين في الدالة نفسها يحافظ على اتساق الاستجابة.

3. إنشاء متحكم المصادقة

أنشئ المتحكم:

php artisan make:controller AuthController

استبدل محتواه بكود التنفيذ الكامل.

app/Http/Controllers/AuthController.php

<?php

namespace App\Http\Controllers;

use App\Traits\ApiResponses;
use Illuminate\Http\JsonResponse;

class AuthController extends Controller
{
    use ApiResponses;

    /**
     * Authenticate the user.
     */
    public function login(): JsonResponse
    {
        return $this->ok('Hello, Login!');
    }
}

يستورد المتحكم ApiResponses ويستخدمه، فتكون دوال الـTrait المحمية متاحة داخل المتحكم. وتُصرّح الدالة login() بنوع الإرجاع JsonResponse، وهو ما يوثّق عقد الدالة دون الحاجة إلى أي تعليق إضافي.

4. تسجيل مسار API

هذا هو ملف مسارات API الكامل في هذه المرحلة.

routes/api.php

<?php

use App\Http\Controllers\AuthController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are registered by bootstrap/app.php and all of them will
| be assigned to the "api" middleware group. Make something great!
|
*/

Route::get('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

يضيف Laravel البادئة /api تلقائياً للمسارات الموجودة هنا. لذلك يصبح Route::get('/login', ...) متاحاً على العنوان /api/login.

يبقى مسار Laravel الافتراضي والمحمي /api/user في الملف، لكننا لن نستخدمه في هذه المرحلة.

5. تشغيل الـAPI واختباره

شغّل خادم Laravel المحلي:

php artisan serve

اختبر المسار من نافذة terminal أخرى:

curl -i http://127.0.0.1:8000/api/login

الأجزاء المهمة في النتيجة هي:

HTTP/1.1 200 OK
Content-Type: application/json

{"message":"Hello, Login!","status":200}

ويمكنك التأكد من تسجيل المسار باستخدام:

php artisan route:list --path=api/login

هيكل ملفات التنفيذ الكامل

هذه فقط هي ملفات التطبيق الخاصة التي أُضيفت أو تغيرت في هذه المرحلة، أما بقية الملفات فهي هيكل Laravel 13 الافتراضي.

app/
├── Http/
│   └── Controllers/
│       └── AuthController.php
└── Traits/
    └── ApiResponses.php
routes/
└── api.php

لماذا نستخدم Trait للاستجابات؟

مع نمو الـAPI ستحتاج متحكمات كثيرة إلى إعادة استجابات بالشكل نفسه. وضع هذا الشكل في مكان مركزي يمنع الاختلافات الصغيرة، ويوفر مكاناً واحداً لإضافة دوال مساعدة لاحقاً مثل created() وerror() وnoContent().

هكذا تؤسس هذه المرحلة القاعدة التي سنبني عليها: مسار API، ومحتوى JSON منظم، وحالة HTTP صحيحة بقيمة 200.

2. اختبار API باستخدام Postman

يتحول تسجيل الدخول إلى مسار POST ويمرّ بالتحقق قبل المتحكم. البيانات الصحيحة تعيد 200، والحقل الناقص يعيد 422 مع قائمة الأخطاء.

توليد الأصناف

php artisan make:request ApiLoginRequest

الطلبات توضع في app/Http/Requests، لذا يكفي اسم الصنف.

الكود

app/Http/Controllers/AuthController.php — التغييرات

تمرير ApiLoginRequest كنوع للمعامل هو ما يشغّل التحقق. أما register() فهي مؤقتة لما بعد.

namespace App\Http\Controllers;

use App\Http\Requests\ApiLoginRequest;
use App\Traits\ApiResponses;
use Illuminate\Http\JsonResponse;

    /**
     * Authenticate the user.
     */
    public function login(): JsonResponse
    public function login(ApiLoginRequest $request): JsonResponse
    {
        return $this->ok('Hello, Login!');
        return $this->ok($request->get('email'));
    }

    /**
     * Register a new user.
     */
    public function register(): JsonResponse
    {
        return $this->ok('register');
    }
}

app/Http/Requests/ApiLoginRequest.php

القواعد صارت هنا بدل المتحكم. وتعيد authorize() القيمة true لأن الدخول متاح للجميع.

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class ApiLoginRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            'email' => 'required',
            'password' => 'required'
        ];
    }
}

routes/api.php — التغييرات

تحوّل الدخول من GET إلى POST. بيانات الاعتماد لا مكان لها في العنوان.

|
*/

Route::get('/login', [AuthController::class, 'login']);
Route::post('/login', [AuthController::class, 'login']);
Route::post('/register', [AuthController::class, 'register']);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();

التحقق

curl -i -X POST http://127.0.0.1:8000/api/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"secret1234"}'

ستحصل على 200 ومعها بريدك. أرسله دون password فتحصل على 422.

3. تصميم عناوين قائمة على الموارد

يبدأ الـAPI بإعادة صفوف حقيقية. مئة طلب موزّعة على عشرة مستخدمين، تُعرض في GET /api/orders.

حالة الطلب واحدة من pending أو paid أو shipped أو cancelled. والدليل كله يستخدم هذه المجموعة.

توليد الأصناف

php artisan make:model Order -mf

الراية -m تضيف الهجرة و-f تضيف المصنع. أما DatabaseSeeder فموجود مسبقاً، وتكتفي بتعديله.

الكود

app/Models/Order.php

الخاصية $fillable هي ما يجعل Order::create() تقبل مصفوفة. أما العلاقة فتأتي في القسم الثامن.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use HasFactory;

    protected $fillable = ['reference', 'status', 'notes', 'user_id'];
}

database/factories/OrderFactory.php

المراجع تأتي بصيغة ORD-12345، والحالة واحدة من الكلمات الأربع أعلاه.

<?php

namespace Database\Factories;

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

/**
 * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Order>
 */
class OrderFactory extends Factory
{
    /**
     * Define the model's default state.
     *
     * @return array<string, mixed>
     */
    public function definition(): array
    {
        return [
            'user_id' => User::factory(),
            'reference' => strtoupper(fake()->bothify('ord-#####')),
            'notes' => fake()->paragraph(),
            'status' => fake()->randomElement(['pending', 'paid', 'shipped', 'cancelled']),
        ];
    }
}

database/migrations/2024_01_27_055742_create_orders_table.php

العمود user_id مفتاح خارجي، وnotes نص حر.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained();
            $table->string('reference');
            $table->text('notes');
            $table->string('status');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('orders');
    }
};

database/seeders/DatabaseSeeder.php

عشرة مستخدمين أولاً، ثم مئة طلب موزّعة عليهم.

<?php

namespace Database\Seeders;

// use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    /**
     * Seed the application's database.
     */
    public function run(): void
    {
        $users = \App\Models\User::factory(10)->create();

        \App\Models\Order::factory(100)
            ->recycle($users)
            ->create();

        // \App\Models\User::factory()->create([
        //     'name' => 'Test User',
        //     'email' => 'test@example.com',
        // ]);
    }
}

routes/api.php — التغييرات

مسار مؤقت. سيستبدله القسم الرابع بمتحكم.

<?php

use App\Http\Controllers\AuthController;
use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/login', [AuthController::class, 'login']);
Route::post('/register', [AuthController::class, 'register']);

Route::get('/orders', function() {
    return Order::all();
});

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

التحقق

php artisan migrate:fresh --seed
curl -s http://127.0.0.1:8000/api/orders -H "Accept: application/json"

ستعود إليك مئة طلب بصيغة JSON.

4. هيكلة API متعدد الإصدارات

تنتقل الطلبات نفسها إلى /api/v1/orders. كل مسارات الإصدار الأول في ملف مستقل، فتصبح إضافة v2 لاحقاً إضافة ملف.

توليد الأصناف

php artisan make:controller Api/V1/OrderController --api --model=Order
php artisan make:request Api/V1/StoreOrderRequest
php artisan make:request Api/V1/UpdateOrderRequest

بادئة المسار تحدد مساحة الأسماء، فيصبح Api/V1/OrderController هو App\Http\Controllers\Api\V1\OrderController. وتتجاوز --api الدالتين create وedit اللتين تحتاجهما نماذج HTML فقط.

الكود

app/Http/Controllers/Api/V1/OrderController.php

لا تحتوي سوى index() على جسم حتى الآن، وتُستكمل البقية من القسم الثالث عشر.

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Models\Order;
use App\Http\Requests\Api\V1\StoreOrderRequest;
use App\Http\Requests\Api\V1\UpdateOrderRequest;

class OrderController extends Controller
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        return Order::all();
    }

    /**
     * Store a newly created resource in storage.
     */
    public function store(StoreOrderRequest $request)
    {
        //
    }

    /**
     * Display the specified resource.
     */
    public function show(Order $order)
    {
        //
    }

    /**
     * Update the specified resource in storage.
     */
    public function update(UpdateOrderRequest $request, Order $order)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     */
    public function destroy(Order $order)
    {
        //
    }
}

app/Http/Requests/Api/V1/StoreOrderRequest.php

أصناف مولّدة. تعيد authorize() القيمة false، لذا تُجيب الكتابة بـ403 إلى أن تصل السياسات في القسم السابع عشر.

<?php

namespace App\Http\Requests\Api\V1;

use Illuminate\Foundation\Http\FormRequest;

class StoreOrderRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return false;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            //
        ];
    }
}

app/Http/Requests/Api/V1/UpdateOrderRequest.php

الصنف المولّد نفسه. ويحصل الطلبان على قواعد حقيقية في القسم الثالث عشر.

<?php

namespace App\Http\Requests\Api\V1;

use Illuminate\Foundation\Http\FormRequest;

class UpdateOrderRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return false;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            //
        ];
    }
}

bootstrap/app.php

تجعل shouldRenderJsonWhen() الأخطاء تحت api/* تُعرض بصيغة JSON بدل صفحة HTML.

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->shouldRenderJsonWhen(
            fn (Request $request) => $request->is('api/*') || $request->expectsJson(),
        );
    })->create();

routes/api.php — التغييرات

تحل مجموعة v1 محل مسار /orders المؤقت. ويبقى الدخول والتسجيل كما هما.

use App\Http\Controllers\AuthController;
use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(base_path('routes/api_v1.php'));

Route::post('/login', [AuthController::class, 'login']);
Route::post('/register', [AuthController::class, 'register']);

Route::get('/orders', function() {
    return Order::all();
});

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

routes/api_v1.php

يسجّل apiResource الدوال index وstore وshow وupdate وdestroy دفعة واحدة.

<?php

use App\Http\Controllers\Api\V1\OrderController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are registered by bootstrap/app.php and all of them will
| be assigned to the "api" middleware group. Make something great!
|
*/

Route::apiResource('orders', OrderController::class);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

التحقق

php artisan route:list --path=api/v1
curl -s http://127.0.0.1:8000/api/v1/orders -H "Accept: application/json"

تظهر خمسة مسارات لـorders تحت v1، ويعيد الطلب الطلبات المزروعة.

5. المصادقة بالرموز باستخدام Laravel Sanctum

يعيد تسجيل الدخول رمز Sanctum، وتتوقف مسارات الطلبات عن الاستجابة للغرباء. غياب الرمز يعني 401.

توليد الأصناف

php artisan make:controller Api/AuthController
php artisan make:request Api/LoginUserRequest

جاء Sanctum مع php artisan install:api في القسم الأول.

الكود

app/Models/User.php — التغييرات

تأتي createToken() من سمة HasApiTokens الخاصة بـ Sanctum. بدونها لا يملك النموذج هذه الدالة أصلًا، ويسقط تسجيل الدخول بخطأ BadMethodCallException.

use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

#[Fillable(['name', 'email', 'password'])]
#[Hidden(['password', 'remember_token'])]
class User extends Authenticatable
{
    /** @use HasFactory<UserFactory> */
    use HasFactory, Notifiable;
    use HasApiTokens, HasFactory, Notifiable;

app/Http/Controllers/Api/AuthController.php

تتحقق Auth::attempt() من بيانات الاعتماد، ثم تُصدر createToken() الرمز.

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\Api\LoginUserRequest;
use App\Models\User;
use App\Traits\ApiResponses;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller
{
    use ApiResponses;

    /**
     * Authenticate the user and issue an API token.
     */
    public function login(LoginUserRequest $request)
    {
        if (! Auth::attempt($request->only('email', 'password'))) {
            return $this->error('Invalid credentials', 401);
        }

        $user = User::firstWhere('email', $request->email);

        return $this->ok(
            'Authenticated',
            [
                'token' => $user->createToken('API token for ' . $user->email)->plainTextToken
            ]
            );
    }
}

app/Http/Requests/Api/LoginUserRequest.php

أدق من الطلب القديم: بريد صحيح وكلمة مرور من ثمانية محارف فأكثر.

<?php

namespace App\Http\Requests\Api;

use Illuminate\Foundation\Http\FormRequest;

class LoginUserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email'],
            'password' => ['required', 'string', 'min:8'],
        ];
    }
}

app/Traits/ApiResponses.php — التغييرات

يُعرض الملف كاملاً لتوضيح السياق، مع تمييز الأسطر التي تغيرت في هذه الخطوة. تكسب success() مفتاح data ليحمل الرمز، وتعيد error() حالات الفشل بالبنية نفسها.

<?php

namespace App\Traits;

use Illuminate\Http\JsonResponse;

trait ApiResponses
{
    /**
     * Return a successful response.
     */
    protected function ok(string $message): JsonResponse
    protected function ok(string $message, array $data): JsonResponse
    {
        return $this->success($message, 200);
        return $this->success($message, $data, 200);
    }

    /**
     * Return a success response whose payload status matches the HTTP status.
     * Return a success response with the given payload.
     */
    protected function success(string $message, int $statusCode = 200): JsonResponse
    protected function success(string $message, array $data, int $statusCode = 200): JsonResponse
    {
        return response()->json([
            'data' => $data,
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }

    /**
     * Return an error response.
     */
    protected function error(string $message, int $statusCode): JsonResponse
    {
        return response()->json([
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }
}

routes/api.php — التغييرات

صار الدخول يشير إلى المتحكم الجديد. أما مسار register المؤقت من القسم 2 فيرحل مع المتحكم القديم — إنشاء المستخدمين له قسم خاص لاحقًا، ولا يصح ترك مسار يشير إلى دالة لم تعد موجودة.

<?php

use App\Http\Controllers\AuthController;
use App\Http\Controllers\Api\AuthController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(base_path('routes/api_v1.php'));

Route::post('/login', [AuthController::class, 'login']);
Route::post('/register', [AuthController::class, 'register']);

حذف الملفات التي حلّ محلها غيرها

المتحكم والطلب المؤقتان من القسم 2 استبدلهما نظيراهما داخل Api\.

rm app/Http/Controllers/AuthController.php
rm app/Http/Requests/ApiLoginRequest.php

routes/api_v1.php — التغييرات

الوسيط auth:sanctum هو ما يفعّل استجابة 401.

|
*/

Route::apiResource('orders', OrderController::class);
Route::middleware('auth:sanctum')->apiResource('orders', OrderController::class);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();

بيانات الاعتماد الخاطئة تعيد 401 لا 422. فالبيانات سليمة، والفاشل هو الدخول.

التحقق

php artisan tinker --execute="echo App\Models\User::first()->email;"

curl -s -X POST http://127.0.0.1:8000/api/login \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"SEEDED_EMAIL","password":"password"}'

curl -i http://127.0.0.1:8000/api/v1/orders -H "Accept: application/json"

كل المستخدمين المزروعين يستخدمون كلمة المرور password. يعود الرمز في data.token. وبدونه يعيد مسار الطلبات 401، ومعه عبر -H "Authorization: Bearer YOUR_TOKEN" يعمل.

6. إلغاء الرموز وتسجيل الخروج الآمن

يحذف POST /api/logout الرمز الذي نفّذ الطلب. وتبقى الأجهزة الأخرى مسجّلة الدخول.

الكود

app/Http/Controllers/Api/AuthController.php — التغييرات

تعيد currentAccessToken() رمز هذا الطلب. احذفه فينتهي.

use App\Http\Requests\Api\LoginUserRequest;
use App\Models\User;
use App\Traits\ApiResponses;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller

        return $this->ok(
            'Authenticated',
            [
                'token' => $user->createToken('API token for ' . $user->email)->plainTextToken
                'token' => $user->createToken(
                    'API token for ' . $user->email,
                    ['*'],
                    now()->addMonth())->plainTextToken
            ]
            );
    }

    /**
     * Revoke the API token used for the current request.
     */
    public function logout(Request $request)
    {
        $request->user()->currentAccessToken()->delete();

        return $this->ok('');
    }
}

app/Traits/ApiResponses.php — التغييرات

صارت $data بقيمة افتراضية فارغة، فلا تحتاج الاستجابة الخالية إلى تمرير أي شيء.

    /**
     * Return a successful response.
     */
    protected function ok(string $message, array $data): JsonResponse
    protected function ok(string $message, array $data = []): JsonResponse
    {
        return $this->success($message, $data, 200);
    }

    /**
     * Return a success response with the given payload.
     */
    protected function success(string $message, array $data, int $statusCode = 200): JsonResponse
    protected function success(string $message, array $data = [], int $statusCode = 200): JsonResponse
    {
        return response()->json([
            'data' => $data,

routes/api.php — التغييرات

الخروج خلف auth:sanctum. لا يمكنك إلغاء رمز دون إرساله.

Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:sanctum')->post('/logout', [AuthController::class, 'logout']);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();

تنتهي صلاحية الرموز بعد شهر أيضاً، وتُحدَّد عند الإصدار.

التحقق

curl -i -X POST http://127.0.0.1:8000/api/logout \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -i http://127.0.0.1:8000/api/v1/orders \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

يعيد الخروج 200. أعد استخدام الرمز نفسه فتحصل على 401.

7. تصميم استجابات مستقرة

تتوقف الطلبات عن كونها صفوفاً خاماً. يعود كل طلب بالحقول type وid وattributes وrelationships وlinks، والقائمة مقسّمة إلى صفحات.

توليد الأصناف

php artisan make:resource V1/OrderResource

الموارد توضع في app/Http/Resources، فتضع البادئة V1/ هذا المورد في App\Http\Resources\V1.

الكود

app/Http/Controllers/Api/V1/OrderController.php — التغييرات

تقسّم index() النتائج إلى صفحات، وتعيد show() مورداً واحداً.

use App\Models\Order;
use App\Http\Requests\Api\V1\StoreOrderRequest;
use App\Http\Requests\Api\V1\UpdateOrderRequest;
use App\Http\Resources\V1\OrderResource;

class OrderController extends Controller
{

     */
    public function index()
    {
        return Order::all();
        return OrderResource::collection(Order::paginate());
    }

    /**

     */
    public function show(Order $order)
    {
        //
        return new OrderResource($order);
    }

    /**

app/Http/Resources/V1/OrderResource.php

المورد يحدد أسماء الحقول العلنية. فيخرج created_at باسم createdAt.

<?php

namespace App\Http\Resources\V1;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class OrderResource extends JsonResource
{
    // public static $wrap = 'order';
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'type' => 'order',
            'id' => $this->id,
            'attributes' => [
                'reference' => $this->reference,
                'notes' => $this->notes,
                'status' => $this->status,
                'createdAt' => $this->created_at,
                'updatedAt' => $this->updated_at
            ],
            'relationships' => [
                'customer' => [
                    'data' => [
                        'type' => 'user',
                        'id' => $this->user_id
                    ],
                    'links' => [
                        ['self' => 'todo']
                    ]
                ]
            ],
            'links' => [
                ['self' => route('orders.show', ['order' => $this->id])]
            ]
        ];
    }
}

غيّر اسم عمود لاحقاً ولن يتغير سوى هذا الملف.

التحقق

curl -s "http://127.0.0.1:8000/api/v1/orders?page=1" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

يحمل كل عنصر type وid وattributes ورابط self، إضافة إلى links وmeta للصفحات.

8. الحقول والعلاقات الشرطية

صنف مورد واحد يعطي مخرجات مختلفة حسب المسار. الطلب المفرد يُظهر notes، والقائمة تخفيها.

توليد الأصناف

php artisan make:controller Api/V1/UsersController --api --model=User
php artisan make:request Api/V1/StoreUserRequest
php artisan make:request Api/V1/UpdateUserRequest
php artisan make:resource V1/UserResource

الكود

app/Http/Controllers/Api/V1/UsersController.php

الجانب الخاص بالمستخدمين من النمط نفسه.

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Models\User;
use App\Http\Requests\Api\V1\StoreUserRequest;
use App\Http\Requests\Api\V1\UpdateUserRequest;
use App\Http\Resources\V1\UserResource;

class UsersController extends Controller
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        return UserResource::collection(User::paginate());
    }

    /**
     * Store a newly created resource in storage.
     */
    public function store(StoreUserRequest $request)
    {
        //
    }

    /**
     * Display the specified resource.
     */
    public function show(User $user)
    {
        return new UserResource($user);
    }

    /**
     * Update the specified resource in storage.
     */
    public function update(UpdateUserRequest $request, User $user)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     */
    public function destroy(User $user)
    {
        //
    }
}

app/Http/Requests/Api/V1/StoreUserRequest.php

صنف مؤقت الآن، وتأتي القواعد في القسم الحادي والعشرين.

<?php

namespace App\Http\Requests\Api\V1;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return false;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            //
        ];
    }
}

app/Http/Requests/Api/V1/UpdateUserRequest.php

الصنف المؤقت نفسه للتحديث.

<?php

namespace App\Http\Requests\Api\V1;

use Illuminate\Foundation\Http\FormRequest;

class UpdateUserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return false;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            //
        ];
    }
}

app/Http/Resources/V1/OrderResource.php — التغييرات

تُخفي when() الحقل notes ما لم يكن المسار orders.show.

            'id' => $this->id,
            'attributes' => [
                'reference' => $this->reference,
                'notes' => $this->notes,
                'notes' => $this->when(
                    $request->routeIs('orders.show'),
                    $this->notes
                ),
                'status' => $this->status,
                'createdAt' => $this->created_at,
                'updatedAt' => $this->updated_at

                    ]
                ]
            ],
            'includes' => [
                new UserResource($this->user)
            ],
            'links' => [
                ['self' => route('orders.show', ['order' => $this->id])]
            ]

app/Http/Resources/V1/UserResource.php

تضيف mergeWhen() الأزمنة في مسارات users.* فقط.

<?php

namespace App\Http\Resources\V1;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'type' => 'user',
            'id' => $this->id,
            'attributes' => [
                'name' => $this->name,
                'email' => $this->email,
                $this->mergeWhen($request->routeIs('users.*'), [
                    'emailVerifiedAt' => $this->email_verified_at,
                    'createdAt' => $this->created_at,
                    'updatedAt' => $this->updated_at,
                ])
            ]
        ];
    }
}

app/Models/Order.php — التغييرات

يضيف علاقة user() التي يقرأها مورد الطلب.

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Order extends Model
{
    use HasFactory;

    protected $fillable = ['reference', 'status', 'notes', 'user_id'];

    /**
     * Get the user that placed the order.
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

routes/api_v1.php — التغييرات

يسجّل مورد المستخدمين خلف auth:sanctum.

<?php

use App\Http\Controllers\Api\V1\OrderController;
use App\Http\Controllers\Api\V1\UsersController;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

*/

Route::middleware('auth:sanctum')->apiResource('orders', OrderController::class);
Route::middleware('auth:sanctum')->apiResource('users', UsersController::class);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();

routes/api.php — التغييرات

نسخ القسم الرابع مسار /user إلى routes/api_v1.php بدل أن ينقله، فظل GET /api/user وGET /api/v1/user يعطيان النتيجة نفسها منذ ذلك الحين. وبعد أن صار الجانب المُصدَّر يملك سطح المستخدمين كاملًا، نحذف التوأم غير المُصدَّر. ويرحل معه Request إذ لم يعد شيء في هذا الملف يستخدمه.

use App\Http\Controllers\Api\AuthController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')->group(base_path('routes/api_v1.php'));

Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:sanctum')->post('/logout', [AuthController::class, 'logout']);

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

صار api.php مقتصرًا على مسارات الرموز ونقطة تركيب v1. وكل ما يقرأه العميل أو يكتبه يقع خلف إصدار.

صنف لكل نموذج أفضل من صنف لكل نقطة نهاية. غيّر اسم حقل مرة واحدة فيتبعه المساران.

التحقق

curl -s http://127.0.0.1:8000/api/v1/orders \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -s http://127.0.0.1:8000/api/v1/orders/1 \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -i http://127.0.0.1:8000/api/user \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

القائمة بلا مفتاح notes، والطلب المفرد يحتويه. ويُظهر /api/v1/users/1 أزمنة المستخدم الإضافية. أما /api/user القديم فيعيد الآن 404 — استخدم /api/v1/user.

9. تحميل العلاقات عند الطلب

يضمّن ?include=customer بيانات العميل داخل كل طلب. وبدونه لا يُنفَّذ أي استعلام إضافي.

توليد الأصناف

php artisan make:controller Api/V1/ApiController

متحكم عادي لا متحكم مورد. يضم دوال مساعدة مشتركة فقط.

الكود

app/Http/Controllers/Api/V1/ApiController.php

تقرأ include() معامل الاستعلام وتجيب بنعم أو لا.

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;

class ApiController extends Controller
{
    /**
     * Determine whether the given relationship was requested via the include parameter.
     */
    public function include(string $relationship) : bool
    {
        $param = request()->get('include');

        if (!isset($param)) {
            return false;
        }

        $includeValues = explode(',', strtolower($param));

        return in_array(strtolower($relationship), $includeValues);
    }
}

app/Http/Controllers/Api/V1/OrderController.php — التغييرات

يحمّل العلاقة عبر with() عند طلب العميل فقط.

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Models\Order;
use App\Http\Requests\Api\V1\StoreOrderRequest;
use App\Http\Requests\Api\V1\UpdateOrderRequest;
use App\Http\Resources\V1\OrderResource;

class OrderController extends Controller
class OrderController extends ApiController
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        if ($this->include('customer')) {
            return OrderResource::collection(Order::with('user')->paginate());
        }

        return OrderResource::collection(Order::paginate());
    }

     */
    public function show(Order $order)
    {
        if ($this->include('customer')) {
            return new OrderResource($order->load('user'));
        }

        return new OrderResource($order);
    }

app/Http/Controllers/Api/V1/UsersController.php — التغييرات

الأمر نفسه للمستخدمين وطلباتهم.

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Models\User;
use App\Http\Requests\Api\V1\StoreUserRequest;
use App\Http\Requests\Api\V1\UpdateUserRequest;
use App\Http\Resources\V1\UserResource;

class UsersController extends Controller
class UsersController extends ApiController
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        if ($this->include('orders')) {
            return UserResource::collection(User::with('orders')->paginate());
        }

        return UserResource::collection(User::paginate());
    }

     */
    public function show(User $user)
    {
        if ($this->include('orders')) {
            return new UserResource($user->load('orders'));
        }

        return new UserResource($user);
    }

app/Http/Resources/V1/OrderResource.php — التغييرات

تُبقي whenLoaded() مفتاح includes خارج الاستجابة ما لم تكن العلاقة محمّلة.

                        'id' => $this->user_id
                    ],
                    'links' => [
                        ['self' => 'todo']
                        'self' => route('users.show', ['user' => $this->user_id])
                    ]
                ]
            ],
            'includes' => [
                new UserResource($this->user)
            ],
            'includes' => new UserResource($this->whenLoaded('user')),
            'links' => [
                ['self' => route('orders.show', ['order' => $this->id])]
                'self' => route('orders.show', ['order' => $this->id])
            ]
        ];
    }

app/Http/Resources/V1/UserResource.php — التغييرات

يضيف includes للطلبات المحمّلة ورابط self.

                    'createdAt' => $this->created_at,
                    'updatedAt' => $this->updated_at,
                ])
            ],
            'includes' => OrderResource::collection($this->whenLoaded('orders')),
            'links' => [
                'self' => route('users.show', ['user' => $this->id])
            ]
        ];
    }

app/Models/User.php — التغييرات

يضيف علاقة orders()، وهي النصف المقابل لعلاقة belongsTo التي أُضيفت إلى Order في القسم الثامن.

// use Illuminate\Contracts\Auth\MustVerifyEmail;
use Database\Factories\UserFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }

    /**
     * Get the orders placed by the user.
     */
    public function orders() : HasMany
    {
        return $this->hasMany(Order::class);
    }
}

بدون whenLoaded() كانت صفحة الطلبات ستُطلق استعلاماً لكل صف. وعدّ الاستعلامات يُظهر الفرق جليًا: صفحة من 15 طلبية تكلّف استعلامين بدون include، وثلاثة معه. أما includes غير المشروط في القسم الثامن فكان يكلّف 17.

التحقق

curl -s "http://127.0.0.1:8000/api/v1/orders?include=customer" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -s "http://127.0.0.1:8000/api/v1/orders" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة الأولى فيها كتلة includes، والثانية بلا شيء.

10. فلاتر استعلام قابلة لإعادة الاستخدام

ترشيح من سلسلة الاستعلام: ?filter[status]=pending، أو مدى تاريخي، أو ?filter[reference]=ORD-1*.

توليد الأصناف

php artisan make:class Http/Filters/V1/QueryFilter
php artisan make:class Http/Filters/V1/OrderFilter

المرشّحات ليست مفهوماً في Laravel، فلا مولّد لها. وينشئ make:class صنفاً عادياً في المسار الذي تحدده.

الكود

app/Http/Controllers/Api/V1/OrderController.php — التغييرات

تستقبل index() النوع OrderFilter، ويحلّه Laravel وقد وُضع الطلب بداخله.

namespace App\Http\Controllers\Api\V1;

use App\Http\Filters\V1\OrderFilter;
use App\Models\Order;
use App\Http\Requests\Api\V1\StoreOrderRequest;
use App\Http\Requests\Api\V1\UpdateOrderRequest;

    /**
     * Display a listing of the resource.
     */
    public function index()
    public function index(OrderFilter $filters)
    {
        if ($this->include('customer')) {
            return OrderResource::collection(Order::with('user')->paginate());
        }

        return OrderResource::collection(Order::paginate());
        return OrderResource::collection(Order::filter($filters)->paginate());
    }

    /**

    public function show(Order $order)
    {
        if ($this->include('customer')) {
            return new OrderResource($order->load('user'));
            return new OrderResource($order->load('customer'));
        }

        return new OrderResource($order);

app/Http/Filters/V1/QueryFilter.php

تستدعي apply() الدالة المطابقة لكل مفتاح استعلام. لا دالة، لا أثر.

<?php

namespace App\Http\Filters\V1;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Http\Request;

abstract class QueryFilter
{
    protected $builder;
    protected $request;

    /**
     * Create a new filter instance for the current request.
     */
    public function __construct(Request $request)
    {
        $this->request = $request;
    }

    /**
     * Apply the given filters to the builder.
     */
    protected function filter($arr)
    {
        foreach($arr as $key => $value) {
            if (method_exists($this, $key)) {
                $this->$key($value);
            }
        }

        return $this->builder;
    }

    /**
     * Apply the request query parameters to the given builder.
     */
    public function apply(Builder $builder)
    {
        $this->builder = $builder;

        foreach($this->request->all() as $key => $value) {
            if (method_exists($this, $key)) {
                $this->$key($value);
            }
        }

        return $builder;
    }
}

app/Http/Filters/V1/OrderFilter.php

دالة لكل مرشّح مدعوم. ويتحول * إلى حرف بدل في reference.

وinclude() هي الدالة الوحيدة التي تستقبل اسم علاقة لا قيمة عمود، لذا تتحقق من كل اسم عبر isRelation() أولًا. فلو سلّمت with() اسمًا لا يعرّفه النموذج رمى Eloquent الخطأ Call to undefined relationship، ووصل إلى العميل على هيئة 500 — انهيار غير معالَج سببه مجرد خطأ مطبعي في معامل استعلام. وتصفية القائمة تجعل الاسم المجهول يتصرف كأي معامل غير معروف: يُتجاهل.

<?php

namespace App\Http\Filters\V1;

class OrderFilter extends QueryFilter
{
    /**
     * Filter by creation date, or by a date range when two dates are given.
     */
    public function createdAt($value)
    {
        $dates = explode(',', $value);

        if (count($dates) > 1) {
            return $this->builder->whereBetween('created_at', $dates);
        }

        return $this->builder->whereDate('created_at', $value);
    }

    /**
     * Eager load the requested relationships, ignoring any the model does not define.
     */
    public function include($value)
    {
        if (!is_string($value)) {
            return $this->builder;
        }

        $model = $this->builder->getModel();

        $relations = array_filter(
            explode(',', $value),
            fn ($relation) => $model->isRelation($relation)
        );

        return $this->builder->with($relations);
    }

    /**
     * Filter by one or more statuses.
     */
    public function status($value)
    {
        return $this->builder->whereIn('status', explode(',', $value));
    }

    /**
     * Filter by reference, where * acts as a wildcard.
     */
    public function reference($value)
    {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('reference', 'like', $likeStr);
    }

    /**
     * Filter by update date, or by a date range when two dates are given.
     */
    public function updatedAt($value)
    {
        $dates = explode(',', $value);

        if (count($dates) > 1) {
            return $this->builder->whereBetween('updated_at', $dates);
        }

        return $this->builder->whereDate('updated_at', $value);
    }
}

app/Http/Resources/V1/OrderResource.php — التغييرات

صار اسم العلاقة customer، فتبعتها whenLoaded().

                    ]
                ]
            ],
            'includes' => new UserResource($this->whenLoaded('user')),
            'includes' => new UserResource($this->whenLoaded('customer')),
            'links' => [
                'self' => route('orders.show', ['order' => $this->id])
            ]

app/Models/Order.php — التغييرات

النطاق filter يتيح كتابة Order::filter($filters). وتُعاد تسمية العلاقة إلى customer في الجولة نفسها ليطابق المصطلح العلني ما يظهر في الاستجابة — أما العمود فيبقى user_id، ولذلك وجب ذكره صراحةً عند إعادة التسمية.

<?php

namespace App\Models;

use App\Http\Filters\V1\QueryFilter;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Order extends Model
{
    /** @use HasFactory<\Database\Factories\OrderFactory> */
    use HasFactory;

    protected $fillable = ['reference', 'status', 'notes', 'user_id'];

    /**
     * Get the user that placed the order.
     * Get the customer that placed the order.
     */
    public function user(): BelongsTo
    public function customer(): BelongsTo
    {
        return $this->belongsTo(User::class);
        return $this->belongsTo(User::class, 'user_id');
    }

    /**
     * Apply the given query filters to the builder.
     */
    public function scopeFilter(Builder $builder, QueryFilter $filters)
    {
        return $filters->apply($builder);
    }
}

صنف المرشّح هو قائمة السماح. المعامل بلا دالة لا يفعل شيئاً، وهذه هي الطريقة الآمنة للفشل.

التحقق

curl -s "http://127.0.0.1:8000/api/v1/orders?filter[status]=pending" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -s "http://127.0.0.1:8000/api/v1/orders?filter[reference]=ORD-1*" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

النداء الأول يعيد الطلبات قيد الانتظار فقط، والثاني يعيد كل مرجع يبدأ بـORD-1.

11. الموارد المتداخلة وفلترة العلاقات

عنوانان جديدان: /api/v1/customers و/api/v1/customers/{customer}/orders.

توليد الأصناف

php artisan make:controller Api/V1/CustomersController --api --model=User
php artisan make:controller Api/V1/CustomerOrdersController

المتحكم المتداخل لا يحتاج --api. يبدأ بدالة index وحدها، وتصل بقية الأفعال حين تحتاجها الأقسام اللاحقة: store في القسم 13، وdestroy في القسم 14، وreplace في القسم 15، وupdate في القسم 16. سجّل index وحده عند هذه النقطة؛ فإتاحة مسارات Resource قبل وجود دوالها في Controller تجعل طلبات تبدو صحيحة تنتهي باستجابة 500.

الكود

app/Http/Controllers/Api/V1/CustomerOrdersController.php

يرشّح بـuser_id ثم يمرّر الاستعلام إلى OrderFilter نفسه.

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Filters\V1\OrderFilter;
use App\Http\Resources\V1\OrderResource;
use App\Models\Order;

class CustomerOrdersController extends Controller
{
    /**
     * Display a listing of the resource.
     */
    public function index($customer_id, OrderFilter $filters)
    {
        return OrderResource::collection(
            Order::where('user_id', $customer_id)->filter($filters)->paginate()
        );
    }
}

app/Http/Controllers/Api/V1/CustomersController.php

المستخدمون بوصفهم عملاء، مع ?include=orders.

<?php

namespace App\Http\Controllers\Api\V1;

use App\Models\User;
use App\Http\Requests\Api\V1\StoreUserRequest;
use App\Http\Requests\Api\V1\UpdateUserRequest;
use App\Http\Resources\V1\UserResource;

class CustomersController extends ApiController
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        if ($this->include('orders')) {
            return UserResource::collection(User::with('orders')->paginate());
        }

        return UserResource::collection(User::paginate());
    }

    /**
     * Store a newly created resource in storage.
     */
    public function store(StoreUserRequest $request)
    {
        //
    }

    /**
     * Display the specified resource.
     */
    public function show(User $customer)
    {
        if ($this->include('orders')) {
            return new UserResource($customer->load('orders'));
        }

        return new UserResource($customer);
    }

    /**
     * Update the specified resource in storage.
     */
    public function update(UpdateUserRequest $request, User $user)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     */
    public function destroy(User $user)
    {
        //
    }
}

app/Http/Resources/V1/OrderResource.php — التغييرات

روابط العلاقات وself صارت تشير إلى مسارات حقيقية.

                        'id' => $this->user_id
                    ],
                    'links' => [
                        'self' => route('users.show', ['user' => $this->user_id])
                        'self' => route('customers.show', ['customer' => $this->user_id])
                    ]
                ]
            ],

app/Http/Resources/V1/UserResource.php — التغييرات

الحقول والروابط صارت تتبع مسارات customers.*.

            'attributes' => [
                'name' => $this->name,
                'email' => $this->email,
                $this->mergeWhen($request->routeIs('users.*'), [
                $this->mergeWhen($request->routeIs('customers.*'), [
                    'emailVerifiedAt' => $this->email_verified_at,
                    'createdAt' => $this->created_at,
                    'updatedAt' => $this->updated_at,

            ],
            'includes' => OrderResource::collection($this->whenLoaded('orders')),
            'links' => [
                'self' => route('users.show', ['user' => $this->id])
                'self' => route('customers.show', ['customer' => $this->id])
            ]
        ];
    }

routes/api_v1.php — التغييرات

يسجّل customers والمسار المتداخل customers.orders.

<?php

use App\Http\Controllers\Api\V1\OrderController;
use App\Http\Controllers\Api\V1\UsersController;

use App\Http\Controllers\Api\V1\CustomersController;
use App\Http\Controllers\Api\V1\CustomerOrdersController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

*/

Route::middleware('auth:sanctum')->apiResource('orders', OrderController::class);
Route::middleware('auth:sanctum')->apiResource('users', UsersController::class);
Route::middleware('auth:sanctum')->apiResource('customers', CustomersController::class);
Route::middleware('auth:sanctum')->apiResource('customers.orders', CustomerOrdersController::class)->only('index');

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();

حذف الملف الذي حلّ محله غيره

حلّ customers محل مورد users في ملف المسارات، فلم يبقَ شيء يشير إلى UsersController. ويستحدث القسم 21 متحكمًا منفصلًا باسم UserController لإدارة المستخدمين بدل إحياء هذا، فهو ميت من هنا فصاعدًا.

rm app/Http/Controllers/Api/V1/UsersController.php

أما UserResource فيبقى — إذ يعيده CustomersController، وهو سبب ظهور بنية العميل نفسها تحت الاسمين.

بنية الطلب واحدة في المسارين، فيقرأ العميل أياً منهما بالطريقة نفسها.

التحقق

php artisan route:list --path=api/v1/customers

curl -s "http://127.0.0.1:8000/api/v1/customers/1/orders?filter[status]=pending" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -s http://127.0.0.1:8000/api/v1/customers/1 \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

تظهر المسارات المتداخلة في القائمة، ويعيد الطلب طلبات ذلك العميل قيد الانتظار. وصارت كل روابط self تشير إلى /api/v1/customers/...، واختفى /api/v1/users.

12. ترتيب آمن يتحكم به العميل

ترتيب من سلسلة الاستعلام: ?sort=status، و?sort=-createdAt للتنازلي، أو الاثنان معاً.

توليد الأصناف

php artisan make:class Http/Filters/V1/CustomerFilter

الكود

app/Http/Controllers/Api/V1/CustomersController.php — التغييرات

تستقبل index() النوع CustomerFilter، فيصبح ترشيح العملاء وترتيبهم كالطلبات.

namespace App\Http\Controllers\Api\V1;

use App\Http\Filters\V1\CustomerFilter;
use App\Models\User;
use App\Http\Requests\Api\V1\StoreUserRequest;
use App\Http\Requests\Api\V1\UpdateUserRequest;

    /**
     * Display a listing of the resource.
     */
    public function index()
    public function index(CustomerFilter $filters)
    {
        if ($this->include('orders')) {
            return UserResource::collection(User::with('orders')->paginate());
        }

        return UserResource::collection(User::paginate());
        return UserResource::collection(User::filter($filters)->paginate());
    }

    /**

app/Http/Filters/V1/CustomerFilter.php

يحدد ما يجوز ترتيب العملاء به. وتحرس include() اسم العلاقة تمامًا كما يفعل OrderFilter في القسم العاشر — إذ إن with() غير المتحقَّق منه يحوّل ?include=bogus إلى 500 هنا أيضًا.

<?php

namespace App\Http\Filters\V1;

class CustomerFilter extends QueryFilter
{
    protected $sortable = [
        'name',
        'email',
        'createdAt' => 'created_at',
        'updatedAt' => 'updated_at'
    ];

    /**
     * Filter by creation date, or by a date range when two dates are given.
     */
    public function createdAt($value)
    {
        $dates = explode(',', $value);

        if (count($dates) > 1) {
            return $this->builder->whereBetween('created_at', $dates);
        }

        return $this->builder->whereDate('created_at', $value);
    }

    /**
     * Eager load the requested relationships, ignoring any the model does not define.
     */
    public function include($value)
    {
        if (!is_string($value)) {
            return $this->builder;
        }

        $model = $this->builder->getModel();

        $relations = array_filter(
            explode(',', $value),
            fn ($relation) => $model->isRelation($relation)
        );

        return $this->builder->with($relations);
    }

    /**
     * Filter by one or more identifiers.
     */
    public function id($value)
    {
        return $this->builder->whereIn('id', explode(',', $value));
    }

    /**
     * Filter by email, where * acts as a wildcard.
     */
    public function email($value)
    {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('email', 'like', $likeStr);
    }

    /**
     * Filter by name, where * acts as a wildcard.
     */
    public function name($value)
    {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('name', 'like', $likeStr);
    }

    /**
     * Filter by update date, or by a date range when two dates are given.
     */
    public function updatedAt($value)
    {
        $dates = explode(',', $value);

        if (count($dates) > 1) {
            return $this->builder->whereBetween('updated_at', $dates);
        }

        return $this->builder->whereDate('updated_at', $value);
    }
}

app/Http/Filters/V1/QueryFilter.php — التغييرات

تفحص sort() كل مفتاح مقابل $sortable قبل وصوله إلى orderBy(). والإشارة - في البداية تعني تنازلياً.

{
    protected $builder;
    protected $request;
    protected $sortable = [];

    /**
     * Create a new filter instance for the current request.

    public function __construct(Request $request)
    {
        $this->request = $request;
    }

    /**
     * Apply the request query parameters to the given builder.
     */
    public function apply(Builder $builder)
    {
        $this->builder = $builder;

        foreach($this->request->all() as $key => $value) {
            if (method_exists($this, $key)) {
                $this->$key($value);
            }
        }

        return $builder;
    }

    /**

    }

    /**
     * Apply the request query parameters to the given builder.
     * Sort the query by the requested columns.
     */
    public function apply(Builder $builder)
    protected function sort($value)
    {
        $this->builder = $builder;
        $sortAttributes = explode(',', $value);

        foreach($this->request->all() as $key => $value) {
            if (method_exists($this, $key)) {
                $this->$key($value);
        foreach($sortAttributes as $sortAttribute) {
            $direction = 'asc';

            if (strpos($sortAttribute, '-') === 0) {
                $direction = 'desc';
                $sortAttribute = substr($sortAttribute, 1);
            }

            if (!in_array($sortAttribute, $this->sortable) && !array_key_exists($sortAttribute, $this->sortable)) {
                continue;
            }

            $columnName = $this->sortable[$sortAttribute] ?? null;

            if ($columnName === null) {
                $columnName = $sortAttribute;
            }

            $this->builder->orderBy($columnName, $direction);
        }

        return $builder;
    }
}

app/Http/Filters/V1/OrderFilter.php — التغييرات

القائمة نفسها للطلبات. والخريطة تترجم createdAt إلى created_at.

class OrderFilter extends QueryFilter
{
    protected $sortable = [
        'reference',
        'status',
        'createdAt' => 'created_at',
        'updatedAt' => 'updated_at'
    ];

    /**
     * Filter by creation date, or by a date range when two dates are given.
     */

app/Models/User.php — التغييرات

يضيف النطاق filter إلى User، وهو النطاق نفسه الذي ناله Order في القسم العاشر.

namespace App\Models;

// use Illuminate\Contracts\Auth\MustVerifyEmail;
use App\Http\Filters\V1\QueryFilter;
use Database\Factories\UserFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Foundation\Auth\User as Authenticatable;

    {
        return $this->hasMany(Order::class);
    }

    /**
     * Apply the given query filters to the builder.
     */
    public function scopeFilter(Builder $builder, QueryFilter $filters)
    {
        return $filters->apply($builder);
    }
}

تمرير المفتاح كما هو إلى orderBy() يتيح الترتيب بأي عمود. والقائمة هي المقصود.

التحقق

curl -s "http://127.0.0.1:8000/api/v1/orders?sort=-createdAt,status" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

curl -s "http://127.0.0.1:8000/api/v1/orders?sort=password" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN"

النداء الأول يرتّب الأحدث أولاً ثم بالحالة، والثاني يُتجاهل لأن password ليس في القائمة.

13. إنشاء الموارد باستخدام POST

يستقبل POST /api/v1/orders بنية المستند نفسها التي يعيدها الـAPI، وينشئ الطلب.

الكود

app/Http/Controllers/Api/V1/ApiController.php — التغييرات

يضم ApiResponses لتستطيع المتحكمات الوارثة استدعاء error().

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Traits\ApiResponses;

class ApiController extends Controller
{
    use ApiResponses;

    /**
     * Determine whether the given relationship was requested via the include parameter.
     */

app/Http/Controllers/Api/V1/CustomerOrdersController.php — التغييرات