بناء API جاهز للإنتاج باستخدام Laravel 13

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

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

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

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

• 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

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

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 للاستجابات

أنشئ المجلد والملف:

mkdir app/Traits

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

app/Traits/ApiResponses.php

<?php

namespace App\Traits;

trait ApiResponses {
    protected function ok($message) {
        return $this->success($message, 200);
    }

    protected function success($message, $statusCode = 200) {
        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\Request;

class AuthController extends Controller
{
    use ApiResponses;
    public function login() {
        return $this->ok('Hello, Login!');
    }
}

يستورد المتحكم ApiResponses ويستخدمه، فتكون دوال الـTrait المحمية متاحة داخل المتحكم. استيراد Request موجود في التنفيذ المرجعي، لكنه لم يُستخدم بعد.

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

استخدام Postman لإرسال طلبات API والتحقق من المدخلات وفحص أخطاء JSON بدلاً من الاعتماد على المتصفح.

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

• app/Http/Controllers/AuthController.php
• app/Http/Requests/ApiLoginRequest.php
• routes/api.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

app/Http/Controllers/AuthController.php

<?php

namespace App\Http\Controllers;

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

class AuthController extends Controller
{
    use ApiResponses;
    public function login(ApiLoginRequest $request) {

        return $this->ok($request->get('email'));
    }

    public function register() {
        return $this->ok('register');
    }
}

app/Http/Requests/ApiLoginRequest.php

<?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

<?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::prefix('v1')->group(base_path('routes/api_v1.php'));

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


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

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

تصميم مسارات قائمة على الموارد للطلبيات وتجهيز الموديلات والمصانع والترحيلات والبيانات التجريبية.

تحمل كل طلبية رمز حالة من حرف واحد: P (قيد الانتظار) وA (مدفوع) وS (تم الشحن) وC (ملغى). وتستخدم جميع قواعد التحقق والفلاتر والمصانع في هذا الدليل المجموعة نفسها.

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

• app/Http/Controllers/AuthController.php
• app/Http/Requests/ApiLoginRequest.php
• app/Models/Order.php
• database/factories/OrderFactory.php
• database/migrations/2024_01_27_055742_create_orders_table.php
• database/seeders/DatabaseSeeder.php
• routes/api.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

app/Http/Controllers/AuthController.php

<?php

namespace App\Http\Controllers;

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

class AuthController extends Controller
{
    use ApiResponses;
    public function login() {
        return $this->ok('Hello, Login!');
    }
}

app/Models/Order.php

<?php

namespace App\Models;

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

class Order extends Model
{
    use HasFactory;
}

database/factories/OrderFactory.php

<?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(['P', 'A', 'S', 'C']),
        ];
    }
}

database/migrations/2024_01_27_055742_create_orders_table.php

<?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;

/*
|--------------------------------------------------------------------------
| 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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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();
});

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

إنشاء حدود واضحة للإصدار الأول من API باستخدام مسارات ومتحكمات وطلبات مخصصة.

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

• app/Http/Controllers/Api/V1/OrderController.php
• app/Http/Requests/Api/V1/StoreOrderRequest.php
• app/Http/Requests/Api/V1/UpdateOrderRequest.php
• bootstrap/app.php
• routes/api.php
• routes/api_v1.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?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

<?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 [
            //
        ];
    }
}

routes/api.php

<?php

use Illuminate\Support\Facades\Route;

// Laravel adds the /api prefix when this file is registered in bootstrap/app.php.
Route::prefix('v1')->group(base_path('routes/api_v1.php'));

bootstrap/app.php

<?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

<?php

use App\Http\Controllers\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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

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

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

routes/api_v1.php

<?php

use App\Http\Controllers\Api\V1\OrderController;
use App\Http\Controllers\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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

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

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

مصادقة عملاء API باستخدام Laravel Sanctum وإنشاء الرموز وحماية المسارات ذات الإصدارات.

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

• app/Http/Controllers/Api/AuthController.php
• app/Http/Controllers/AuthController.php
• app/Http/Requests/Api/LoginUserRequest.php
• app/Traits/ApiResponses.php
• routes/api.php
• routes/api_v1.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

app/Http/Controllers/Api/AuthController.php

<?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\Http\Request;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller
{
    use ApiResponses;
    public function login(LoginUserRequest $request) {
        $request->validated($request->all());

        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

<?php

namespace App\Traits;

trait ApiResponses {
    protected function ok($message, $data) {
        return $this->success($message, $data, 200);
    }

    protected function success($message, $data, $statusCode = 200) {
        return response()->json([
            'data' => $data,
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }

    protected function error($message, $statusCode) {
        return response()->json([
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }
}

routes/api.php

<?php

use App\Http\Controllers\Api\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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

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

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

routes/api_v1.php

<?php

use App\Http\Controllers\Api\V1\OrderController;
use App\Http\Controllers\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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

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

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

تسجيل خروج العملاء بأمان عبر إلغاء رموز Sanctum وإعادة استجابات موحدة بلا محتوى.

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

• app/Http/Controllers/Api/AuthController.php
• app/Traits/ApiResponses.php
• routes/api.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

app/Http/Controllers/Api/AuthController.php

<?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\Http\Request;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller
{
    use ApiResponses;
    public function login(LoginUserRequest $request) {
        $request->validated($request->all());

        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,
                    ['*'],
                    now()->addMonth())->plainTextToken
            ]
            );
    }

    public function logout(Request $request) {
        $request->user()->currentAccessToken()->delete();

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

app/Traits/ApiResponses.php

<?php

namespace App\Traits;

trait ApiResponses {
    protected function ok($message, $data = []) {
        return $this->success($message, $data, 200);
    }

    protected function success($message, $data = [], $statusCode = 200) {
        return response()->json([
            'data' => $data,
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }

    protected function error($message, $statusCode) {
        return response()->json([
            'message' => $message,
            'status' => $statusCode
        ], $statusCode);
    }
}

routes/api.php

<?php

use App\Http\Controllers\Api\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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

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

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

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

تحويل طلبيات Eloquent إلى عقد JSON عام ومستقر باستخدام Laravel API Resources.

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

• app/Http/Controllers/Api/V1/OrderController.php
• app/Http/Resources/V1/OrderResource.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?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;
use App\Http\Resources\V1\OrderResource;

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

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

    /**
     * Display the specified resource.
     */
    public function show(Order $order)
    {
        return new OrderResource($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/Resources/V1/OrderResource.php

<?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])]
            ]
        ];
    }
}

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

تشكيل استجابات مختلفة من المورد نفسه عبر إظهار الحقول والعلاقات أو إخفائها شرطياً.

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

• app/Http/Controllers/Api/V1/UsersController.php
• app/Http/Requests/Api/V1/StoreUserRequest.php
• app/Http/Requests/Api/V1/UpdateUserRequest.php
• app/Http/Resources/V1/OrderResource.php
• app/Http/Resources/V1/UserResource.php
• app/Models/Order.php
• routes/api_v1.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?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->when(
                    $request->routeIs('orders.show'),
                    $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']
                    ]
                ]
            ],
            'includes' => [
                new UserResource($this->user)
            ],
            'links' => [
                ['self' => route('orders.show', ['order' => $this->id])]
            ]
        ];
    }
}

app/Http/Resources/V1/UserResource.php

<?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

<?php

namespace App\Models;

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

class Order extends Model
{
    use HasFactory;

    public function user(): BelongsTo {
        return $this->belongsTo(User::class);
    }
}

routes/api_v1.php

<?php

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

use App\Http\Controllers\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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();
});

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

السماح للمستهلك بطلب بيانات العلاقات عبر معامل include وتجنب الاستعلامات غير الضرورية.

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

• app/Http/Controllers/Api/V1/ApiController.php
• app/Http/Controllers/Api/V1/OrderController.php
• app/Http/Controllers/Api/V1/UsersController.php
• app/Http/Resources/V1/OrderResource.php
• app/Http/Resources/V1/UserResource.php
• app/Models/User.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class ApiController extends Controller
{
    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

<?php

namespace App\Http\Controllers\Api\V1;

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 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());
    }

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

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

        return new OrderResource($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/Controllers/Api/V1/UsersController.php

<?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 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());
    }

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

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

        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/Resources/V1/OrderResource.php

<?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->when(
                    $request->routeIs('orders.show'),
                    $this->notes
                ),
                'status' => $this->status,
                'createdAt' => $this->created_at,
                'updatedAt' => $this->updated_at
            ],
            'relationships' => [
                'customer' => [
                    'data' => [
                        'type' => 'user',
                        'id' => $this->user_id
                    ],
                    'links' => [
                        'self' => route('users.show', ['user' => $this->user_id])
                    ]
                ]
            ],
            'includes' => new UserResource($this->whenLoaded('user')),
            'links' => [
                'self' => route('orders.show', ['order' => $this->id])
            ]
        ];
    }
}

app/Http/Resources/V1/UserResource.php

<?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,
                ])
            ],
            'includes' => OrderResource::collection($this->whenLoaded('orders')),
            'links' => [
                'self' => route('users.show', ['user' => $this->id])
            ]
        ];
    }
}

app/Models/User.php

<?php

namespace App\Models;

// use Illuminate\Contracts\Auth\MustVerifyEmail;
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;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<int, string>
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
    ];

    public function orders() : HasMany {
        return $this->hasMany(Order::class);
    }
}

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

ربط حقول ومعاملات query string بفئات فلترة قابلة لإعادة الاستخدام للبحث في الطلبيات.

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

• app/Http/Controllers/Api/V1/OrderController.php
• app/Http/Filters/V1/QueryFilter.php
• app/Http/Filters/V1/OrderFilter.php
• app/Http/Resources/V1/OrderResource.php
• app/Models/Order.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?php

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;
use App\Http\Resources\V1\OrderResource;

class OrderController extends ApiController
{
    /**
     * Display a listing of the resource.
     */
    public function index(OrderFilter $filters)
    {
        return OrderResource::collection(Order::filter($filters)->paginate());
    }

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

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

        return new OrderResource($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/Filters/V1/QueryFilter.php

<?php

namespace App\Http\Filters\V1;

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

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

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

    protected function filter($arr) {
        foreach($arr as $key => $value) {
            if (method_exists($this, $key)) {
                $this->$key($value);
            }
        }

        return $this->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

<?php

namespace App\Http\Filters\V1;

class OrderFilter extends QueryFilter {
    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);
    }

    public function include($value) {
        return $this->builder->with($value);
    }

    public function status($value) {
        return $this->builder->whereIn('status', explode(',', $value));
    }

    public function reference($value) {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('reference', 'like', $likeStr);
    }

    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

<?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->when(
                    $request->routeIs('orders.show'),
                    $this->notes
                ),
                'status' => $this->status,
                'createdAt' => $this->created_at,
                'updatedAt' => $this->updated_at
            ],
            'relationships' => [
                'customer' => [
                    'data' => [
                        'type' => 'user',
                        'id' => $this->user_id
                    ],
                    'links' => [
                        'self' => route('users.show', ['user' => $this->user_id])
                    ]
                ]
            ],
            'includes' => new UserResource($this->whenLoaded('customer')),
            'links' => [
                'self' => route('orders.show', ['order' => $this->id])
            ]
        ];
    }
}

app/Models/Order.php

<?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;

    public function customer(): BelongsTo {
        return $this->belongsTo(User::class, 'user_id');
    }

    public function scopeFilter(Builder $builder, QueryFilter $filters) {
        return $filters->apply($builder);
    }
}

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

تمثيل العملاء وطلبياتهم كموارد متداخلة مع الحفاظ على اتساق الاستجابات وعناوين URL.

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

• app/Http/Controllers/Api/V1/CustomerOrdersController.php
• app/Http/Controllers/Api/V1/CustomersController.php
• app/Http/Resources/V1/OrderResource.php
• app/Http/Resources/V1/UserResource.php
• routes/api_v1.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?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;
use Illuminate\Http\Request;

class CustomerOrdersController extends Controller
{
    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

<?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

<?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->when(
                    $request->routeIs('orders.show'),
                    $this->notes
                ),
                'status' => $this->status,
                'createdAt' => $this->created_at,
                'updatedAt' => $this->updated_at
            ],
            'relationships' => [
                'customer' => [
                    'data' => [
                        'type' => 'user',
                        'id' => $this->user_id
                    ],
                    'links' => [
                        'self' => route('customers.show', ['customer' => $this->user_id])
                    ]
                ]
            ],
            'includes' => new UserResource($this->whenLoaded('customer')),
            'links' => [
                'self' => route('orders.show', ['order' => $this->id])
            ]
        ];
    }
}

app/Http/Resources/V1/UserResource.php

<?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('customers.*'), [
                    'emailVerifiedAt' => $this->email_verified_at,
                    'createdAt' => $this->created_at,
                    'updatedAt' => $this->updated_at,
                ])
            ],
            'includes' => OrderResource::collection($this->whenLoaded('orders')),
            'links' => [
                'self' => route('customers.show', ['customer' => $this->id])
            ]
        ];
    }
}

routes/api_v1.php

<?php

use App\Http\Controllers\Api\V1\OrderController;
use App\Http\Controllers\Api\V1\CustomersController;
use App\Http\Controllers\Api\V1\CustomerOrdersController;
use App\Http\Controllers\AuthController;
use App\Models\Order;
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!
|
*/

// http://localhost:8000/api/
// universal resource locator
// orders
// users

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



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

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

إضافة ترتيب آمن يتحكم به العميل من دون كشف أعمدة قاعدة البيانات عشوائياً في query string.

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

• app/Http/Controllers/Api/V1/CustomersController.php
• app/Http/Filters/V1/CustomerFilter.php
• app/Http/Filters/V1/QueryFilter.php
• app/Http/Filters/V1/OrderFilter.php
• app/Models/User.php

تعرض المقاطع التالية المحتوى الكامل للملفات، وليست أجزاء مختصرة من diff. لا نكرر ملفات Laravel المولدة التي لم تتغير في هذه المرحلة.

الكود الكامل

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

<?php

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;
use App\Http\Resources\V1\UserResource;

class CustomersController extends ApiController
{
    /**
     * Display a listing of the resource.
     */
    public function index(CustomerFilter $filters)
    {
        return UserResource::collection(User::filter($filters)->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/Filters/V1/CustomerFilter.php

<?php

namespace App\Http\Filters\V1;

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

    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);
    }

    public function include($value) {
        return $this->builder->with($value);
    }

    public function id($value) {
        return $this->builder->whereIn('id', explode(',', $value));
    }

    public function email($value) {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('email', 'like', $likeStr);
    }

    public function name($value) {
        $likeStr = str_replace('*', '%', $value);
        return $this->builder->where('name', 'like', $likeStr);
    }

    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);
    }

    
}