تنزيل data transfer object - تنزيل رمز مصدر data transfer object

data transfer object

فئات أخرى

3.9.1

تنزيل

تحذير لقد قررنا التوقف عن صيانة هذه الحزمة.
فكر في الترحيل إلى بيانات spatie/laravel أو cuyz/valinor.
لا تتردد في تفرع الكود الخاص بنا وتكييفه ليناسب احتياجاتك.

كائنات نقل البيانات مع البطاريات المضمنة

تثبيت

يمكنك تثبيت الحزمة عبر الملحن:

 يتطلب الملحن كائنًا/كائنًا لنقل البيانات

ملاحظة : الإصدار 3 من هذه الحزمة يدعم فقط php:^8.0 . إذا كنت تبحث عن الإصدار الأقدم، فراجع الإصدار 2.

ادعمنا

نحن نستثمر الكثير من الموارد في إنشاء أفضل الحزم مفتوحة المصدر في فئتها. يمكنك دعمنا عن طريق شراء أحد منتجاتنا المدفوعة.

نحن نقدر بشدة إرسالك لنا بطاقة بريدية من مسقط رأسك، مع ذكر الحزمة (الحزم) التي تستخدمها. ستجد عنواننا على صفحة الاتصال لدينا. ننشر جميع البطاقات البريدية المستلمة على جدار البطاقات البريدية الافتراضية لدينا.

الاستخدام

الهدف من هذه الحزمة هو جعل إنشاء الكائنات من صفائف البيانات (المتسلسلة) أمرًا سهلاً قدر الإمكان. إليك ما يبدو عليه DTO:

 استخدام SpatieDataTransferObjectAttributesMapFrom؛استخدام SpatieDataTransferObjectDataTransferObject؛فئة MyDTO توسع DataTransferObject
{عامة أخرىDTO $otherDTO؛    العامة OtherDTOCollection $collection؛

        #[CastWith(ComplexObjectCaster::class)]public ComplexObject $complexObject;    public ComplexObjectWithCast $complexObjectWithCast;

        #[NumberBetween(1, 100)]public int $a;

        #[MapFrom('address.city')]سلسلة عامة $city;
}

يمكنك إنشاء DTO مثل هذا:

 $dto = MyDTO الجديد(
    ج: 5،
    مجموعة: [
        ['المعرف' => 1]،
        ['المعرف' => 2]،
        ['المعرف' => 3]،
    ]،
    كائن معقد: ['name' => 'اختبار'،
    ]،
    complexObjectWithCast: ['name' => 'test'،
    ]،
    أخرىDTO: ['id' => 5]،
);

دعونا نناقش كل الاحتمالات واحدا تلو الآخر.

الحجج المسماة

يمكن إنشاء DTO باستخدام الوسائط المسماة. من الممكن أيضًا الاستمرار في استخدام تدوين المصفوفة القديم. هذا المثال يعادل المثال أعلاه.

 $dto = new MyDTO(['a' => 5,'collection' => [
        ['المعرف' => 1]،
        ['المعرف' => 2]،
        ['المعرف' => 3]،
    ],'complexObject' => ['name' => 'اختبار',
    ],'complexObjectWithCast' => ['name' => 'test',
    ],'otherDTO' => ['id' => 5],
]);

يلقي القيمة

إذا كان DTO يحتوي على خاصية تمثل DTO أخرى أو مجموعة DTO، فستهتم الحزمة بإرسال صفائف البيانات تلقائيًا إلى DTOs:

 $dto = MyDTO الجديد(
    المجموعة: [ // سيصبح هذا كائنًا من فئة OtherDTOCollection['id' => 1],
        ['id' => 2], // سيكون كل عنصر بمثابة مثيل لـ OtherDTO['id' => 3],
    ]،
    otherDTO: ['id' => 5], // سيتم إرسال هذه البيانات إلى OtherDTO);

عجلات مخصصة

يمكنك إنشاء فئات العجلات الخاصة بك، والتي ستأخذ أي مدخلات يتم تقديمها لها، وسترسل تلك المدخلات إلى النتيجة المرجوة.

ألق نظرة على ComplexObject :

 كائن معقد فئة
{سلسلة عامة اسم $؛
}

وعجلتها ComplexObjectCaster :

 استخدم SpatieDataTransferObjectCaster؛ فئة ComplexObjectCaster تنفذ Caster
{/** * @param array|قيمة $mixed * * @returnmixed */public function cast(mixed $value): ComplexObject{return new ComplexObject(
            الاسم: $value['name']
        );
    }
}

عجلات خاصة بفئة معينة

بدلًا من تحديد العجلة التي يجب استخدامها لكل خاصية، يمكنك أيضًا تحديد العجلة على الفئة المستهدفة نفسها:

 تقوم فئة MyDTO بتوسيع DataTransferObject
{عامة ComplexObjectWithCast $complexObjectWithCast;
}

 #[CastWith(ComplexObjectWithCastCaster::class)]فئة ComplexObjectWithCast
{سلسلة عامة اسم $؛
}

العجلات الافتراضية

من الممكن تحديد العجلات الافتراضية في فئة DTO نفسها. سيتم استخدام هذه العجلات عند مواجهة خاصية من نوع معين داخل فئة DTO.

 #[
    DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
    DefaultCast(MyEnum::class, EnumCaster::class),
] فئة مجردة BaseDataTransferObject تمتد DataTransferObject
{حالة MyEnum $ العامة؛ // سيتم استخدام EnumCasterpublic DateTimeImmutable $date; // سيتم استخدام DateTimeImmutableCaster}

استخدام وسائط العجلات المخصصة

يمكن لأي عجلة تمرير وسائط مخصصة، ويعد تنفيذ ArrayCaster المدمج مثالًا جيدًا لكيفية استخدام ذلك.

سيساعد استخدام الوسيطات المسماة عند تمرير الإدخال إلى المستخدم في جعل التعليمات البرمجية الخاصة بك أكثر وضوحًا، ولكنها ليست مطلوبة.

على سبيل المثال:

    /** @var SpatieDataTransferObjectTestsFoo[] */#[CastWith(ArrayCaster::class, itemType: Foo::class)]مصفوفة عامة $collectionWithNamedArguments;    /** @var SpatieDataTransferObjectTestsFoo[] */#[CastWith(ArrayCaster::class, Foo::class)]مصفوفة عامة $collectionWithoutNamedArguments;

لاحظ أن الوسيطة الأولى التي تم تمريرها إلى مُنشئ الإرسال هي دائمًا المصفوفة التي تحتوي على نوع (أنواع) القيمة التي يتم إرسالها. ستكون كافة الوسائط الأخرى هي تلك التي تم تمريرها كوسائط إضافية في سمة CastWith .

تصديق

لا توفر هذه الحزمة أي وظيفة تحقق محددة، ولكنها توفر لك طريقة لبناء سمات التحقق الخاصة بك. على سبيل المثال، NumberBetween هو سمة تحقق ينفذها المستخدم:

 تقوم فئة MyDTO بتوسيع DataTransferObject
{
    #[NumberBetween(1, 100)]public int $a;
}

يعمل مثل هذا تحت غطاء محرك السيارة:

 #[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]class NumberBetween يطبق أداة التحقق
{وظيفة عامة __construct(int خاص $min,private int $max) {
    } public function validate(mixed $value): ValidationResult{if ($value < $this->min) {return ValidationResult::invalid("يجب أن تكون القيمة أكبر من أو تساوي {$this->min}");
        }if ($value > $this->max) {return ValidationResult::invalid("يجب أن تكون القيمة أقل من أو تساوي {$this->max}");
        }return ValidationResult::valid();
    }
}

رسم الخرائط

يمكنك تعيين خاصية DTO من خاصية مصدر باسم مختلف باستخدام السمة #[MapFrom] .

إنه يعمل مع اسم خاصية التدوين "النقطة" أو الفهرس.

 تقوم فئة PostDTO بتوسيع DataTransferObject
{
    #[MapFrom('postTitle')]سلسلة عامة $title;

        #[MapFrom('user.name')]سلسلة عامة $author;
}$dto = new PostDTO(['postTitle' => 'مرحبًا بالعالم','user' => ['name' => 'John Doe']
]);

 تقوم فئة UserDTO بتوسيع DataTransferObject
{

    #[MapFrom(0)]سلسلة عامة $firstName;

        #[MapFrom(1)]سلسلة عامة $lastName;
}$dto = new UserDTO(['John', 'Doe']);

في بعض الأحيان تريد أيضًا تعيينها أثناء التحويل إلى Array. حالة الاستخدام النموذجية هي التحول من حالة الجمل إلى حالة الثعبان. لذلك يمكنك استخدام السمة #[MapTo] .

 تقوم فئة UserDTO بتوسيع DataTransferObject
{

    #[ماب فروم (0)]
    #[MapTo('first_name')]سلسلة عامة $firstName;

        #[خريطة من (1)]
    #[MapTo('last_name')]سلسلة عامة $lastName;
}$dto = new UserDTO(['John', 'Doe']);$dto->toArray() // ['first_name' => 'John', 'last_name'=> 'Doe'];$dto- >only('first_name')->toArray() // ['first_name' => 'John'];

أوامر DTO الصارمة

أضاف الإصدار السابق من هذه الحزمة فئة FlexibleDataTransferObject والتي سمحت لك بتجاهل الخصائص التي لم تكن موجودة في DTO. لقد تم تغيير هذا السلوك، وأصبحت جميع عناصر DTO مرنة الآن بشكل افتراضي، ولكن يمكنك جعلها صارمة باستخدام السمة #[Strict] :

 تقوم فئة NonStrictDto بتوسيع DataTransferObject
{سلسلة عامة اسم $؛
}// يعمل هذا على NonStrictDto(
    الاسم: "الاسم"،
    غير معروف: 'غير معروف')؛

 استخدم SpatieDataTransferObjectAttributesStrict؛

#[Strict] فئة StrictDto توسع DataTransferObject
{سلسلة عامة اسم $؛
}// يؤدي هذا إلى ظهور استثناء SpatieDataTransferObjectExceptionsUnknownPropertiesnew StrictDto(
    الاسم: "الاسم"،
    غير معروف: 'غير معروف')؛

وظائف المساعدة

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

 $postData->all();$postData->فقط('title', 'body')
    ->toArray();
    $postData->باستثناء('المؤلف')
    ->toArray();

لاحظ أن all() ‎ ستعيد ببساطة جميع الخصائص، بينما toArray() ‎ ستعيد كائنات DTO المتداخلة إلى المصفوفات أيضًا.

يمكنك ربط التابعين except() و only() :

 $postData->باستثناء('العنوان')
    -> باستثناء ("الجسم")
    ->toArray();

من المهم ملاحظة أن except() و only() غير قابلة للتغيير، ولن تغير كائن نقل البيانات الأصلي.

DTOs غير قابل للتغيير والاستنساخ

لا تفرض هذه الحزمة كائنات غير قابلة للتغيير نظرًا لأن PHP لا تدعمها، ولكن ننصحك دائمًا بالحفاظ على DTOs الخاصة بك غير قابلة للتغيير. لمساعدتك، هناك طريقة clone في كل DTO تقبل البيانات لتجاوزها:

 $clone = $original->clone(other: ['name' => 'a']);

لاحظ أنه لم يتم تغيير أي بيانات في $original .

مجموعات من DTOs

يزيل هذا الإصدار فئة DataTransferObjectCollection . بدلاً من ذلك، يمكنك استخدام عجلات بسيطة وفئات التجميع الخاصة بك.

فيما يلي مثال على إرسال مجموعة من DTOs إلى مجموعة من DTOs:

 يمتد شريط الفئة DataTransferObject
{/** @var SpatieDataTransferObjectTestsFoo[] */#[CastWith(FooArrayCaster::class)]public array $collectionOfFoo;
}يمتد class Foo إلى DataTransferObject
{سلسلة عامة اسم $؛
}

 تقوم فئة FooArrayCaster بتنفيذ Caster
{وظيفة عامة cast(mixed $value): array{if (! is_array($value)) {throw new Exception("يمكن إرسال المصفوفات إلى Foo فقط");
        }return array_map(fn (array $data) => new Foo(...$data),$value);
    }
}

إذا كنت لا تريد تلميح الكتابة المتكرر، أو تريد وظيفة المجموعة الموسعة؛ يمكنك إنشاء فئات المجموعة الخاصة بك باستخدام أي تطبيق للمجموعة. في هذا المثال، نستخدم Laravel:

 يمتد شريط الفئة DataTransferObject
{
    #[CastWith(FooCollectionCaster::class)]public CollectionOfFoo $collectionOfFoo;
}يمتد class Foo إلى DataTransferObject
{سلسلة عامة اسم $؛
}

 استخدم IlluminateSupportCollection;class CollectionOfFoo يمتد المجموعة
{// أضف نوع الإرجاع الصحيح هنا للمحللين الثابتين لمعرفة نوع المصفوفة التي تعد وظيفة عامة OffsetGet($key): Foo{returnparent::offsetGet($key);
    }
}

 تقوم فئة FooCollectionCaster بتنفيذ Caster
{public function cast(mixed $value): CollectionOfFoo{return new CollectionOfFoo(array_map(fn (array $data) => new Foo(...$data),$value));
    }
}

صفائف بسيطة من DTOs

بالنسبة لمصفوفة بسيطة من DTOs، أو كائن ينفذ ArrayAccess المدمج في PHP، فكر في استخدام ArrayCaster الذي يتطلب توفير نوع العنصر:

 يمتد شريط الفئة DataTransferObject
{/** @var SpatieDataTransferObjectTestsFoo[] */#[CastWith(ArrayCaster::class, itemType: Foo::class)]مصفوفة عامة $collectionOfFoo;
}

اختبار

 اختبار الملحن

سجل التغيير

الرجاء مراجعة سجل التغيير للحصول على مزيد من المعلومات حول ما تغير مؤخرًا.

المساهمة

يرجى الاطلاع على المساهمة للحصول على التفاصيل.

حماية

إذا وجدت خطأً يتعلق بالأمان، فيرجى إرسال بريد إلكتروني إلى العنوان [email protected] بدلاً من استخدام أداة تعقب المشكلات.

البطاقات البريدية

أنت حر في استخدام هذه الحزمة، ولكن إذا وصلت إلى بيئة الإنتاج الخاصة بك، فإننا نقدر بشدة إرسالك لنا بطاقة بريدية من مسقط رأسك، مع ذكر الحزمة (الحزم) التي تستخدمها.

عنواننا هو: سباتي، كرويكسترات 22، 2018 أنتويرب، بلجيكا.

ننشر جميع البطاقات البريدية المستلمة على موقع شركتنا.

أدوات خارجية

json2dto: واجهة المستخدم الرسومية لتحويل كائنات JSON إلى فئات DTO (مع دعم التداخل). يوفر أيضًا أداة CLI للاستخدام المحلي.
مصنع كائنات نقل البيانات: يقوم بإنشاء مثيل DTO بذكاء باستخدام المحتوى الصحيح لخصائصك بناءً على اسمه ونوعه.