PHPackages                             omegaalfa/cache - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. omegaalfa/cache

ActiveLibrary

omegaalfa/cache
===============

Explicit, predictable PSR-6 and PSR-16 cache stores for PHP 8.4.

v1.0.0(yesterday)00MITPHPPHP ^8.4CI failing

Since Jul 27Pushed yesterdayCompare

[ Source](https://github.com/omegaalfa/cache)[ Packagist](https://packagist.org/packages/omegaalfa/cache)[ RSS](/packages/omegaalfa-cache/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (8)Versions (2)Used By (0)

Omegaalfa Cache
===============

[](#omegaalfa-cache)

> Cache previsível para PHP 8.4, compatível com PSR-6 e PSR-16.

📚 O que é cache?
----------------

[](#-o-que-é-cache)

Cache é uma cópia temporária de algo caro de obter: uma consulta, API, relatório ou HTML. Um **hit** ocorre quando a chave existe; um **miss**, quando não existe ou expirou. **TTL** é seu tempo de vida. **Backend/Store** é onde os dados ficam; **driver** seleciona esse backend; **namespace** separa aplicações; **serializer** converte valores PHP para armazenamento. PSR-6 e PSR-16 são padrões PHP-FIG para APIs interoperáveis.

Important

Cache não é a fonte oficial. A aplicação deve continuar correta sem ele.

Use-o em operações repetidas e lentas. Evite-o quando o dado não pode ficar desatualizado ou a operação já é barata.

⚡ Recursos
----------

[](#-recursos)

PHP 8.4, PSR-6/16, TTL, `DateInterval`, bulk, `remember()`, namespaces, serializers e backends Array, File, Redis, APCu e Null.

📦 Instalação
------------

[](#-instalação)

```
composer require omegaalfa/cache
php exemplo.php
```

Redis requer `ext-redis`; APCu requer `ext-apcu`.

🚀 Primeiro exemplo
------------------

[](#-primeiro-exemplo)

```
require __DIR__.'/vendor/autoload.php';
use Omegaalfa\Cache\CacheFactory;

$cache = CacheFactory::array();
$cache->set('saudacao', 'Olá!', 60);
echo $cache->get('saudacao', 'MISS');
```

A factory cria memória local, `set()` grava por 60 segundos e `get()` lê ou devolve o padrão.

🗄️ Backends disponíveis
-----------------------

[](#️-backends-disponíveis)

BackendPersistênciaCompartilhadoUsoArrayStore❌❌testes/processo curtoFileStore✅um hostpersistência localRedisStore✅✅produção distribuídaApcuStoredepende do SAPIum hostcache local experimentalNullStore❌❌cache desabilitado### ArrayStore

[](#arraystore)

```
$cache = CacheFactory::array(maxEntries: 1000);
```

Rápido e sem dependências; some ao terminar o processo.

### FileStore

[](#filestore)

```
use Omegaalfa\Cache\Config\FileConfig;
$cache = CacheFactory::file(new FileConfig(__DIR__.'/var/cache'));
```

Usa locks, checksum, temporário e `rename()`. Indicado para filesystem local Unix/WSL. Não há `fsync`; NFS e Windows nativo não foram homologados.

### RedisStore

[](#redisstore)

```
use Omegaalfa\Cache\Config\RedisConfig;
$cache = CacheFactory::redis(new RedisConfig(
    host: '127.0.0.1', password: getenv('REDIS_PASSWORD') ?: null,
    database: 0, timeout: 2.0, readTimeout: 2.0, prefix: 'app:prod:',
));
```

É compartilhado e usa MGET/pipeline. `clear()` versiona o namespace sem FLUSHDB. Não há failover; TLS com certificados ainda é experimental. Também existe `CacheFactory::fromRedis($redis, 'app:')`.

### NullStore

[](#nullstore)

```
$cache = CacheFactory::null();
```

Aceita gravações e sempre retorna miss.

### ApcuStore — experimental

[](#apcustore--experimental)

```
$cache = CacheFactory::apcu('app:');
```

Hit, miss, TTL, bulk e namespace são testados, mas concorrência/SAPIs precisam de matriz maior. Não compartilha entre hosts. Em CLI: `php -d apc.enable_cli=1 script.php`.

🧠 Conceitos e API
-----------------

[](#-conceitos-e-api)

```
$cache->set('segundos', 'valor', 300);
$cache->set('intervalo', 'valor', new DateInterval('PT15M'));
$cache->set('infinito', 'valor', null);
$cache->has('segundos');
$cache->delete('segundos');
$cache->clear();

$cache->setMultiple(['a' => 1, 'b' => 2], 60);
$valores = $cache->getMultiple(['a', 'b', 'c'], null);
$cache->deleteMultiple(['a', 'b']);
```

TTL zero/negativo expira imediatamente. Use prefixos Redis/APCu ou diretórios File distintos como namespaces.

### remember()

[](#remember)

```
$usuario = $cache->remember('usuario-42', 300, fn() => buscarUsuario(42));
```

O resolver roda somente no miss; suas exceções são propagadas. Não há lock contra stampede.

### Tipos, null e valores falsy

[](#tipos-null-e-valores-falsy)

```
$cache->set('string', 'texto');
$cache->set('int', 42);
$cache->set('float', 19.9);
$cache->set('false', false);
$cache->set('zero', 0);
$cache->set('vazio', '');
$cache->set('null', null);
$cache->set('array', ['a']);
$cache->set('objeto', new stdClass());

var_dump($cache->has('null')); // true: diferencia null de miss
```

O `NativeSerializer` é padrão. Para JSON:

```
use Omegaalfa\Cache\SimpleCache;
use Omegaalfa\Cache\Serializer\JsonSerializer;
use Omegaalfa\Cache\Store\ArrayStore;
$cache = new SimpleCache(new ArrayStore(), new JsonSerializer());
```

Closures/resources falham com `SerializationException`.

### Configuração por array

[](#configuração-por-array)

```
$cache = CacheFactory::create([
 'driver' => 'file',
 'file' => ['directory' => __DIR__.'/var/cache', 'gcProbability' => 1, 'gcDivisor' => 100],
]);
```

Drivers: `array`, `file`, `redis`, `apcu`, `null`.

### Exceções

[](#exceções)

```
use Omegaalfa\Cache\Exception\InvalidArgumentException;
use Omegaalfa\Cache\Exception\BackendUnavailableException;
try {
    $cache->set('chave/invalida', 'x');
} catch (InvalidArgumentException|BackendUnavailableException $e) {
    error_log($e->getMessage());
}
```

Chaves vazias ou com `{}()/\\@:` são inválidas.

🎯 Casos reais
-------------

[](#-casos-reais)

```
$usuarios = $cache->remember('usuarios-ativos', 60, fn() =>
    $pdo->query('SELECT id,nome FROM usuarios WHERE ativo=1')->fetchAll(PDO::FETCH_ASSOC)
);
$cotacao = $cache->remember('cotacao-usd', 30, fn() =>
    json_decode(file_get_contents('https://api.exemplo.test/cotacao'), true, flags: JSON_THROW_ON_ERROR)
);
$relatorio = $cache->remember('relatorio', new DateInterval('PT30M'), fn() => gerarRelatorio());
$config = $cache->remember('config', 300, fn() => json_decode(file_get_contents(__DIR__.'/config.json'), true));
$html = $cache->remember('html-inicial', 120, fn() => renderizarPagina());
$permissoes = $cache->remember('permissoes-42', 60, fn() => carregarPermissoes(42));
```

Após mudar o dado, use `delete()`. Também se podem guardar metadados de arquivos e dados temporários de sessão, mas a biblioteca não gerencia arquivos nem implementa `SessionHandlerInterface`.

📖 PSR-6
-------

[](#-psr-6)

```
use Omegaalfa\Cache\CacheItemPool;
use Omegaalfa\Cache\Store\ArrayStore;
$pool = new CacheItemPool(new ArrayStore());
$item = $pool->getItem('produto-42');
if (!$item->isHit()) {
    $item->set(['nome'=>'Monitor'])->expiresAfter(300);
    $pool->save($item);
}
$pool->saveDeferred($pool->getItem('outra')->set('valor'));
$pool->commit();
```

O destrutor não faz commit implícito.

✅ Boas práticas
---------------

[](#-boas-práticas)

- escolha TTL pela tolerância a dados antigos;
- invalide após escritas;
- separe ambiente/versão por namespace;
- use bulk para muitas chaves;
- mantenha senhas fora do código;
- monitore backend e teste hit, miss e falha;
- nunca use cache como única persistência.

❌ Erros comuns
--------------

[](#-erros-comuns)

ErroSoluçãoconfundir null e missuse `has()`esperar persistência do ArrayStoreuse File/Redisnunca invalidarcombine TTL e `delete()`esperar fallback Rediscapture exceção e defina políticausar APCu entre hostsuse Redisguardar closure/resourcearmazene dados serializáveis⚠️ Limitações atuais e roadmap
------------------------------

[](#️-limitações-atuais-e-roadmap)

Não fazem parte da versão estável: locks distribuídos, stampede, failover, L1/L2, tags e métricas. Redis TLS ainda carece de integração com certificados; FileStore não tem `fsync`; APCu permanece experimental para concorrência/SAPI.

Roadmap: locks/stampede, failover explícito, métricas, L1/L2, igbinary/msgpack, tags, Redis TLS e matriz APCu ampliada.

❓ FAQ
-----

[](#-faq)

**Preciso de Redis?** Não: Array atende um processo e File um host.

**Expira sozinho?** Após o TTL produz miss; a remoção física depende do backend.

**Se Redis cair?** Lança `RedisConnectionException`, sem fallback silencioso.

**Funciona em CLI/Docker?** Sim, com extensões, rede e permissões corretas.

**Qual backend?** Array/processo; File/host; Redis/distribuído; APCu/local experimental; Null/desabilitado.

🧪 Qualidade
-----------

[](#-qualidade)

```
composer validate --strict
composer style
composer phpstan
composer test
composer test:coverage
```

📄 Licença
---------

[](#-licença)

MIT. Consulte [LICENSE](LICENSE), [CONTRIBUTING.md](CONTRIBUTING.md) e [SECURITY.md](SECURITY.md).

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/16062691?v=4)[omegaalfa](/maintainers/omegaalfa)[@omegaalfa](https://github.com/omegaalfa)

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/omegaalfa-cache/health.svg)

```
[![Health](https://phpackages.com/badges/omegaalfa-cache/health.svg)](https://phpackages.com/packages/omegaalfa-cache)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[flow-php/etl

PHP ETL - Extract Transform Load - Abstraction

378604.0k107](/packages/flow-php-etl)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M605](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)