README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Cache

Кэш для PHP 8.1+ с PSR-16 (SimpleCache) и PSR-6 (CacheItemPool) из одного пакета: бэкенды «в памяти» и файловый (атомарная запись), инъектируемые часы (PSR-20) для детерминированного TTL в тестах. Нулевые тяжёлые зависимости.

Установка

composer require cloud-castle/cache

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Cache\Cache;

// PSR-16 (SimpleCache) в памяти.
$cache = Cache::array();
$cache->set('user:42', $user, 3600);        // на час
$user = $cache->get('user:42', $default);    // значение или умолчание при промахе

// PSR-16 файловый кэш с атомарной записью (temp + rename).
$cache = Cache::file('/var/cache/app');

// PSR-6 (CacheItemPool) с отложенным сохранением.
$pool = Cache::filePool('/var/cache/app');
$item = $pool->getItem('report');
if (!$item->isHit()) {
    $item->set($report)->expiresAfter(600);
    $pool->save($item);
}

// Детерминированный TTL в тестах — подмените системные часы на mock/frozen.
$cache = Cache::array($mockClock);

Возможности

PSR-16 (SimpleCache) и PSR-6 (CacheItemPool) из одного пакета над общим бэкендом.
Бэкенды: ArrayStore (в памяти) и FileStore (файлы с атомарной записью через cloud-castle/file-system — никаких частично записанных файлов).
Инъектируемые часы (PSR-20): истечение TTL детерминировано в тестах — «перематывайте» время FrozenClock/MockClock без реального ожидания.
Корректный null: попадание в кэш null отличается от промаха.
Валидация ключей по требованиям PSR (запрет символов {}()/\@:).
Нулевые тяжёлые зависимости — только PSR-контракты и cloud-castle/clock, cloud-castle/file-system.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	symfony	scrapbook	illuminate	phpfastcache	array¹
PSR-16 (SimpleCache) из коробки	✅	✅	✅	✅	✅	❌
PSR-6 (CacheItemPool) из коробки	✅	✅	✅	❌	✅	❌
Инъектируемые часы (PSR-20) — детерминированный TTL в тестах	✅	❌	❌	❌	❌	❌
Атомарная файловая запись (без битых кэш-файлов)	✅	✅	❌	❌	❌	❌
Нулевые тяжёлые зависимости (только PSR + clock/file-system)	✅	❌	✅	❌	❌	✅
Всего	🏆 5	3	3	1	2	1

2. Безопасность и корректность

Свойство	🏆 CloudCastle	symfony	scrapbook	illuminate	phpfastcache	array¹
Валидация ключей по PSR (запрет {}()/\@:)	✅	✅	✅	✅	✅	❌
Корректное хранение null (отличается от промаха)	✅	✅	✅	✅	✅	❌
Атомарная запись файлов (нет частичных данных)	✅	✅	❌	❌	❌	❌
Детерминированное истечение TTL (инъектируемые часы)	✅	❌	❌	❌	❌	❌
Устойчивость к битым кэш-файлам (промах вместо падения)	✅	✅	✅	❌	✅	❌
Всего	🏆 5	4	3	2	3	0

3. Производительность

set + get в кэше «в памяти», 200 000 раз (минимум из 4).

Решение	Время (мс)	Итог
array¹	9	базовый уровень (не библиотека)
🏆 CloudCastle	110,1	быстрейшее среди библиотек
illuminate	146,4	аналог
scrapbook	382,2	аналог
symfony	798,1	аналог
phpfastcache	1 096,8	аналог

4. Потребление памяти

Пик памяти на 200 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	7 024	легчайшее среди библиотек
symfony	7 024	аналог
scrapbook	7 024	аналог
illuminate	7 024	аналог
array¹	7 024	базовый уровень (не библиотека)
phpfastcache	7 258	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Вывод: CloudCastle Cache — самый быстрый среди PSR-16 библиотек и самый лёгкий по памяти, единственный дающий PSR-16 + PSR-6 с инъектируемыми часами (тестируемый TTL) и атомарной файловой записью при нулевых тяжёлых зависимостях.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

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

Репозиторий: https://gitverse.ru/cloud-castle/cache
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия