Fonte de dados: Memcache

---

1Apresentação

O cache costuma ser usado para armazenar informações que são frequentemente acessadas para leitura. Por isso, é preferível não lê-las no banco de dados a cada acesso, mas sim agregá-las e colocá-las em cache; as leituras seguintes serão mais rápidas.

É preciso entender que, ao contrário das sessões, as variáveis de cache são comuns a toda a aplicação. Por isso, é importante pensar cuidadosamente na nomenclatura das variáveis, para poder encontrá-las facilmente.
Outra diferença é que as variáveis de cache têm como propósito permanecer temporárias. Elas expiram depois de um certo tempo, que pode ser definido de forma global ou precisamente para cada variável. Por padrão, o tempo de expiração é de 24 horas.

Se você configurou corretamente os parâmetros de conexão com o servidor Memcached, o Temma cria automaticamente um objeto do tipo \Temma\Datasources\Memcache. Por convenção, vamos considerar que você nomeou essa conexão cache no arquivo etc/temma.php (veja a documentação de configuração).

Nos controladores, a conexão com o cache fica então disponível ao escrever:

$cache = $this->cache;

Nos outros objetos gerenciados pelo componente de injeção de dependências, a conexão com o cache pode ser acessada ao escrever:

$cache = $loader->dataSources->cache;
$cache = $loader->dataSources['cache'];

---

2Configuração

No arquivo etc/temma.php (veja a documentação de configuração), você declara o DSN (Data Source Name) usado para se conectar ao(s) servidor(es) Memcache.

Quando os dados são distribuídos entre vários servidores Memcache, cabe aos clientes conhecer todos os servidores, e a lista deles deve ser configurada de forma idêntica em todos os clientes que precisam se conectar aos servidores.

O DSN para se conectar a um servidor Memcache é escrito da seguinte forma: memcache://SERVIDOR[:PORT]
O número de porta padrão é 11211.

Quando há vários servidores Memcache, separe-os com ponto e vírgula.
Exemplo: memcache://localhost;otherhost:11000;anotherhost

Se o servidor Memcache estiver em execução na mesma máquina, é possível se conectar usando um socket Unix, evitando assim as latências de rede. Nesse caso, o DSN é da forma: memcache://CAMINHO
O caminho deve levar ao socket Unix (geralmente /var/run/memcache/memcached.sock).
Exemplo: memcache:///var/run/memcache/memcached.sock

Por padrão, as variáveis de cache são armazenadas em um namespace específico para cada site, com base no nome de domínio completo (www.mysite.com, othersite.org, test.othersite.org, etc.). Se você precisar compartilhar variáveis de cache entre vários sites, é possível especificar o namespace acrescentando-o ao final do DSN após um sinal de cerquilha (#).

Exemplos:
memcache://localhost#globalsite.com
memcache://cache.server:11000#globalsite.com
memcache:///var/run/memcache/memcached.sock#cache_namespace

---

3Chamadas unificadas

3.1Acesso como array

// verificação da existência de um dado
if (isset($cache['key1']))
    doSomething();

// leitura de dados (desserializados)
$data = $cache['key1'];

// escrita de dados (serializados)
$cache['key1'] = $value;

// exclusão de dados
unset($cache['key1']);

// número de elementos
$cnt = count($cache);

---

3.2Métodos gerais

// verificação da existência de um dado
if ($cache->isSet('user:1'))
    doSomething();

// exclusão de um dado
$cache->remove('user:1');

// exclusão de vários dados
$cache->mRemove(['user:1', 'user:2', 'user:3']);

// exclusão de dados a partir de um prefixo
$cache->clear('user:');

// exclusão de todos os dados
$cache->flush();

---

3.3Gerenciamento de dados serializados complexos

O Memcache não suporta o método search().

Por padrão, os dados armazenados no Memcache têm uma duração de vida de 24 horas. É possível especificar o número de segundos de cache, até 30 dias (seja especificando 2592000 segundos, seja indicando o valor -1).

// leitura de dados (desserializados)
$user = $cache->get('user:1');
// leitura de dados com valor padrão
$color = $cache->get('color', 'blue');
// leitura de dados com criação de dados se necessário
$user = $cache->get("user:$userId", function() use ($userId) {
    return $this->dao->get($userId);
});

// leitura de vários dados (desserializados)
$users = $cache->mGet(['user:1', 'user:2', 'user:3']);

// escrita de dados (serializados)
$cache->set('user:1', $userData);
// escrita de dados (serializados) com uma duração de vida de uma hora
$cache->set('user:1', $userData, 3600);

// escrita de vários dados (serializados)
$cache->mSet([
    'user:1' => $user1data,
    'user:2' => $user2data,
    'user:3' => $user3data,
]);
// escrita de vários dados, com uma duração de vida de 30 dias
$cache->mSet([
    'user:1' => $user1data,
    'user:2' => $user2data,
], -1);

---

3.4Gerenciamento de dados brutos

O Memcache não suporta o método find().

Por padrão, os dados armazenados no Memcache têm uma duração de vida de 24 horas. É possível especificar o número de segundos de cache, até 30 dias (seja especificando 2592000 segundos, seja indicando o valor -1).

// leitura de dados (brutos)
$html = $cache->read('page:home');
// leitura de dados com valor padrão
$html = $cache->read('page:home',
                           '<html><body><h1>Homepage</h1><body><html>');
// leitura de dados com criação de dados se necessário
$html = $cache->read('page:home', function() {
    return file_get_contents('/path/to/homepage.html');
});

// leitura de vários dados (brutos)
$pages = $cache->mRead(['page:home', 'page:admin', 'page:products']);

// cópia de um dado para um arquivo local
$cache->copyFrom('page:home', '/path/to/newpage.html');
// cópia de um dado para um arquivo local, com valor padrão
$cache->copyFrom('page:home', '/path/to/newpage.html', $defaultHtml);
// cópia de um dado para um arquivo local, com criação de dados se necessário
$cache->copyFrom('page:home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
});
// cópia de um dado para um arquivo local, com criação de dados se necessário
// (com uma duração de vida de uma hora)
$cache->copyFrom('page:home', '/path/to/newpage.html', function() {
    return file_get_contents('/path/to/oldpage.html');
}, 3600);

// escrita de dado (bruto)
$cache->write('color:blue', '#0000ff');
// escrita de dado (bruto) com uma duração de vida de uma hora
$cache->write('color:blue', '#0000ff', 3600);

// escrita de vários dados (brutos)
$cache->mWrite([
    'color:blue'  => '#0000ff',
    'color:red'   => '#ff0000',
    'color:green' => '#00ff00',
]);
// escrita de vários dados com uma duração de vida de 30 dias
$cache->mWrite([
    'color:blue'  => '#0000ff',
    'color:red'   => '#ff0000',
], -1);

// escrita de dado (bruto) a partir de um arquivo local
$cache->copyTo('page:home', '/path/to/homepage.html');
// escrita de dado a partir de um arquivo local, com uma duração de vida de uma hora
$cache->copyTo('page:home', '/path/to/homepage.html', 3600);

// escrita de vários dados (brutos) a partir de arquivos locais
$cache->mCopyTo([
    'page:home'     => '/path/to/homepage.html',
    'page:admin'    => '/path/to/admin.html',
    'page:products' => '/path/to/products.html',
]);
// escrita de vários dados a partir de arquivos locais com uma duração de vida de 30 dias
$cache->mCopyTo([
    'page:home'  => '/path/to/homepage.html',
    'page:admin' => '/path/to/admin.html',
], -1);

---

4Chamadas específicas

4.1Expiração do cache

O método setExpiration() é usado para definir o tempo de cache padrão. Isso evita ter que defini-lo explicitamente toda vez que um dado é escrito no cache.
Ele recebe um parâmetro, que é a duração de vida máxima dos dados em cache, expressa em segundos. Por padrão, a duração é de 86400 segundos (24 horas).
Esse método retorna a instância do objeto de cache.

// define o prazo de expiração padrão para uma hora
$cache->setExpiration(3600);

// expiração de 5 minutos, seguida da adição de um dado
$cache->setExpiration(300)->set('aa', 'bb');

Você pode usar o método getExpiration() para saber o tempo de cache atualmente configurado.

// queremos garantir que o prazo de expiração seja de pelo menos 1 hora
$exp = $cache->getExpiration();
if ($exp < 3600)
    $cache->setExpiration(3600);

---

4.2Gerenciamento de prefixo

O que chamamos de "prefixos" é um rótulo que é acrescentado aos nomes das variáveis de cache. A vantagem é poder gerenciar todas as variáveis de cache que têm o mesmo prefixo, para invalidá-las em uma única operação.

O método setPrefix([string $prefix]) é usado para definir o prefixo das variáveis que serão processadas nas chamadas a get() e set() que se seguirem. Chamá-lo sem parâmetros remove o uso de prefixos.
Ele retorna a instância do objeto de cache.

O método clear(string $prefix) é usado para invalidar todas as variáveis de cache que têm o prefixo passado como parâmetro.
Ele também retorna a instância do objeto de cache.

Exemplo de uso:

// definição de um prefixo
$cache->setPrefix('sites');
// adição de variáveis de cache
$cache->set('A', $siteA);
$cache->set('B', $siteB);
$cache->set('C', $siteC);

// definição de outro prefixo
$cache->setPrefix('articles');
// adição de variáveis de cache
$cache->set('Y', $articleY);
$cache->set('Z', $articleZ);

// exclusão das variáveis pertencentes ao primeiro prefixo
// ("A", "B" e "C")
$cache->clear('sites');

// interrompe o uso do prefixo "articles"
$cache->setPrefix();

// recupera uma variável com prefixo
$data = $cache->setPrefix('articles')->get('Z');

É possível saber o prefixo atual usando o método getPrefix():

$prefix = $cache->getPrefix();
if ($prefix != 'sites')
    $cache->setPrefix('sites');

---

4.3Habilitar / desabilitar o cache

O método disable() é usado para desativar temporariamente o uso do cache. Todas as chamadas subsequentes não retornarão erro, mas nenhum acesso ao cache será realizado.
O método enable() permite reativar o uso do cache (depois de uma chamada a disable(), por exemplo).
Esses dois métodos retornam a instância do objeto de cache.

Exemplo de uso:

// desativa o cache
$cache->disable();

// a função anônima será sistematicamente executada,
// porque o cache está desativado
$article = $cache->get(
    "article:$articleId",
    function () use ($articleId, $dao) {
        return ($dao->get($articleId));
    }
);

// reativa o cache e salva uma variável
$cache->enable()->set('name', $value);

O método enable() reativa o cache que foi temporariamente desativado. Ele também retorna a instância do objeto de cache.

$cache->enable();

Para saber se o cache está ativado ou desativado, você pode usar o método isEnabled(), que retorna true se o cache estiver ativado, e false caso contrário.

if (!$cache->isEnabled())
    print("Cache desativado");