Пакет використовується як альтернатива JSON-ресурсів Laravel. Перевагою даного пакету є строга типізація мапингу та вбудований інструмент для генерації TypeScript-типів.
composer require savks/negotiator
Для написання власного мапера потрібно створити клас який наслідує \Savks\Negotiator\Support\Mapping\Mapper
. Приклад
мапера:
<?php
namespace App\Http\Mapping;
use App\Models\User;
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Mapper,
Schema
};
final class UserMapper extends Mapper
{
public function __construct(public readonly User $user)
{
}
public static function schema(): Cast
{
return Schema::object([
'id' => Schema::string('id'),
'firstName' => Schema::string('first_name'),
'lastName' => Schema::string('last_name')->nullable(),
], 'user');
}
}
Опис маперів не повинен містити імперативного коду, оскільки не можливо буде згенерувати типи. Це пов'язано з тим що при генерації відбувається імітація створення маперів для отримання інформації про типи, і якщо в описі буде присутній імперативний код, то це унеможливить роботу з ними.
Якщо поле може набувати значення null
, його потрібно позначати як ->nullable()
, оскільки через строгість типізації
буде викинуто помилку. Якщо поле не обов'язкове, його можна позначити як ->optional()
(бажано так робити для
зменшення вихідного об'єму даних), в такому випадку якщо значення буде null
то в кастах object
та keyedArray
це
поле буде проігноровано.
Також для зменшення вихідного об'єму даних можна не обов'язковими робити не тільки
null
. Для цого є допоміжний метод->optionalIfFalse()
вboolean
, або->optionalIfEmpty()
в типахstring
таarray
. Для більш гнучкого налаштування потрібно використовувати аргументи методу->optional()
.
В крайніх випадках може виникнути необхідність вказати
optional
тільки для типу, при тому зберігши перевірку типів при мапингу. В такому випадку потрібно використовувати методи->maybeOptional()
або->maybeNullable()
.
string
,boolean
,number
— примітиви.constString
,constBoolean
,constNumber
— статичні типи. Відрізняються тим, що значення встановлюється явно. Також, можуть виступати як літерали (статичних значень).anyObject
— дозволяє описати об'єкти опускаючи опис його полів (в TypeScript — цеRecord<string, any>
).enum
— значення перерахування.null
— визначає значення як NULL.any
— будь-яке значення (аналогічне такому в TypeScript).
array
— звичайний масив типу — список. Працює на базі будь-якого ітеративного значення. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'items' => Schema::array(
Schema::anyObject(),
'items'
),
]);
object
— об'єкт зі статичними полями. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'field' => Schema::string('field'),
]);
keyedArray
— асоціативний масив/мапа, відрізняється від об'єкта тим, що базується на ітерованому значенні. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'items' => Schema::keyedArray(
Schema::anyObject(),
'items'
),
]);
mapper
— дозволяє вказати як значенням інший мапер. Приклад:
<?php
use App\Models\User;
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'user' => Schema::mapper(
fn (User $user): UserMapper => new UserMapper($user),
'user'
),
]);
Schema::object([
'user' => Schema::mapper(UserMapper::class, 'user'),
]);
Для правильно генерації типів, для TypeScript, у функції-резолвер мапера важливо вказувати сам мапер як тип що повертається, в іншому випадку значення набуватиму значення
any
.
union
— дозволяє вказати декілька можливих типів. Вказується як набір варіантів з умовами (умови не впливають на генерацію типів). Приклад:
<?php
use App\Models\User;
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'field' => Schema::union()
->variant(
fn (User $user) => $user->role === 'admin',
Schema::object([
'field' => Schema::string('field'),
])
)
->variant(
['role', 'guest'],
Schema::object([
'field' => Schema::string('field'),
])
)
->default(
Schema::object([
'field' => Schema::string('field'),
])
),
]);
spread
— дозволяє розкласти один об'єкт в інший. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\Schema;
use Savks\Negotiator\Support\Mapping\Casts\{
ObjectUtils\Spread,
Cast
};
Schema::object([
'field' => Schema::string('field'),
new Spread([
'otherField' => Schema::string('other_field')
], 'accessor'),
]);
typedField
— дозволяє вказувати поле з типізованим ключем. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\Schema;
use Savks\Negotiator\Support\Mapping\Casts\{
ObjectUtils\TypedField,
Cast
};
Schema::object([
'field' => Schema::string('field'),
new TypedField(SomeEnum::CASE, [
'otherField' => Schema::string('other_field')
]),
]);
intersection
— використовується для вказання перетнутих типів, зазвичай використовується якщо необхідно розширити інший мареп. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'field' => Schema::intersection(
Schema::mapper(UserMapper::class, 'user'),
Schema::object([
'otherField' => Schema::string('other_field')
], 'user'),
),
]);
oneOfConst
— дозволяє вказати, що значення може набувати одного з типів-констант. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'field' => Schema::oneOfConst([
Schema::constNumber(1),
Schema::constNumber(2),
Schema::constNumber(3),
]),
]);
scope
— дозволяє прокалькулювати значення яке буде передано далі в мапинг. Приклад:
<?php
use Savks\Negotiator\Support\Mapping\{
Casts\Cast,
Schema
};
Schema::object([
'field' => Schema::scope(
Schema::oneOfConst([
Schema::constNumber(1),
Schema::constNumber(2),
Schema::constNumber(3),
]),
fn (array $data) => $data['value']
),
]);
Для генерації типів пакет містить клас генератора Savks\Negotiator\Support\TypeGeneration\Generator
. Для роботи якого
достатньо вказання для яких маперів і з якими просторами імен потрібно згенерувати код. Приклад використання:
<?php
use App\Http\Mapping\UserMapper;
use Savks\Negotiator\Enums\RefTypes;
use Illuminate\Support\Str;
use Savks\Negotiator\Support\TypeGeneration\TypeScript\{
Generator,
Target
};
$generator = new Generator(
/* Функція для визначення референсів. */
fn (RefTypes $type, string $target) => match ($type) {
RefTypes::ENUM => sprintf(
'import(\'@enums\').%s',
class_basename($target::class)
),
RefTypes::MAPPER => sprintf(
'import(\'@dto\').%s',
class_basename($target::class)
),
}
);
$generator->addTarget(
new Target(UserMapper::class, '@dto')
);
$generator->saveTo('./path_to_file.ts');
Бувають випадки коли генератор не зможе створити мапер для отримання типів, через те що мапер в конструкторі отримує специфічні вхідні дані. В такому випадку необхідно реалізувати інтерфейс
Savks\Negotiator\Support\Mapping\WithCustomMock
з методом створення маперу з довільними даними.
-
Неможливо декларативно описати дані для мапера.
Розв'язання цієї проблеми буде прокидка в каст кінцевих значень. Касти мають аксесор, це спосіб вказати звідки брати дані для роботи, він може бути анонімною функцією яка поверне кінцеве значення, в такому випадку в самому касті залишиться лише описати типи.