aledefreitas/zlx_cache

Módulo de cache para os sites dos servidores da PROJECT / ZLX

ZLX Cache

, _(*1)

### Introdução

A classe ZLX\Cache traz uma forma elegante de utilizar cache na aplicação, facilitando a implementação de sistemas de Cache em sua aplicação. Com esta classe é possível criar várias instâncias separadas de Cache para sua aplicação, sem forçar que sua aplicação se restrinja a apenas uma implementação de cache. Você poderá alterar ou criar engines de cache com sua própria lógica, sobre-escrevendo a classe CacheEngine. Também pode apagar dados de várias instâncias de uma só vez, através dos namespaces atribuídos às instâncias!, _(*2)

### Instalação

É possível instalar o ZLX\Cache através do Composer:, _(*3)

composer require aledefreitas/zlx_cache

### Requerimentos

• PHP 7.0+

### Pre-built Engines

• Redis
• Memcached
• Memcache

### Modo de uso

Abaixo citaremos as funções que são utilizadas no gerenciamento do cache na sua aplicação. Primeiramente, iniciamos o Cache, no início de seu código de inicialização da aplicação:, _(*4)

    use ZLX\Cache\Cache;
    $config = [ 'prefix' => 'cache_prefix',
                'instances' => [
                    // Utilizamos default, pois é a configuração padrão do cache
                    'default' => [  'engine' => 'memcached',
                                    'duration' => '+10 minutes',
                                    'groups' => [ 'Posts', 'Comments', 'Session' ],
                                    'prevent_clear' => [ 'Session' ] ]
                ]
            ];
    // Iniciamos o cache
    Cache::init($config);

Atenção!

Tenha muita atenção ao setar a configuração 'prefix' na inicialização do Cache. Ela é o prefixo para as entradas de cache de seu site, e não deve ser duplicada com nenhum outro prefixo igual em qualquer outro site no servidor inteiro., _(*5)

Criando instâncias on-the-fly (em tempo de execução)

Podemos criar instancias novas programáticamente em tempo de execução com a função Cache::create():, _(*6)

    use ZLX\Cache\Cache;
    $config = [ 'engine' => 'memcached',
                'duration' => '+10 minutes',
                'groups' => [ 'Posts', 'Comments', 'Session' ],
                'prevent_clear' => [ 'Session' ]
            ];

    Cache::create('meu_cache', $config);

Atributos das instâncias:

• 'engine': É o Engine a ser utilizado. Ex.: 'memcached'
• 'duration': Duração das chaves de cache. Ex.: '+40 minutes'
• 'prefix': Prefixo da instância. Ex.: 'prefixo_zlx'
• 'namespaces': Array contendo os namespaces ao qual a instância pertence. Ex.: [ 'Posts', 'Admin' ]
• 'groups': Array contendo os grupos da instância. Ex.: [ 'Comments', 'Session', 'Users' ]
• 'prevent_clear': Array contendo os grupos que são ignorados quando o método clear(false)

Após inicializado, poderemos utilizar todas suas funcionalidades:, _(*7)

Atenção!

Todas as funções tem como padrão a instância 'default'. Caso seja omitido este parâmetro, a instância utilizada será a 'default'. Você pode especificar o parametro para utilizar outra instância., _(*8)

set(key, value [, instance = 'default')

Salva uma chave e seu valor no cache. Retorna (boolean) com true quando foi salvo com sucesso, e false quando não foi salvo com sucesso., _(*9)

        Cache::set('chave', 'teste de valor', 'default');

get(key [, instance = 'default')

Retorna o valor de uma chave do cache. Retorna (boolean) false caso não seja encontrado nada., _(*10)

        Cache::get('chave', 'default');

delete(key [, instance = 'default')

Apaga o valor de uma chave do cache. Retorna (boolean) com true caso delete, e false caso não delete., _(*11)

        Cache::delete('chave', 'default');

remember(key, callable [, instance = 'default')

Pesquisa o valor da chave requisitado, caso o mesmo não exista, executa a função callable e salva na chave requisitada (e retorna) seu retorno., _(*12)

        Cache::remember('chave', function() {
        // Inclua sua lógica aqui
        return $retorno;
        }, 'default');

clearGroup(group [, instance = 'default')

Invalida todas as chaves de um grupo determinado na instancia escolhida, _(*13)

        Cache::clearGroup('Grupo', 'default');

clear([ ignore_prevents = false [, instance = 'default')

Apaga todas as entradas de cache da instancia. Caso ignore_prevents seja setado como true, ignorará até os grupos em 'prevent_clear'., _(*14)

        Cache::clear(false, 'default');

clearNamespace(namespace)

Invoca o método clear() de todas as instâncias sob o namespace escolhido, _(*15)

        Cache::clearNamespace('Namespace');

### Funcionamento dos Grupos de Cache

A funcionalidade de grupos de Cache no ZLX\Cache é interessante para invalidar/resetar apenas entradas de cache em um grupo específico. Suponhamos que em determinado momento da sua lógica, você cria uma entrada de Cache sob o grupo 'Posts', para guardar os dados de uma postagem específica:, _(*16)

        Cache::set("Posts.data.".$id_post, [ "title" => "Meus dados do post", "body" => "Corpo do meu post" ]);

Ao utilizar o padrão 'Grupo.chave' para salvar, deletar, ou retornar uma chave (set(),get()***,delete(),remember()), caso o grupo esteja no array de grupos da sua instância, ele será salvo sob este grupo., _(*17)

Ao invocar o método**clearGroup()***, invalidamos todas as chaves sob este grupo, de forma que na próxima requisição de qualquer chave deste grupo, ela não será encontrada no cache, e portanto será renovada!, _(*18)

### Funcionamento dos Namespaces

É muito parecido com o funcionamento de grupos, porém funciona num escopo acima dos grupos. Os grupos pertencem à instancia, e as instâncias pertencem aos namespaces. Quando o método**clearNamespace()*** for invocado, ele irá executar um clear (***ignorando os prevents***) em todas as instâncias pertencentes ao namespace a ser resetado., _(*19)

### Criando e utilizando uma Engine personalizada

O ZLX\Cache permite que sejam criadas Engines personalizadas para que possa-se desenvolver as lógicas necessárias do programador através de abstração da classe ZLX\Cache\CacheEngine!, _(*20)

Abaixo segue o exemplo de uma classe personalizada:, _(*21)

use ZLX\Cache\CacheEngine;

    class CustomCacheEngine extends CacheEngine {
    public $_defaultConfigs; // Configurações padrões

    public function __construct(array $config) {
        // Lógica do método construtor

        $this->_configs = array_merge($this->_defaultConfigs, $config); // Merge das configurações padrões. É necessário caso haja configurações padrões.
        parent::__construct($config);
    }

    public function set($key, $value, $custom_ttl = false) {
        // Lógica de salvamento de valores no cache
    }

    public function get($key) {
        // Lógica de busca de valores no cache
    }

    public function delete($key) {
        // Lógica de apagamento de valor no cache
    }

    public function clear($ignore_prevents) {
        // Lógica para reset do cache
    }

    public function add($key, $value, $ttl = 3) {
        // Lógica para add no cache
    }
}

Então, será possível adicionar instâncias desta classe de duas maneiras diferentes:, _(*22)

    // Através da inicialização do Cache
    use ZLX\Cache\Cache;
    $config = [ 'prefix' => 'cache_prefix',
                'instances' => [
                    'meu_cache' => [    'engine' => 'CustomCacheEngine',
                                        'duration' => '+10 minutes',
                                        'groups' => [ 'Posts', 'Comments', 'Session' ],
                                        'prevent_clear' => [ 'Session' ] ]
                ]
            ];

    Cache::init($config);

    // Através da inicialização do Cache
    use ZLX\Cache\Cache;
    $config = [ 'engine' => 'CustomCacheEngine',
                'duration' => '+10 minutes',
                'groups' => [ 'Posts', 'Comments', 'Session' ],
                'prevent_clear' => [ 'Session' ]
            ];

    Cache::create('meu_cache', $config);

Desta forma, você pode criar engines que utilizam a lógica que for necessária implementada., _(*23)