DevCraft Документации

Начало работы 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*наследовать AbstractWithprivate или protected, не static, не readonly
Ответ/запрос API, заполнение из массива, JSON наружунаследовать AbstractReflectionpublic, с типами
Кэш на диске по PSR-6создать FileCachePool (наследование не нужно)

Требования

ЧтоМинимум
PHP8.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
Маппер по reflectionfromArray / toArray, вложенные DTO, ArrayOf
ВалидацияFilter, Range, Regex, исключения

Разделы документации

Дальше

  1. Установить пакет в проект.
  2. Выбрать базовый класс по таблице выше и пройти нужное руководство.
  3. Смотреть сигнатуры в справочнике.

На этой странице