فيما يلي مثال خطوة بخطوة حول كيفية إنشاء كائنات نقل البيانات (DTOs) باستخدام Laravel Data:

1. تثبيت حزمة بيانات Laravel

للبدء، قم بتثبيت حزمة البيانات spatie/laravel باستخدام Composer. تساعد هذه الحزمة في إنشاء DTOs وإدارة البيانات بكفاءة.

composer require spatie/laravel-data

2. إنشاء كائن نقل البيانات (DTO)

بعد تثبيت الحزمة، يمكننا إنشاء فئة DTO للتعامل مع نقل البيانات. لنفترض أن لدينا كيان مستخدم، ونريد إنشاء DTO لنقل بيانات المستخدم.

قم بتشغيل الأمر Artisan التالي لإنشاء فئة DTO جديدة:

php artisan make:data UserData

سيؤدي هذا إلى إنشاء فئة UserData داخل دليل التطبيقات/البيانات.

3. تحديد الخصائص والأنواع في DTO

الآن، دعنا نقوم بتحرير فئة UserData لتحديد الخصائص وأنواع البيانات التي تتوقعها لـ DTO الخاص بك.

namespace App\Data;

use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public string $address,
        public ?string $phone = null  // Optional phone field
    ) {}
}

توضيح:

• تقوم طريقة __construct تلقائيًا بتعيين القيم الواردة إلى خصائص DTO.
• يشير ?string $phone = null إلى أن خاصية الهاتف اختيارية.

4. استخدام DTO في وحدة التحكم

الآن بعد إنشاء UserData DTO، يمكننا استخدامه داخل وحدة التحكم لدينا للتعامل مع البيانات الواردة، وتحويلها، وتمريرها بين طبقات التطبيق.

namespace App\Http\Controllers;

use App\Data\UserData;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request)
    {
        // Validate the incoming request data
        $validatedData = $request->validate([
            'name' => 'required|string',
            'email' => 'required|email',
            'address' => 'required|string',
            'phone' => 'nullable|string',
        ]);

        // Create a UserData DTO
        $userData = UserData::from($validatedData);

        // You can now access $userData->name, $userData->email, etc.
        User::create([
            'name' => $userData->name,
            'email' => $userData->email,
            'address' => $userData->address,
            'phone' => $userData->phone,
        ]);

        return response()->json(['message' => 'User created successfully']);
    }
}

توضيح:

• تقوم طريقة UserData::from() تلقائيًا بتعيين بيانات الطلب التي تم التحقق من صحتها في كائن DTO.
• يمكن الآن استخدام كائن DTO لنقل البيانات بين وحدة التحكم والنموذج (أو طبقات أخرى من التطبيق).

5. تحويل البيانات باستخدام DTO

يمكنك استخدام DTO لتحويل البيانات عند إرجاع الاستجابات أيضًا. دعونا نعدل طريقة العرض في UserController لإرجاع بيانات المستخدم من خلال DTO.

public function show(User $user)
{
    // Convert the User model to UserData DTO
    $userData = new UserData(
        name: $user->name,
        email: $user->email,
        address: $user->address,
        phone: $user->phone
    );

    return response()->json($userData);
}

توضيح:

• هنا، نقوم بإنشاء UserData DTO يدويًا عن طريق تمرير خصائص نموذج المستخدم إلى مُنشئ DTO.
• يمكن إرجاع DTO مباشرة كاستجابة JSON، مما يضمن تنسيق البيانات المنظمة.

6. DTO مع المجموعات

إذا كنت تعمل مع مجموعات من البيانات، مثل جلب قائمة المستخدمين، فإن حزمة DTO توفر طريقة بسيطة للتعامل مع المجموعات أيضًا.

public function index()
{
    $users = User::all();

    // Convert the collection of User models to a collection of UserData DTOs
    $userCollection = UserData::collection($users);

    return response()->json($userCollection);
}

توضيح:

• تقوم طريقة UserData::collection($users) بتعيين كل نموذج مستخدم إلى UserData DTO، مما يحول المجموعة بأكملها إلى قائمة DTOs.

7. تخصيص تحويل البيانات

تسمح حزمة بيانات spatie/laravel بتخصيص التحويل، على سبيل المثال، إعادة تسمية السمات أو إضافة حقول محسوبة.

class UserData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public string $address,
        public ?string $phone = null
    ) {}

    // Add a custom method to compute a full contact string
    public function fullContact(): string
    {
        return "{$this->name} ({$this->email})";
    }
}

الآن، يمكنك استخدام fullContact() للحصول على سلسلة منسقة مخصصة عند العمل مع DTO.

8. التحقق من صحة البيانات وعمليات DTO

يمكنك إضافة قواعد التحقق مباشرة في DTO باستخدام ميزة قواعد Laravel Data.

namespace App\Data;

use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        #[Required] public string $name,
        #[Email] public string $email,
        public string $address,
        public ?string $phone = null
    ) {}
}

توضيح:

• باستخدام سمات التحقق مثل #[مطلوب] و#[البريد الإلكتروني]، يمكنك فرض التحقق مباشرة على مستوى DTO، مما يؤدي إلى تبسيط العملية بشكل أكبر.

خاتمة

في هذا البرنامج التعليمي العملي، اكتشفنا كيفية إنشاء واستخدام كائنات نقل البيانات (DTOs) باستخدام Laravel Data. باستخدام نمط DTO، يمكنك إدارة بياناتك وتحويلها بشكل نظيف، مما يضمن فصل الاهتمامات بين طبقات التطبيق الخاص بك، مع تسهيل صيانة التعليمات البرمجية. تعمل حزمة البيانات المكانية/laravel على تبسيط إدارة DTO، مما يوفر ميزات سهلة الاستخدام لكل من المطورين والتطبيقات واسعة النطاق.