Download the PHP package troum/mycro-core without Composer

troum/mycro-core

Общая PHP-библиотека для микросервисов: типизированные DTO с гидратацией из массивов, интеграция с RabbitMQ и простой файловый логгер.

Требования: PHP ^8.4, php-amqplib/php-amqplib ^3.5

Пространство имён: Mycro\Core\

Установка

Пакет доступен на Packagist:

Рекомендуемый constraint — ^1.1. Версии отмечаются git-тегами (v1.1.0, v1.1.3 и т.д.):

DTO (BaseDto)

Базовый класс для immutable DTO. Свойства объявляются как public readonly — значения задаются один раз при создании из массива (например, из HTTP-запроса или сообщения очереди).

Минимальный пример

Правила гидратации

1. Обрабатываются только свойства с модификатором readonly.
2. Ключи входного массива приводятся к snake_case (firstName, first-name, first_name → first_name). Нормализуется только верхний уровень — вложенные массивы передаются в свойство как есть, вместе с исходными ключами.
3. Если значение не найдено и нет атрибута DefaultValue / необязательного MapProperty, выбрасывается DtoHydrationException.
4. Повторная инициализация уже заданного readonly-свойства запрещена (ReadonlyPropertyUpdateException).

Атрибут DefaultValue

Задаёт значение, если ключ отсутствует в данных:

Атрибут MapProperty

Сопоставляет свойство DTO с одним или несколькими ключами во входных данных (после нормализации в snake_case):

Порядок поиска значения: алиасы из from → имя свойства → DefaultValue → null (если required: false).

Атрибут Transform

Преобразует значение после разрешения маппера, до записи в свойство. Трансформер должен реализовать TransformerContract:

Частичное обновление: wasProvided() и providedAttributes()

toArray() возвращает все readonly-свойства, включая значения из DefaultValue и null от required: false. Для PATCH-запросов этого недостаточно: непонятно, что клиент прислал, а что подставила библиотека.

DTO запоминает, ключи каких свойств действительно присутствовали во входном массиве:

• явный null считается переданным значением — поле можно очистить;
• значение из #[DefaultValue] или #[MapProperty(required: false)] переданным не считается — оно не перезапишет данные в БД;
• свойство, найденное по алиасу #[MapProperty(from: 'other_name')], попадает в результат под именем свойства, а не алиаса;
• значения — уже после #[Transform], как и в toArray().

Для частичного обновления используйте providedAttributes() вместо array_filter($dto->toArray(), fn ($v) => $v !== null):

Для создания записи по-прежнему нужен toArray() — там значения по умолчанию как раз необходимы.

Кастомный PropertyMapper

По умолчанию используется DefaultPropertyMapper. Свой маппер подключается глобально для всех DTO:

Интерфейс PropertyMapperInterface::resolve() возвращает кортеж [bool $hasValue, mixed $value, bool $fromInput].

Третий элемент — позиционный и необязательный: маппер, возвращающий два элемента, продолжает работать, но wasProvided() и providedAttributes() для его DTO всегда будут пустыми. Возвращайте true только тогда, когда значение действительно взято из входного массива:

Проверяйте наличие ключа через array_key_exists(), а не isset() — иначе явный null не будет считаться переданным.

RabbitMQ

RabbitMQService

Подключение, публикация и потребление сообщений (JSON в теле, durable exchange/queue).

Поведение consumer:

• no_ack = false — ручное подтверждение;
• при успехе — ack();
• при ошибке — лог через CoreLoggerInterface::error(), nack(requeue: true).

RabbitMQConsumer

Тонкая обёртка над consume():

RabbitMQPublisherInterface

Интерфейс только для публикации — удобно для DI и моков в тестах:

Логирование

CoreLoggerInterface

Используется в RabbitMQ consumer. В Laravel-сервисе можно зарегистрировать адаптер к Log::channel().

FileCoreLogger

Запись в файл с меткой времени. По умолчанию: {package}/logs/core.log (каталог создаётся автоматически).

Исключения

Структура пакета

Тесты

Лицензия

MIT