Начало работы v1.1.0
Что такое DevCraft Dev Tools: описание, возможности, для кого, выбор базового класса и быстрый старт.
Описание пакета
DevCraft Dev Tools (devcraftclub/dev-tools) — небольшая библиотека на PHP 8.3 для типовых задач в коде продуктов DevCraft и любых PHP-проектов: собрать объект «по цепочке», принять массив с API и проверить поля, положить значение в файловый кэш по стандарту PSR-6.
Вместо того чтобы в каждом модуле писать свои setX/getX, ручной разбор массивов и самодельный кэш на файлах, вы берёте готовые базовые классы и атрибуты. Пакет ставится через Composer; отдельного плагина DLE или экрана в админке у него нет — это зависимость для разработчика.
Версия 1.1.0 добавляет файловый пул кэша (FileCachePool) поверх уже знакомых цепочек with* и DTO на AbstractReflection. Линейка 1.x совместима с PHP 8.3+.
Возможности
- Цепочки
with*для скрытых свойств: атрибуты#[With]и#[WithItem]на наследникеAbstractWith. - Чтение и запись через
get*/set*/is*— атрибуты#[Getter]/#[Setter]из пакета lombok-php (подключены черезAbstractWith). - DTO с публичными типизированными свойствами:
fromArray(),toArray(),toJson()наAbstractReflection. - Проверка полей атрибутами:
Filter,Range,Regex,ArrayOf. - Файловый кэш по PSR-6:
FileCachePool, ключи с «папками» (Translation/dict), очистка префиксаclearNamespace()(расширение пакета, не часть PSR-6). - Общая точка в DevCraft Admin: тонкая обёртка
CacheControlповерх того же пула.
Для кого
Разработчики модулей и сервисов
Вы пишете сущности запросов, ответы API, настройки и кэш переводов. Подключаете пакет Composer’ом и наследуете нужный базовый класс — или создаёте FileCachePool как обычный объект. Каркас админки DLE и DevCraft Admin здесь ни при чём: Dev Tools живёт в vendor и вызывается из вашего PHP.
Документация для кода: Руководства, справочник. В экосистеме DLE пакет уже тянет DevCraft Admin — отдельно ставить Dev Tools на сайт обычно не нужно.
Владельцы сайта / админы панели
Этот раздел документации вам почти не нужен: на сайте вы ставите DevCraft Admin и сателлиты. Dev Tools приедет как зависимость Composer внутри devcraft/. Менять код библиотеки не требуется.
Почему не «свой» набор хелперов
Свой withFoo на каждом классе, ручной foreach по массиву API и кэш через file_put_contents быстро расходятся между модулями: разные имена методов, разная проверка типов, разный формат файлов. Dev Tools даёт один контракт: атрибуты + два базовых класса + один PSR-6 пул. В DevCraft Admin кэш уже сидит на FileCachePool — ваш сателлит может пользоваться тем же механизмом, а не третьей самоделкой.
Два базовых класса нельзя склеить наследованием: у AbstractWith свойства скрытые (private/protected), у AbstractReflection — публичные. Нужны оба стиля — два класса рядом или композиция.
Архитектура
Три независимых блока; в проекте берут один или несколько.
Цепочки with* DTO из массива Кэш PSR-6
───────────── ────────────── ────────
#[With] / #[WithItem] public-свойства с типами FileCachePool
#[Getter] / #[Setter] (lombok-php) │ │
│ ▼ ▼
▼ AbstractReflection {каталог}/{ключ}.cache
AbstractWith ──__call──► WithHandler │ JSON-запись {e,f,v}
│ (сначала with*) ▼
└──parent──► Lombok\Helper ReflectionMapper
(get* / set* / is*) │
▼
PropertyValidator
│
Filter / Range / Regex / ArrayOfВыбор базового класса
| Задача | Что брать | Свойства |
|---|---|---|
Объект-запрос, билдер, цепочка with* плюс get* / set* | наследовать AbstractWith | private или protected, не static, не readonly |
| Ответ/запрос API, заполнение из массива, JSON наружу | наследовать AbstractReflection | public, с типами |
| Кэш на диске по PSR-6 | создать FileCachePool (наследование не нужно) | — |
Требования
| Что | Минимум |
|---|---|
| PHP | 8.3+ |
| Composer | да |
psr/cache | ^3.0 (ставится с пакетом) |
marcin-orlowski/lombok-php | ^1.2 (для get* / set* на AbstractWith) |
Подробнее: Установка.
Быстрый старт
1. Кэш на файлах
use Devcraft\Cache\FileCachePool;
$pool = new FileCachePool('/path/to/cache', defaultTtlSeconds: 3600);
$item = $pool->getItem('Translation/dict');
$item->set(['hello' => 'world']);
$pool->save($item);
$hit = $pool->getItem('Translation/dict');
if ($hit->isHit()) {
$value = $hit->get();
}
$pool->clearNamespace('Translation'); // расширение Dev Tools (не из PSR-6)2. Цепочка with*
use Lombok\Getter;
use Devcraft\Abstracts\AbstractWith;
use Devcraft\Attributes\With;
use Devcraft\Attributes\WithItem;
#[Getter]
final class Query extends AbstractWith
{
#[With]
private ?int $page = null;
#[With, WithItem('string')]
private array $tags = [];
#[WithItem('string', ['string', 'null'])]
private array $labels = [];
}
$query = (new Query())
->withPage(1)
->withTagsItem('proxy')
->withLabelsItem('status', 'ready');
$query->getPage(); // 1
$query->getTags(); // ['proxy']
$query->getLabels(); // ['status' => 'ready']3. DTO из массива
use Devcraft\Abstracts\AbstractReflection;
use Devcraft\Attributes\ArrayOf;
use Devcraft\Attributes\Range;
use Devcraft\Attributes\Regex;
final class Address extends AbstractReflection
{
public string $city;
}
final class Proxy extends AbstractReflection
{
#[Regex('/^[0-9a-f-]{36}$/i')]
public string $id;
#[Range(min: 1, max: 65535)]
public int $port;
public Address $address;
#[ArrayOf(Address::class)]
public array $locations = [];
}
$proxy = Proxy::fromArray([
'id' => '550e8400-e29b-41d4-a716-446655440000',
'port' => '8080',
'address' => ['city' => 'Berlin'],
'locations' => [
['city' => 'Berlin'],
['city' => 'Paris'],
],
]);
$proxy->port; // int 8080 (string coerced)
$proxy->address->city; // 'Berlin'
$proxy->toArray(); // nested arrays
echo $proxy->toJson(); // pretty-printed JSONРуководства (подробнее)
| Руководство | О чём |
|---|---|
| Файловый кэш PSR-6 | Пул, ключи, TTL, очистка префикса, формат на диске |
| Атрибуты With | #[With], #[WithItem], правила типов и ошибки |
| Getter и Setter | Как lombok-php стыкуется с AbstractWith |
| Маппер по reflection | fromArray / toArray, вложенные DTO, ArrayOf |
| Валидация | Filter, Range, Regex, исключения |
Разделы документации
Установка
Packagist и локальный path repository
Руководства
Кэш, With, accessors, DTO, валидация
Справочник API
Классы, атрибуты, исключения
История изменений
Что нового в 1.1.0
English
Full English documentation
Дальше
- Установить пакет в проект.
- Выбрать базовый класс по таблице выше и пройти нужное руководство.
- Смотреть сигнатуры в справочнике.