Download the PHP package savks/negotiator without Composer

Пакет використовується як альтернатива JSON-ресурсів Laravel. Перевагою даного пакету є строга типізація мапингу та вбудований інструмент для генерації TypeScript-типів.

Встановлення

Опис маперів

Для написання власного мапера потрібно створити клас який наслідує \Savks\Negotiator\Support\Mapping\Mapper. Приклад мапера:

Опис маперів не повинен містити імперативного коду, оскільки не можливо буде згенерувати типи. Це пов'язано з тим що при генерації відбувається імітація створення маперів для отримання інформації про типи, і якщо в описі буде присутній імперативний код, то це унеможливить роботу з ними.

NULL та не обов'язкові поля

Якщо поле може набувати значення null, його потрібно позначати як ->nullable(), оскільки через строгість типізації буде викинуто помилку. Якщо поле не обов'язкове, його можна позначити як ->optional() (бажано так робити для зменшення вихідного об'єму даних), в такому випадку якщо значення буде null то в кастах object та record це поле буде проігноровано.

Також для зменшення вихідного об'єму даних можна не обов'язковими робити не тільки 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 — звичайний масив типу — список. Працює на базі будь-якого ітеративного значення. Приклад:

• object — об'єкт зі статичними полями. Приклад:

• record — асоціативний масив/мапа, відрізняється від об'єкта тим, що базується на ітерованому значенні. Приклад:

Утилітарні типи

• mapper — дозволяє вказати як значенням інший мапер. Приклад:

Для правильно генерації типів, для TypeScript, у функції-резолвер мапера важливо вказувати сам мапер як тип що повертається, в іншому випадку значення набуватиму значення any.

• union — дозволяє вказати декілька можливих типів. Вказується як набір варіантів з умовами (умови не впливають на генерацію типів). Приклад:

• spread — дозволяє розкласти один об'єкт в інший. Приклад:

• typedField — дозволяє вказувати поле з типізованим ключем. Приклад:

• intersection — використовується для вказання перетнутих типів, зазвичай використовується якщо необхідно розширити інший мареп. Приклад:

• oneOfConst — дозволяє вказати, що значення може набувати одного з типів-констант. Приклад:

• scope — дозволяє прокалькулювати значення яке буде передано далі в мапинг. Приклад:

Генерація типів

Для генерації типів пакет містить клас генератора Savks\Negotiator\Support\TypeGeneration\Generator. Для роботи якого достатньо вказання для яких маперів і з якими просторами імен потрібно згенерувати код. Приклад використання:

Бувають випадки коли генератор не зможе створити мапер для отримання типів, через те що мапер в конструкторі отримує специфічні вхідні дані. В такому випадку необхідно реалізувати інтерфейс Savks\Negotiator\Support\Mapping\WithCustomMock з методом створення маперу з довільними даними.

Крайні випадки

1. Неможливо декларативно описати дані для мапера.

   Розв'язання цієї проблеми буде прокидка в каст кінцевих значень. Касти мають аксесор, це спосіб вказати звідки брати дані для роботи, він може бути анонімною функцією яка поверне кінцеве значення, в такому випадку в самому касті залишиться лише описати типи.