Finalmente, depois de muitos anos, achei que tivesse encontrado uma situação em que variáveis estáticas seriam úteis para mim no PHP.

A diferença da variável estática em uma função é que ela não perde o seu valor quando a execução deixa o seu escopo. Isto é, na próxima vez que a função for executada, a variável terá o mesmo valor que tinha na execução anterior.

Nunca tinha achado muita utilidade pra isso, até porque geralmente as variáveis locais de um método realmente tinham o tempo de vida de cada execução. Quando não, fazia mais sentido utilizar uma propriedade da classe.

Até que recentemente surgiu a necessidade de executar um método que consultava o banco de dados dezenas de vezes em uma única requisição, alterando apenas o parâmetro da query.

Como consultar o banco uma única vez não era viável neste caso, um raciocínio que segui para tentar poupar um pouco o servidor foi efetuar o prepare somente 1 vez para cada query. E aí entrou a variável estática, guardando o resultado do prepare para execuções futuras, na mesma requisição.

Dessa forma, a partir da segunda vez que o método for chamado, ele executa direto o prepared statement com o id que deve ser consultado, sem ter que fazer o prepare de novo.

Para minha surpresa, fazendo um benchmark simples hoje (meses depois de implementar com static, assumindo que seria mais rápido), percebi que poupar o prepare no Oracle não fez muita diferença. Pelo visto o Oracle percebe que é a mesma query e não prepara novamente, ou simplesmente fazer o prepare é tão simples que não faz diferença economizar.

Sendo assim, parece que a pequena utilidade que eu tinha dado a variáveis estáticas não me serviu de nada. Estou apresentando o resultado aqui porque, bem… “Negative results are still results. Even 20 thousand of them”.

Pelo visto vou ficar sem ter utilidade para variáveis estáticas. A não ser que você tenha outros relatos positivos :)

É comum ver scripts com dezenas de linhas de código pra fazer algo extremamente simples. Fica aqui meu apelo desesperado com algumas dicas rápidas.

1 – Listar arquivos de um diretório

Se não houver um motivo muito claro pra usar opendir, readdir e closedir (não consigo pensar em nenhum), a forma mais prática de listar o conteúdo de um diretório é com DirectoryIterator:

Se for necessário listar os arquivos recursivamente, percorrendo todos os subdiretórios, é só usar o RecursiveDirectoryIterator junto com o RecursiveIteratorIterator:

Com um pouco de criatividade, é possível estender essas classes com qualquer lógica facilmente, como por exemplo, para montar uma árvore com a estrutura dos diretórios.

2 – montar e desmontar query strings

Mesmo que menos comum (e menos útil), colocar uma query string numa URL é um trabalho trivial demais pra ser feito com implode, concatenando tudo ou qualquer outro método engenhoso. Desde o lançamento do PHP 5 é possível contar com a http_build_query:

E o inverso também é possível com as funções parse_url e parse_str:

Só fique atento que, por motivos alheios ao bom senso, parse_str por padrão extrai as variáveis no escopo onde foi chamada. É necessário passar um segundo argumento para ter um array gerado por referência, como no exemplo acima com a variável $query.

3 – ler páginas remotas

Dentre todas as implementações, a mais desnecessária costuma ser fsockopen, fwrite, feof, fgets e fclose para ler arquivos remotos por HTTP.

Uma função já resolve:

Isso é possível graças aos protocol wrappers que encapsulam a lógica de acesso aos respectivos protocolos, tal como HTTP. Esta forma de acesso, no entanto, depende da configuração allow_url_fopen estar habilitada no php.ini (que é o padrão).

Para ler os response headers da requisição, utilize fopen com stream_get_meta_data.

E se um dia você quiser impressionar a mulherada, veja a função stream_wrapper_register para criar o seu próprio protocol wrapper.

4 – submeter dados por post para uma página remota

A coisa fica mais complicada quando o desenvolvedor pensa em usar cURL pra submeter dados por POST para outro servidor. A extensão até tem seu mérito, mas usá-la apenas pra este propósito é um grande equívoco.

As funções que fazem uso dos protocol wrappers aceitam um objeto de stream context, criado pela função stream_context_create, para configurar alguns aspectos do protocolo. As opções de contexto do protocolo HTTP permitem definir, entre outras coisas, o método de acesso (GET, POST, etc) e o conteúdo a ser postado:

Quando não for necessário ler o retorno da requisição, basta chamar a url com fopen passando o contexto como quarto argumento.

5 – fazer download de um arquivo remoto

Vale lembrar que a maioria das funções de stream e filesystem aceitam URLs completas e fazem uso da abstração do protocolo. O que eu vejo muita gente esquecer é que isso inclui a função copy:

O trecho acima vai baixar a imagem remota e salvar no arquivo local /tmp/Terri Clark.jpg. E caso não seja óbvio, “local” se refere a quem está executando o script PHP, que no caso será o seu servidor caso seja um script web, e não o cliente que está acessando pelo browser.

Se o objetivo for realmente repassar o conteúdo remoto para o cliente que estiver acessando pelo browser, o script é igualmente simples:

Considerando que estamos apenas testando a funcionalidade. Ter um script de proxy totalmente funcional é bem mais complexo, e certamente já tem algo pronto por aí.

6 – fazer cálculo com data

Dentre todas as simplificações possíveis, a que mais costuma comover é a função strtotime. Pra quem já está acostumado, parece que não faz mais do que sua obrigação. Mas pra quem ainda faz cálculos com data multiplicando por 86400, chega a parecer mágico:

Mais exemplos você mesmo pode ver no manual do PHP ou na página de Date Input Formats do projeto GNU. Para o nome dos meses e dias da semana ficarem em português, utilize setlocale(LC_TIME, ‘pt_BR’); antes de chamar a função strftime.

7 – escapar sql e html

Felizmente nunca mais vi nenhum script com aberrações anti-sql-injection, mas há algum tempo era possível encontrar pessoas removendo palavras-chave de SQL de todas as strings que íam para o banco de dados. Se o usuário digitasse palavras como select, delete ou drop, elas eram simplesmente removidas da frase. Isso quando o programador não interrompia o script e acusava o usuário de estar tentando explorar alguma falha de segurança. Eu juro, isso existia.

Ao trabalhar com PDO, a melhor opção (pra não dizer a única!) é utilizar prepare e execute pra separar a query em si dos seus parâmetros:

Se estiver utilizando drivers nativos, veja as funções mysql_real_escape_string ou mysqli_prepare e mysqli_stmt_bind_param, dependendo da extensão. Certamente outros bancos de dados têm a mesma funcionalidade.

A única preocupação é garantir que os parâmetros não se misturem com a query; não precisa inventar moda e remover o que o usuário digitou.

Outra confusão comum é ao escapar HTML. O objetivo é evitar que o texto digitado por um usuário seja interpretado pelo browser de todos os usuários do site.

Conceitualmente, esta é uma responsabilidade da camada de exibição. O template é que deve utilizar htmlspecialchars antes de gerar a saída na tela, e não antes de salvar no banco. Isso garante que o conteúdo que está no banco é fiel ao que foi digitado pelo usuário e pode ser reaproveitado em outras mídias além do HTML.

O que pode e deve ser feito é filtrar conteúdo realmente indevido, como caracteres inválidos ou espaços extras, dependendo da aplicação.

E então o camarada decide programar orientado a objetos. Coloca todas as funções procedurais dentro de uma classe e acha o máximo. Comete o erro que eu chamo de Programação Orientada a Classes.

Assunto batido demais na altura do campeonato, mas com a quantidade de vezes que tenho visto isso acontecer, melhor tentar esclarecer algumas coisas.

Ultimamente, o erro mais comum tem sido ao criar classes de acesso ao banco. Não entrarei no mérito de usar ou não um framework já existente ou da vantagem de ORM. Se o cara quer criar as classes, que crie. Mas crie corretamente.

A dificuldade está em perceber os objetos e criar métodos orientados a cada um deles. Ao lidar com banco de dados, o primeiro passo é identificar os três sujeitos principais:

• a conexão com o banco
• o resultado de uma consulta, ou rowset
• e cada item desse resultado, ou row

Como assumem três papéis distintos, devem ser representados por três classes diferentes.

Surge então a dúvida se o rowset deve estender a conexão ou vice-versa. Esse pensamento é fruto direto do que o desenvolvedor acha que entendeu ao ver tantos extends por aí. Se não houvesse influência de achar que orientação a objeto significa objetos estendendo objetos, ficaria mais claro que as classes trabalham independentemente.

Estende-se uma classe para criar um subtipo dela. É perfeitamente válido que a classe Carro estenda a classe Automóvel, porque carro é um tipo de automóvel. Mas fisicamente não faz sentido que Carro estenda Motor; ele simplesmente usa um motor. Até porque, se fosse seguir essa linha de raciocínio, um carro teria que estender motor, porta, roda, volante…

A dúvida seguinte é de como interligar essas classes. A solução vem conforme identificamos o papel de cada uma delas.

A classe que representa a conexão precisa de um método para conectar no banco e outro para executar queries. Podemos assumir também que cada query tem um resultado. Sendo assim, a execução de queries deve retornar um objeto rowset.

O rowset por sua vez precisa de um resource no qual trabalhar. Logo, a conexão, que é quem vai criar este objeto, deve passar o resource no constructor, que nada mais é do que o retorno de mysql_query(), por exemplo. Uma vez construído, o rowset precisa minimamente de um método para contar a quantidade de rows retornados e outro para retornar cada row.

Seguindo este modelo, uma classe para conexão com o MySQL pode começar assim:

Um ponto importante a observar é que o resultado de mysql_connect() é associado a uma propriedade do objeto para ser referenciado mais tarde. Isso garante que, caso existam outras conexões, as funções mysql_select_db e mysql_query sejam utilizadas na conexão correspondente ao objeto no qual foram chamadas.

O método query executa a SQL passada como argumento e monta um objeto para representar o rowset, passando o resource retornado pela mysql_query() para o constructor.

No constructor, colocamos o resource em uma propriedade do objeto porque precisaremos dele nos métodos count() e fetchAssoc().

No fetchAssoc(), seria legal retornar um objeto próprio do tipo Row ao invés de retornar simplesmente um array. Isso ajuda principalmente se for necessário encapsular alguma lógica nos rows. Mas isso fica como dever de casa.

As consultas ficariam assim:

A principal diferença desta implementação com o que alguns desenvolvedores têm implementado é que os métodos estão realmente orientados aos respectivos objetos, e não amontuados em uma única classe.

Agora, pra impressionar mais as gatinhas:

1. Controle erros utilizando Exceptions
2. Leia sobre interfaces e factory pattern para saber como abstrair o driver do código final
3. Implemente a interface Iterator da SPL e utilize o rowset em um foreach
4. Crie classes de acesso para não ter SQL espalhado nos scripts
5. Finalmente, jogue tudo fora e use um framework com ORM :)

Espero que essa tentativa ajude a esclarecer também aqueles que estejam com dificuldade de desenhar seus objetos, mesmo que não sejam de acesso a banco.

No post sobre Fluent Interface, testei seu uso para nomear métodos de forma clara e reutilizável nas consultas ao banco de dados.

Durante o desenvolvimento, percebi que o Eclipse completava o código conforme eu digitava, tornando o uso das classes extremamente simples:

No final, a linha de código soava como uma frase em português, exceto pelos caracteres adicionais para a sintaxe do PHP.

A idéia então foi exportar a lista de classes e métodos parar criar uma linguagem própria do sistema, de forma que o usuário final pudesse usar o autocomplete pela web para formar uma frase sem as distrações da sintaxe.

A interface ficou assim:

Se o player não abrir, clique aqui para ver o vídeo de demonstração da interface no Youtube.

O autocomplete ainda não acompanha o que o usuário digita sem escolher uma opção, mas já é possível selecionar as opções com o teclado ou mouse, preencher cada parâmetro pelo prompt do Javascript e ter os métodos listados de acordo com o contexto.

A biblioteca e uma aplicação de exemplo estão no projeto DslCatalog que criei no Google Code.

Abaixo seguem os detalhes de como implementar os catálogos em um banco de dados já existente em 3 passos rápidos. Rápidos mesmo, eu juro :)

Passo 1 de 3: Criando as classes do modelo

A aplicação de exemplo segue com um banco de dados SQLite neste modelo:

Atualmente o único adapter de banco de dados para uso no DSL Catalog é a Zend Db Table. Mesmo que o projeto já utilize algum outro ORM ou qualquer abstração, as tabelas deverão ser mapeadas com a Zend_Db_Table_Abstract. O que não significa mudar de biblioteca. Apenas o mapeamento das tabelas deve ser feito.

Utilizando a Zend Db Table, que já está inclusa no pacote para download, a classe da tabela de cidades do modelo acima fica assim:

class Model_Cidade_Table extends Zend_Db_Table_Abstract
{
    protected $_name = 'cidade';
    protected $_rowClass = 'Model_Cidade_Row';
}

Para as tabelas que têm chave estrangeira, é preciso mapear as colunas e a classe que cada chave referencia:

class Model_Matricula_Table extends Zend_Db_Table_Abstract
{
    protected $_primary = array('id_aluno', 'id_matricula');
    protected $_name = 'matricula';
    protected $_rowClass = 'Model_Matricula_Row';
    
    protected $_referenceMap = array(
        'aluno' => array(
            'columns'       => 'id_aluno',
            'refTableClass' => 'Model_Aluno_Table',
            'refColumns'    => 'id',
        ),
        'curso' => array(
            'columns'       => 'id_curso',
            'refTableClass' => 'Model_Curso_Table',
            'refColumns'    => 'id',
        ),
    );
}

A propriedade $_rowClass descreve qual classe representará cada linha da tabela e é onde os métodos que atuam individualmente nos objetos devem ser implementados.

Para nós isso é importante porque precisamos de uma forma genérica de representar na tela cada objeto do catálogo. Nos exemplos, a representação é feita apenas como string com o método mágico __toString que o PHP utiliza, mas com um pouco de criatividade pode-se evoluir facilmente para widgets mais elaborados.

Cada cidade será objeto dessa classe, e sua representação como string é o próprio nome da cidade:

class Model_Cidade_Row extends Zend_Db_Table_Row_Abstract
{
    public function __toString()
    {
        return $this->nome;
    }
}

O mapeamento das classes deve ocorrer para cada tabela que estará disponível através dos catálogos.

Passo 2 de 3: Criando os catálogos

Nas imagens anteriores a consulta era alunos matriculados no curso letras atualmente com status cursando. Quando esta frase é interpretada pelo parser, os tokens são separados e a árvore de execução fica dessa forma:

1. catálogo de alunos
2. critério matriculados
3. catálogo de matrículas
4. critério noCurso com argumento letras
5. critério atualmenteComStatus com argumento cursando

Para permitir esta gramática, o catálogo de alunos fica assim:

class Catalogo_Alunos extends DslCatalog_Abstract
{
    /**
     * Instancia e retorna tabela de alunos
     *
     * @return DslCatalog_Database_Adapter_Zend
     */
    protected function _factoryAdapter()
    {
        return new DslCatalog_Database_Adapter_Zend(new Model_Aluno_Table());
    }
 
    /**
     * Retorna ligação destes alunos com suas matrículas
     *
     * @return Catalogo_Matriculas
     */
    public function matriculados()
    {
         return $this->_reference('Catalogo_Matriculas');
    }
}

O método _factoryTable deve ser sempre implementado e retornar o adaptador para a tabela que o catálogo representa.

Já o método matriculados faz parte da gramática do usuário. Ele utiliza o _reference para instanciar e retornar o catálogo relacionado, passando o nome do catálogo como argumento. Para realizar o JOIN, é importante que a relação entre as tabelas esteja mapeada (no Zend Db, através da array _referenceMap).

Como no PHP não existe type hint de retorno, é fundamental que a tag @return do phpDoc seja sempre incluída corretamente, pois é através dela que a interface determina o contexto dos critérios.

E então o catálogo de matrículas:

class Catalogo_Matriculas extends DslCatalog_Abstract
{
    /**
     * Instancia e retorna tabela de matrículas
     *
     * @return DslCatalog_Database_Adapter_Zend
     */
    protected function _factoryAdapter()
    {
        return new DslCatalog_Database_Adapter_Zend(new Model_Matricula_Table());
    }
 
    /**
     * Filtra matrículas pelo nome do curso
     *
     * @param string $curso
     * @return Catalogo_Matriculas
     */
    public function noCurso($curso)
    {
        $cursos = $this->_reference('Catalogo_Cursos');
        $cursos->chamados($curso);
 
        return $this;
    }
 
    /**
     * Filtra matrículas pelo status atual
     *
     * @param string $status
     * @return Catalogo_Matriculas
     */
    public function atualmenteComStatus($status)
    {
        $criterio = 'matricula.id_aluno = matricula_status.id_aluno'
                  . ' AND matricula.id_curso = matricula_status.id_curso'
                  . ' AND CURRENT_TIMESTAMP BETWEEN matricula_status.data_inicio'
                  . '                           AND matricula_status.data_fim';
 
        $this->criteria()->join('matricula_status', $criterio, array())
                         ->where('matricula_status.status LIKE ?', $status);
 
        return $this;                          
    }
}

O interessante neste caso é que o método noCurso referencia e utiliza um critério do catálogo de cursos, mas retorna o próprio catálogo de matrículas. Isso foi necessário por conveniência na gramática para manter o fluxo no mesmo contexto. Mais detalhes podem ser vistos no antigo post sobre problema do contexto nas Fluent Interfaces.

E finalmente o método atualmenteComStatus adiciona um critério à query. Esse ponto tem mais a ver com a Zend Db do que com a lógica da DSL em si.

Os demais catálogos estão disponíveis na demonstração.

Uma vez com os catálogos criados, é preciso reuní-los para montar a gramática. Como o conjunto de catálogos tende a ser o mesmo em todo o sistema, parece interessante estender a classe dessa forma:

class Catalogo_Grammar extends DslCatalog_Parser_Grammar
{
    public function __construct()
    {
        $this->addCatalog('Catalogo_Alunos');
        $this->addCatalog('Catalogo_Cidades');
        $this->addCatalog('Catalogo_Cursos');
        $this->addCatalog('Catalogo_Matriculas');
    }
}

Passo 3 de 3: Criando a interface do usuário

Considerando a consulta do usuário em uma string qualquer (por exemplo vinda de um formulário), basta instanciar o parser e adicionar a ele a gramática que criamos logo acima.

A partir daí é possível interpretar a consulta e receber um catálogo que pode ser iterado e ter seus objetos mostrados na tela:

$consulta = 'alunos matriculados no curso letras';
 
$gramatica = new Catalogo_Grammar();
 
$parser = new DslCatalog_Parser();
$parser->setGrammar($gramatica);
 
$catalogo = $parser->parse($consulta);
 
foreach ($catalogo as $item) {
    echo $item, '<br />';
}

Para deixar a caixa de texto da consulta com autocomplete, o script dslcatalog.js deve ser incluído junto com a estrutura da gramática:

<form method="get" action="index.php">
<p>
    <input type="text" id="q" name="q" value="" />
    <input type="submit" />
</p>
</form>
 
<script type="text/javascript" src="dslcatalog.js"></script>
<script type="text/javascript">
    var gramatica = <?php echo $gramatica->getJson() ?>;
 
    new DslCatalog.AutoComplete(document.getElementById('q'), gramatica);
</script>

Na aplicação de exemplo, a gramática foi deixada em um script separado com o objetivo de ficar no cache do navegador. Falando em cache, atualmente nenhuma camada da biblioteca tem essa preocupação, mas com o tempo isso tende a melhorar.

Download

A biblioteca com a aplicação de exemplo na revisão 39 está disponível no link abaixo, já incluindo as classes necessárias do Zend Framework. É só baixar e acessar o caminho demo/public/index.php.

http://dslcatalog.googlecode.com/files/dslcatalog-r39.zip
ou
http://dslcatalog.googlecode.com/files/dslcatalog-r39.tar.gz

Para a demonstração, o único requisito é que o PDO esteja habilitado com o driver SQLite. Caso receba a mensagem The sqlite driver is not currently installed, basta instalar a extensão pelo pecl:

Uma vez instalada, algum dos arquivos do php.ini deve conter extension=pdo_sqlite.so. Depois é só reiniciar o Apache.

Testes

Se alguém puder testar para tentar levantar possíveis sugestões seria legal. E se der algum problema é só falar.

Alguns dos recursos já planejados incluem:

• outra camada de acesso ao banco quando a Zend Db se mostrar limitada;
• catálogos de agregação com possibilidade de agrupamento para consultas como total de alunos matriculados por curso e cidade;
• parâmetros por widgets configuráveis (consulta de datas em um calendário, consulta de cursos em um combo pré-definido, etc);
• item dos catálogos mostrados em seus respectivos widgets;
• melhorar o autocomplete;
• e por aí vai…

E por enquanto eu fico devendo os testes de unidade, foi pura falta de habilidade mesmo. Mas já serão providenciados.

No post sobre Fluent Interface no PHP foi apresentada uma API que terminou assim:

O banco de dados estava estruturado com as tabelas de aluno, cidade, matrícula e curso. Como a relação do aluno com o curso é através da tabela de matrícula, foi necessário um catálogo extra para adicionar o critério sem quebrar o significado dos métodos.

Para o critério do nome da cidade do aluno como chave estrangeira, bastou realizar um JOIN a partir do próprio método e continuar o fluxo no catálogo de alunos.

Neste caso é um critério simples, mas é comum acontecer o contrário, como no caso em que o aluno tem vínculo com a tabela de matrículas e esta tem vínculo com a tabela de cursos.

Poderia ser criado um método matriculadosNoCurso($curso) que fizesse JOIN nas duas tabelas, mas não seria uma prática adequada, já que o catálogo de alunos estaria assumindo uma responsabilidade do contexto de matrículas, o que em breve levaria à repetição de código.

O ideal é permitir que catálogos tenham referências entre si. O critério do nome do curso passa para o catálogo de matrículas que poderá ser associado com o catálogo de alunos.

Agora falta relacionar o catálogo de matrículas com o catálogo de alunos.

Passando o contexto para outro objeto

Começando de fora pra dentro, o catálogo de alunos precisa passar o contexto para o catálogo de matrículas para que a interface possa utilizar os seus métodos.

O método _reference é herdado da classe Catalogo_Abstract e é responsável por instanciar e retornar o catálogo desejado.

Os catálogos são mapeados em um array para que a referência não seja feita mais de uma vez a partir do mesmo objeto.

Ao instanciar o objeto, o próprio catálogo é passado como argumento para o construtor, e é nessa etapa que o relacionamento será realizado.

Aceitando a referência

Ao receber uma referência no construtor, três procedimentos precisam ser feitos:

1. guardar no array de referências o objeto passado;
2. utilizar o mesmo select, já que a query é só uma;
3. fazer JOIN entre as tabelas.

Para associar os catálogos é necessário saber o critério que os relaciona. Apesar de no Zend Framework essa informação estar disponível no reference map, parece que ainda não há uma forma automática de relacionar duas classes Zend_Db_Table. Como o uso do framework não é o foco, os detalhes serão dispensados.

Acompanhando o código:

Voltando ao contexto anterior (até porque voltar ao próximo é mais complicado)

O catálogo de alunos já se relaciona com o de matrículas, mas uma vez no contexto de matrículas, ainda não é possível voltar a utilizar os critérios de alunos.

Observando a consulta em português puro, é correto afirmar que a lista se trata de “alunos matriculados no curso Enfermagem em que os alunos sejam da cidade do Rio de Janeiro”.

Assim como o método “matriculados” serve como ligação semântica entre os alunos e suas matrículas, nada mais justo que criar um método para a ligação “em que os alunos sejam”.

Os três novos métodos fazem a mesma coisa e existem para deixar a chamada mais natural. Dessa forma, fica transparente iniciar a consulta pelo catálogo de matrículas e filtrar por $matriculas-> dosAlunos()-> daCidade(‘Rio de Janeiro’), ou voltar para o contexto de alunos e aplicar um método de estado, como $matriculas-> emQueOsAlunosEstejam()-> desativados().

De certa forma a escolha das palavras foi tendenciosa. A frase talvez devesse ser “alunos matriculados no curso Enfermagem que sejam da cidade Rio de Janeiro”, mas nesse caso seria difícil determinar o contexto a qual “que sejam” se refere, principalmente se a consulta iniciar pelo catálogo de matrículas.

Quando as chamadas começam pelo catálogo de alunos e seguem pelo método matriculados, o método dosAlunos não precisa instanciar o catálogo de alunos, porque o construtor já o adicionou como referência no array _references.

Quando mudar de contexto

Ao filtrar pela cidade do aluno ou pelo curso da matrícula, o JOIN foi feito no mesmo método e o contexto não mudou. Esta decisão foi totalmente baseada na prática.

Olhando a API, não era necessário ter algo como $alunos-> daCidade(‘Rio de Janeiro’)-> emQueOsAlunosEstejam()-> emOrdem(), porque a partir dos alunos não haveria nenhum critério específico das cidades.

De qualquer forma, pode ser interessante criar um catálogo de cidades e utilizá-lo ao filtrar os alunos, mesmo não mudando de contexto.

Com um catálogo próprio fica natural iniciar a consulta pelo contexto de cidades, possibilitando algo como $cidades-> comAlunos()-> matriculados()-> noCurso(‘Psicologia’).

Exemplo completo

Publiquei os testes no link abaixo, incluindo as classes necessárias do Zend Framework e SQL de amostra utilizando SQLite na memória. É só baixar e executar o index.php.

Código fonte navegável
Exemplo para download

Esses dias testei o uso de Fluent Interface para consulta de dados de forma semântica, tentando criar uma API legível e reutilizável que eventualmente servisse diretamente ao usuário.

Em uma API comum, uma classe de negócio tem diversos métodos que retornam uma lista de acordo com diferentes critérios. As consultas ficam próximas do seguinte:

Em um sistema real são muitas as variações de critérios e a classe acaba crescendo em quantidade de código e dificuldade de uso e manutenção.

A proposta é eliminar a necessidade de um método para cada tipo de consulta. Os critérios apenas configuram a consulta que será realizada uma única vez quando necessário, possibilitando que esses critérios de busca funcionem independentemente.

As chamadas passam a ser realizadas assim:

Para conseguir esta API é preciso:

1. encadear os métodos
2. ter a possibilidade de configurar a query dinamicamente
3. identificar quando a configuração termina para então realizar a consulta.

Ainda que existam outras técnicas para refatorar a primeira API, o uso de Fluent Interface é um avanço significativo até a implementação de Domain Specific Language para uso do usuário.

Method Chaining

O primeiro passo é perceber a simplicidade do encadeamento de métodos. Geralmente as propriedades de uma classe são definidas por métodos setters que não retornam nada. O objetivo é retornar o próprio objeto a partir de cada um desses métodos.

Esta técnica por si só apenas reduz a quantidade de código uma vez que não precisamos repetir a instância do objeto para cada setter.

Fluent Interface

Feito o encadeamento, é necessária uma mudança conceitual. O ponto principal é que a nomenclatura dos métodos deixe que a interface flua naturalmente.

Renomeando os métodos e retornando o próprio objeto é possível fazer a chamada de forma amigável:

Acima de tudo é importante manter consistência para que fique claro quais são as classes que trabalham com Method Chaining, evitando que o programador espere o próprio objeto como retorno equivocadamente.

Nestes exemplos será utilizado o prefixo Catalogo como tentativa de identificar essas classes. O uso de namespaces seria extremamente bem-vindo se a linguagem permitisse.

Montando a query

Diferente de uma API tradicional, os métodos anteriores devem apenas configurar o critério da consulta.

Mesmo sendo possível montar a SQL manualmente, uma camada de persistência que permita queries orientadas a objeto diminui muito a complexidade do código com o qual você precisa se preocupar. Os exemplos utilizam a modesta Zend_Db, mas uma biblioteca mais madura pode ser necessária no futuro.

Sobre o Zend Framework, basta saber que cada tabela é representada por uma classe que estende Zend_Db_Table_Abstract. Nessa classe, o método select retorna uma representação de SELECT na tabela, que pode ser configurada até o momento de executar a SQL.

Cada catálogo utilizará uma classe abstrata como base e implementará um método para identificar a tabela à qual está associado:

Desta forma já é possível combinar os métodos para consulta de alunos:

As últimas duas consultas resultariam na seguinte SQL:

Determinando o momento da consulta com SPL

Até então, os dois métodos do catálogo de alunos apenas configuram a consulta e retornam o próprio catálogo. Falta uma forma de executar a query.

Uma solução é adicionar um método consultar que vai utilizar a SQL gerada e retornar a lista de alunos. Esse método, contudo, não impressionaria em nada as gatinhas, sem contar que não fluiria tão bem se comparado a uma frase em português.

Tratando-se de um catálogo, espera-se dele uma lista de objetos que serão iterados em um loop. No cenário ideal, o código abaixo deve ser suficiente:

E esse de fato é o cenário real (Ohhh).

Para controlar a iteração de um objeto em um foreach, o PHP dispõe da interface Iterator da Standard PHP Library. Quando utilizada, é necessário implementar os seguintes métodos, que serão chamados nessa ordem:

1. rewind: reinicia a iteração;
2. valid: determina se a iteração deve continuar;
3. current: retorna o valor da iteração atual;
4. key: retorna o índice da iteração atual;
5. next: avança a iteração.

A consulta no Zend_Db retorna um objeto Zend_Db_Table_Rowset_Abstract, que já implementa a interface Iterator da SPL. Como a iteração no catálogo deve representar uma iteração neste rowset, basta direcionar os métodos para o objeto da consulta.

Para ficar mais claro como os métodos são chamados, vale a pena dar uma olhada nestes slides.

O problema do contexto

O filtro por cidade foi um exemplo simples para ilustrar o conceito de Fluent Interface, imaginando que exista a coluna cidade na tabela de alunos, sem chave estrangeira. No mundo real é mais complicado que isso.

No primeiro exemplo lá em cima, a proposta era filtrar os alunos matriculados no curso de Enfermagem, mas, na minha realidade, não existe vínculo direto entre curso e aluno, apenas pela tabela de matrícula.

A solução que encontrei foi criar um catálogo específico de matrículas que é instanciado pelo catálogo de alunos, já criando o relacionamento entre as duas classes, resultando em um JOIN entre as três tabelas.

Para evitar que este texto ficasse ainda mais longo, separei os detalhes em um post específico sobre problema de contexto nas Fluent Interfaces.

Domain Specific Language

Talvez ainda não pareça justificável todo o trabalho que uma Fluent Interface consistente vai gerar.

A grande vantagem só ficou clara pra mim quando o Eclipse começou a auto-completar os métodos dos catálogos. Se estou no catálogo de alunos, ele já mostra o filtro de cidade. Se eu escrevo a cidade, ele ainda permite filtrar pelos já matriculados. Uma vez na matrícula, posso filtrar pelo curso, e assim por diante.

Isso é o mínimo que se espera de uma IDE que ocupa tanta memória. Mas e se o usuário tivesse a mesma facilidade?

Ao invés de me ligarem falando “Garoto, preciso de uma lista de alunos da região norte inscritos essa semana no curso de Gestão em Saúde pelo edital da UAB que tenham blah blah blah”, a (quase) mesma fala seria digitada numa caixa de texto com auto-complete.

Não que o problema não possa ser resolvido com um formulário gigante incluindo todos os filtros de consulta possíveis, mas estamos falando de usabilidade. Interfaces amigáveis para o usuário, código amigável para o programador. Quem não achou o plugin Ubiquity minimamente interessante?

E pra quem concorda que digitar a busca nem sempre é a melhor opção, os catálogos seriam facilmente exportados para ambientes visuais. Combinados com ações específicas de cada entidade (como matricular aluno, aprovar inscrição, desativar tutor…), o código passa a ser extremamente plugável.

Para tornar isso possível, a idéia é utilizar reflexão nas classes e expor os métodos na interface do usuário. Assim que parar de fazer sol na praia e eu tiver algum tempo, vou tentar expandir estes exemplos para DSL externa. O post de Domain Specific Language externa no PHP demonstra a implementação.

De qualquer forma, no fundo vou sentir falta das tais ligações.

Exemplo completo

Uma implementação mais recente, já com interface para consulta pelo usuário, está disponível no post sobre Domain Specific Language externa.

Referências

• Martin Fowler – Fluent Interface
  http://martinfowler.com/bliki/FluentInterface.html
• Post de Guilherme Chapiewski que clareou minhas idéias sobre Fluent Interface
  http://gc.blog.br/2007/09/25/refatorando-para-fluent-interface/
• Zend Framework – Documentação da Zend_Db
  http://framework.zend.com/manual/en/zend.db.html
• Documentação da Standard PHP Library no PHP
  http://www.php.net/~helly/php/ext/spl/
• Resolvendo problema de contexto nas Fluent Interfaces
  http://garotosopa.wordpress.com/contexto-fluent-interface
• Câmera pra ver se está sol na praia
  http://transito.rio.rj.gov.br/imagens1/31.jpg

Em 1995 a Netscape^[1] teve a idéia de utilizar respostas HTTP multipart como implementação de server push, onde o servidor envia múltiplas respostas a uma mesma requisição. Treze anos depois eu me dei conta que esse streaming de dados realmente torna aplicações web muito mais dinâmicas, caracterizando o que alguns chamam de Comet^[2].

Outras opções para aplicações dinâmicas incluem deixar um iframe carregando tags Javascript eternamente; abrir uma conexão XMLHttpRequest a cada intervalo de tempo; ou implementar Long Polling, onde o servidor segura a conexão enquanto não houver conteúdo novo e, quando a resposta for enviada, um novo XMLHttpRequest é criado pelo navegador.

O grande conceito de server push é o servidor poder se comunicar com o cliente em tempo real sem que o navegador tenha que ficar pedindo atualizações. Nenhuma das soluções acima consegue atingir o estado da arte neste ponto.

Multipart

O conceito de multipart é o mesmo que utilizamos em e-mails MIME^[3], como quando enviamos e-mails com anexo. Um cabeçalho deve ser enviado definindo que o tipo da resposta é com várias partes separadas por um delimitador (boundary):

Content-type: multipart/mixed; boundary="delimitador"

E então cada uma das partes fica entre este delimitador, acompanhada do seu próprio content-type:

--delimitador
Content-type: text/plain
 
Primeira mensagem
--delimitador
Content-type: text/plain
 
Segunda mensagem
--delimitador
Content-type: text/plain
 
Mensagem final
--delimitador--

O delimitador é iniciado por dois hífens e o último deles também termina com dois hífens, indicando o final do conteúdo. Sem este último delimitador, o cliente vai ficar esperando por outras partes até que os dois hífens depois do delimitador indiquem o final do conteúdo.

Javascript

A diferença no Javascript para receber respostas multipart é apenas um parâmetro extra no objeto XMLHttpRequest:

var xhr = new XMLHttpRequest();
xhr.multipart = true;
xhr.open('GET', 'script-multipart.php', true);
xhr.onreadystatechange = function(){
    if( this.readyState == 4 && this.status == 200 ){
        document.body.innerHTML = this.responseText;
    }
};
window.onload = function(){ xhr.send(null); }

Quando configurado para respostas multipart, a requisição é dada como concluída pra cada uma das partes recebidas. A propriedade readyState recebe o valor 4 (Loaded) e o evento onReadyStateChange é disparado. A parte carregada vai estar disponível em responseText, da mesma forma que em requisições normais.

Se o XMLHttpRequest estiver configurado para multipart, é importante que o servidor responda como multipart e vice-versa.

Servidor

No servidor é necessário enviar o cabeçalho HTTP para definir o tipo de resposta como multipart. Mas diferente das mensagens MIME, o tipo de conteúdo multipart no HTTP é multipart/x-mixed-replace. A partir daí basta respeitarmos a saída com os delimitadores.

<?php
set_time_limit(0);
    
header('Content-type: multipart/x-mixed-replace;boundary="delimitador"');
echo "--delimitador\n";
    
while( true ){
    echo "Content-type: text/plain\n\n";
    
    echo date("d/m/Y H:i:s"), "\n";
    
    echo "--delimitador\n";
    flush();
    
    sleep(1);
}

Ao acessar o script acima pelo navegador já é possível ver as partes sendo trocadas na tela (daí o tipo replace).

O time limit foi desabilitado para que o script fique em execução enquanto o cliente estiver conectado. Sem ele, pela configuração normal do PHP, o script daria timeout em 30 segundos.

O content-type principal (multipart/x-mixed-replace) foi enviado com a função header por fazer parte dos response headers da requisição HTTP. Já os content-type’s de cada mensagem são enviados como saída normal, pois fazem parte do conteúdo como um todo, e não dos cabeçalhos HTTP. Para diferenciar o cabeçalho do conteúdo em si, ele deve ser terminado com uma linha em branco (\n\n). Caso não seja necessário o envio de nenhum cabeçalho, é importante ter uma linha vazia entre o delimitador e o conteúdo.

Assim que cada parte é montada, é preciso ter certeza que ela será enviada ao cliente ao invés de ficar no buffer do PHP. Dependendo do seu ambiente, pode ser necessário o uso da função ob_flush() em conjunto com flush()^[4].

Problemas

Somente Gecko

Até o momento, a interpretação de multipart pelo XMLHttpRequest está disponível apenas em navegadores que utilizam a engine Gecko, como o Firefox, por exemplo. Para manter o código compatível com outros browsers é possível checar o suporte com if( xhr.multipart != null ) e implementar outra solução como contingência. Uma boa saída é utilizar multipart nos navegadores que o suportarem e long polling nos demais.

if( window.XMLHttpRequest ){
    var xhr = new XMLHttpRequest();
}else if( window.ActiveXObject ){
    var xhr = new ActiveXObject('Microsoft.XMLHTTP');
}
function iniciar(){
    xhr.abort();
    if( xhr.multipart != null ){
        xhr.multipart = true;
        xhr.open('GET', 'script-multipart.php?multipart', true);
    }else{
        xhr.open('GET', 'script-multipart.php', true);
    }
    xhr.onreadystatechange = ler;
    xhr.send(null);
}
function ler(){
    if( xhr.readyState == 4 ){
        if( xhr.status == 200 ){
            document.body.innerHTML = xhr.responseText;
        }
        if( ! xhr.multipart ){
            iniciar();
        }
    }
}
window.onload = iniciar;

<?php
set_time_limit(0);
if( isset($_GET['multipart']) ){
    header('Content-type: multipart/x-mixed-replace;boundary="delimitador"');
    echo "--delimitador\n";
}
while( true ){
    if( isset($_GET['multipart']) ){
        echo "Content-type: text/plain\n\n";
    }
 
    echo date("d/m/Y H:i:s"), "\n";
 
    if( isset($_GET['multipart']) ){
        echo "--delimitador\n";
        flush();
        sleep(1);
    }else{
        sleep(1);
        exit();
    }
}

Controle de falha

Nestes exemplos, o script nunca terminará a requisição e o navegador vai ficar esperando novas partes enquanto a página estiver aberta. Essa é realmente a idéia. Contudo, é possível que a execução do script ou a conexão com o servidor seja interrompida inesperadamente.

Como o navegador não recebeu a indicação do fim da resposta multipart (delimitador seguido de dois hífens), o XMLHttpRequest vai ficar esperando novas partes sem que haja qualquer aviso de erro ou timeout. Uma solução razoável é implementar o controle de timeout manualmente:

var xhr = new XMLHttpRequest();
var t;
function iniciar(){
    xhr.abort();
    xhr.multipart = true;
    xhr.open('GET', 'script-multipart.php', true);
    xhr.onreadystatechange = ler;
    xhr.send(null);
    contarTimeout();
}
function ler(){
    if( xhr.readyState == 4 && xhr.status == 200 ){
        contarTimeout();
        document.body.innerHTML = xhr.responseText;
    }
}
function contarTimeout(){
    clearTimeout(t);
    t = setTimeout(iniciar, 5000);
}
window.onload = iniciar();

FastCGI buffer

Um problema que não consegui resolver foi o buffer do FastCGI. Por mais que o script faça flush e ob_flush, parece que o FastCGI mantém um buffer intocável. Neste caso essa solução não funcionaria.

No meu host, eu tenho a alternativa de executar scripts diretamente como CGI. Ao invés de ter um arquivo com extensão .php, criei o script com extensão .cgi e coloquei #!/usr/bin/php na primeira linha. Esta solução funcionou para testes, mas em produção é melhor procurar outra saída, como utilizar mod_php ou até mesmo uma forma de desabilitar o buffer do FastCGI.

Chat em PHP

Eu já tinha publicado um Chat em PHP utilizando Long Polling^[5] e acabei reescrevendo parte dele para utilizar XMLHttpRequest com requisição multipart.

Assim como no último o exemplo, o Javascript faz o controle manual de timeout. Para evitar reconexões quando ninguém mandar mensagem por muito tempo, o servidor envia um ping de tempos em tempos para manter a conexão ativa. Em navegadores que não utilizam a engine Gecko, a solução de Long Polling é utilizada.

Código fonte:
http://code.google.com/p/chatildis/source/browse/trunk/chat-multipart.php?r=10

Script para download:
http://chatildis.googlecode.com/files/chat-multipart.php

Da mesma forma que o chat anterior, esta implementação ainda utiliza o MySQL com tabela na memória para repassar as mensagens para todos os clientes. Este método está longe do ideal. Talvez em uma próxima ocasião eu tente alguma coisa com threads e Observer Pattern.

Referências

1. An exploration of dynamic documents
2. Comet (programming)
3. Multipurpose Internet Mail Extensions (MIME), Multipart messages
4. PHP: flush – manual
5. Chat PHP com XHR Long Polling

Esses dias surgiu a questão da melhor forma de notificar o usuário sobre alterações no servidor em tempo (quase) real, como novas mensagens de um chat, por exemplo.

A forma mais intuitiva pra mim seria fazer requisições XMLHttpRequest em pequenos intervalos, checando por mensagens mais novas que a última mensagem já recebida. Este método, entretanto, desperdiçaria muitas requisições se o intervalo fosse muito curto ou comprometeria a experiência do usuário se o intervalo fosse maior.

A idéia proposta é manter uma única conexão XHR aberta enquanto o servidor não responder com uma mensagem nova. Uma vez que exista mensagens novas, o cliente processa a resposta e em seguida cria uma nova conexão XHR que permanecerá aberta até a próxima resposta. Dessa forma o cliente fará no máximo 1 requisição por mensagem.

Depois eu acabei descobrindo que esta é a implementação de XMLHttpRequest long polling.

O código funciona da seguinte forma:

Ajax:
    url: 'chat.php?ultimo_id=' + ultimo_id
    success:
        processar retorno json
        guardar ultimo_id
    complete:
        executar requisição novamente
PHP:
    Loop infinito:
        consultar mensagens mais novas que ultimo_id
        se houver mensagens:
            escrever mensagens em json
            parar o loop para o cliente ler o json

Funcionou muito bem em rede local com 16 clientes, cada um enviando uma mensagem por segundo. As mensagens ficaram no MySQL numa tabela na memória com Query Cache habilitado e não tive problemas com processamento do banco, ficando sempre abaixo de 6%. O Apache também não sofreu sobrecarga, tendo no máximo 3% de CPU em cada um dos 3 processos.

Sem dúvida esta implementação tem menos overhead que requisições em pequenos intervalos. Melhor que isso somente a implementação de streaming com XMLHttpRequest, que não fecharia a conexão a cada mensagem nova, mas isso fica pra depois utilizando requisições multipart.

Código-fonte:
http://code.google.com/p/chatildis/source/browse/trunk/chat.php?r=7

Script para download:
http://chatildis.googlecode.com/files/chat.php

Recentemente, precisei migrar alguns relatórios CSV para XLS, de forma que pudessem ser abertos diretamente no Excel sem aquelas telas chatas de importação de dados. Utilizei a classe Spreadsheet_Excel_Writer do PEAR e o resultado foi melhor do que o esperado.

Criando planilhas

O arquivo do Excel é organizado em uma pasta de trabalho (workbook) onde ficam uma ou mais planilhas (worksheets). O código PHP seguirá a mesma lógica, instanciando a pasta de trabalho e adicionando a ela um objeto para cada planilha. As planilhas poderão ser preenchidas conforme a posição da linha e coluna, ambas começando do zero.

Observe que a planilha foi adicionada utilizando o operador de referência &. No PHP 4 isto é necessário para que a variável $worksheet deste escopo represente efetivamente a planilha dentro da pasta de trabalho $workbook. Do PHP 5 em diante este recurso não é necessário, já que variáveis apontam sempre para o mesmo objeto (exceto, claro, quando propositalmente clonados).

void Worksheet::write ( integer $row , integer $col , mixed $token , mixed $format=0 )

• integer $row – número da linha onde escrever (começando do 0)
• integer $col – número da coluna onde escrever (começando do 0)
• mixed $token – conteúdo da célula
• mixed $format – opcional, especifica a formatação da célula

O método write tenta identificar o tipo do conteúdo como texto, número, link, fórmula ou vazio. Esta identificação automágica acabou me levando a um resultado inesperado ao preencher células com número de CPF, já que alguns começavam com zero e, ao serem convertidos de texto para número, acabaram tendo os primeiros dígitos removidos. Para ter certeza do formato da célula, é possível utilizar diretamente as demais funções de escrita:

• writeBlank para escrever uma célula vazia, útil para formatar o estilo sem especificar valor
• writeFormula para escrever uma fórmula, da mesma forma que seria feito no Excel
• writeNumber para escrever um número
• writeString para escrever um texto livre
• writeUrl para escrever um link; o texto visível pode ser especificado no quarto parâmetro e a formatação, se alguma, no quinto parâmetro

Como a identificação de tipo pelo método write é feita com uma série de expressões regulares, utilizar os métodos de escrita para determinado tipo pode melhorar o desempenho do script com planilhas muito grandes.

Além da escrita por célula, é possível preenchermos toda uma linha ou coluna a partir de um array. Estes métodos são especialmente úteis para preencher a planilha a partir de uma consulta ao banco de dados:

mixed Worksheet::writeRow ( integer $row , integer $col , array $val , mixed $format =null )

• integer $row – número da linha onde escrever
• integer $col – número da coluna onde começar a escrever os valores
• array $val – valores das células que serão escritas na linha
• mixed $format – opcional, especifica a formatação da célula

mixed Worksheet::writeCol ( integer $row , integer $col , array $val , mixed $format =null )

• integer $row – número da linha onde começar a escrever os valores
• integer $col – número da coluna onde escrever
• array $val – valores das células que serão escritas na coluna
• mixed $format – opcional, especifica a formatação da célula

Formatando a célula

Enquanto eu migrava alguns relatórios para XLS, percebi que outra grande novidade pro usuário em comparação à importação de CSV seria melhorar o visual da planilha. A formatação de estilo é adicionada à pasta de trabalho e em seguida associada às células que receberão o estilo.

O estilo adicionado define um tom claro de cinza para o fundo e a fonte em negrito. O Excel utiliza uma paleta de cores própria; para adicionar uma cor diferente, o método setCustomColor deve ser utilizado, passando o índice da cor como primeiro argumento (que será utilizado para identificar a cor em funções como setFgColor e setColor) e os níveis RGB como segundo, terceiro e quarto argumentos, respectivamente.

Também é possível passar um array com as configurações diretamente para o método addFormat:

Todas as opções de formatação podem ser vistas na documentação do addFormat.

Não vi nenhuma forma de deixar as colunas com largura automática, como quando damos dois cliques no divisor de colunas e a largura é reajustada automaticamente, mas o método setColumn pode ser utilizado para determinar uma largura fixa para um conjunto de colunas.

void Worksheet::setColumn ( integer $firstcol , integer $lastcol , float $width , mixed $format=0 , integer $hidden=0 )

• integer $firstcol – primeira coluna do intervalo onde aplicar a formatação
• integer $lastcol – última coluna do intervalo
• float $width – largura das colunas
• mixed $format – opcional, especifica a formatação da célula
• integer $hidden – define se as colunas devem estar ocultas

Enviando para download

Uma vez que a pasta de trabalho esteja montada, basta enviar o header com o tipo de conteúdo e o nome do arquivo adequados para que o browser faça o download corretamente.

O método send envia os headers necessários e o close carrega o arquivo binário.

Instalando a classe

A instalação da classe é feita pelo próprio PEAR, com o detalhe de resolver as dependências necessárias e especificar que a classe ainda está em estado beta:

Como utilizei a classe na intranet, o comando pôde ser executado como root pelo administrador do servidor para instalar a classe no sistema. Veja o link Installation of a local PEAR copy on a shared host para instruções de como utilizar classes PEAR em servidores compartilhados.

Documentação

Veja ainda a documentação da classe Spreadsheet_Excel_Writer para mais detalhes sobre diversos outros recursos.

Variáveis globais são aquelas definidas na raiz do script, fora de qualquer outro escopo, e que não existem dentro de uma função ou método, da mesma forma que variáveis criadas em um desses escopos deixarão de existir fora dele.

As variáveis superglobais, entretanto, podem ser acessadas em qualquer escopo, e são elas $GLOBALS, $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES, $_ENV, $_REQUEST e $_SESSION. Acontece que não é possível definir uma outra variável como superglobal (ao menos não sem o uso da Runkit), e aí a confusão começa.

A partir de um escopo, para declarar que uma variável pertence ao escopo global, utiliza-se a keyword global dentro desse escopo, mesmo que a variável ainda não tenha sido definida, quando nesse caso passará a existir se definida pela função.

<?php
$chamadas = 0;
 
function carregar(){
 global $chamadas, $artista;
 
 $chamadas++;
 $artista = "Whitesnake";
}
 
carregar();
echo $artista, " - ", $chamadas; // Whitesnake - 1
?>

Contudo, são inúmeras as vezes que observei o uso incorreto do global, fora de qualquer escopo, com o objetivo de tornar a variável uma superglobal. Mas na realidade, além de constatar o óbvio declarando que uma variável global pertence ao próprio escopo global, isso simplesmente não funciona e obriga o desenvolvedor a utilizar a keyword global novamente dentro do escopo onde deseja ter o acesso.

O diagrama acima evidencia as superglobais na direita, acessíveis de qualquer lugar, as variáveis ao fundo limitadas aos seus respectivos escopos e, compondo a linha de frente, as variáveis globais, existentes ao longo do script e que podem ser utilizadas em um determinado escopo com o uso da keyword global. Então mesmo que você chame sua variável de Docinho, ela não vai se tornar uma superglobal.

Outra maneira de utilizar variáveis globais é pela superglobal $GLOBALS, uma array associativa com referência às variáveis no escopo global.

É importante observar ainda que, de uma forma geral, variáveis globais são uma causa comum de problemas, já que você não sabe se o valor é realmente o que você espera que seja. Um método simples de evitar isso é passar as variáveis necessárias como parâmetro para a função ou objeto que vai utilizá-las.

Eu só consegui perceber o problema de confiar em variáveis globais com a ajuda da minha mãe. Certa vez ela deixou um pudim delicioso na geladeira, e na manhã seguinte colocou uma travessa de peixe na prateleira de baixo. Pronto, o pudim ficou com gosto de sardinha o resto da semana. E foi assim que eu aprendi que devo separar minhas varáveis em lugares seguros, evitando que fatores externos acabem estragando tudo sem que eu sequer perceba.

E pra ficar claro, o que foi abordado nada tem a ver com o uso da diretiva register_globals que, quando ativada, define o conteúdo de $_ENV, $_GET, $_POST, $_COOKIE e $_SERVER como variáveis globais. Então $_POST['nome'] também passa a existir como $nome, $_GET['pagina'] também como $pagina, e assim por diante. Este terrível fenômeno está desativado por padrão desde a versão 4.2 e será removido por completo no PHP 6.

Referências

• Escopo de variáveis
• Superglobais predefinidas
• (Não) Utilizando a diretiva Register Globals
• Ferramenta case utilizada no diagrama de escopo de variáveis

Eu considero o ano de 2004 como sendo o ápice da quantidade de dúvidas sobre a mensagem Headers already sent, quando era comum muitos usuários perguntarem a solução diariamente no IRC. Um saco. Ainda hoje o Google retorna quase 2 milhões de resultados para esse termo, e a maioria deles como sendo erros legítimos que o crawler encontrou enquanto navegava.

Para entender o problema é preciso compreender um pouco como funciona a comunicação HTTP. Quando é feita uma requisição ao endereço http://meudominio/caminho/script.php, o navegador conecta na porta 80 do servidor meudominio e envia um cabeçalho (Request headers) semelhante a este seguido de uma linha em branco:

GET /caminho/script.php HTTP/1.1
Host: meudominio

O servidor recebe essa requisição, nesse caso chama o PHP para interpretar o script, e responde, começando pelo cabeçalho (Response headers), seguido de uma linha em branco e o conteúdo da resposta, se houver:

HTTP/1.1 200 OK
Date: Mon, 18 Jun 2007 05:49:07 GMT
Server: Apache
Transfer-Encoding: chunked
Content-Type: text/html; charset=ISO-8859-1
 
<html>
<body>
Oi mundo.
</body>
</html>

Cada uma das primeiras linhas representa um cabeçalho (header) e começa mostrando o status da resposta (tal como sucesso, não encontrado, erro interno, etc) além de informações como tempo de expiração, encoding, cookies, entre outras.

A mensagem de erro Headers already sent ocorre porque o script tenta enviar um header após o trecho destinado a eles já ter sido enviado ao cliente por razão do conteúdo da resposta ter começado, seja ele HTML, texto, mensagens de erro e até mesmo linhas em branco ou comentários fora das tags do PHP.

O mais comum é ter problemas com as funções setcookie, porque o cookie é enviado ao cliente no cabeçalho da resposta, session_start, por precisar enviar um cookie para iniciar a sessão, e, obviamente, com a função header em si, que é muito utilizada para redirecionar o usuário para outro endereço.

A resposta definitiva para o problema é mudar a disposição do script de forma que os headers necessários sejam realmente enviados antes da apresentação HTML, que é a forma natural do modelo MVC. Quando isso não é possível, ou é difícil de ser mudado, é um sinal claro de que o script está mal estruturado, uma vez que toda a lógica deve ocorrer antes, e não misturada com o que o usuário está vendo.

O modelo inapropriado da aplicação fica ainda mais evidente quando o erro ocorre com o header Location, usado para redirecionamento. Chega a ser desperdício de recursos e banda, além de não fazer nenhum sentido, enviar um trecho HTML, ou qualquer tipo de conteúdo, se o browser deve seguir pra outra página sem mostrar nada na tela.

Em função disso surgiu também o mito de colocar funções que enviam um header na primeira linha do script, em especial a session_start, o que não é exatamente verdade. A necessidade essencial é de utilizá-las antes de qualquer saída (output) ao usuário, não importando exatamente onde no script, desde que nada tenha sido enviado ainda.

De qualquer forma, o PHP possui o recurso de Output Buffering que armazena a saída em um buffer e envia o conteúdo ao cliente de uma só vez (ou em pedaços determinados, dependendo do tamanho do buffer), e é aí que a ilusão de muitos começa.

Quando utilizado de forma adequada para o propósito adequado, o Output Buffering é extremamente benéfico em termos de desempenho, pois diminui o número de vezes que ocorre a comunição PHP – Servidor Web – Sistema Operacional – Rede – Usuário. Outros usos comuns são na compressão da saída em Gzip, para diminuir o consumo de banda, e ao encapsular a saída em uma string, como por exemplo em alguma técnica de template.

Todavia esse recurso costuma ser utilizado indevidamente por desenvolvedores esotéricos, que têm a função ob_start como varinha mágica para os mais diversos tipos de bruxaria. Uma vez que o conteúdo passa a ficar em um buffer, aquele início da resposta HTTP não terminou, ainda existindo então a possibilidade de enviar headers, seja ele um cookie, início de sessão ou até mesmo redirecionamento.

Mas que fique claro que contar com Output Buffering como mágica para enviar headers no meio da apresentação é apenas concordar com a péssima estrutura montada.

Referências

• O protocolo HTTP
• Controle de saída
• Funções ob_start, session_start, setcookie e header
• Accelerating PHP Code Performance for Oracle, artigo de Ilia Alshanetsky que menciona o uso de output buffering

Recentemente, precisei de um banco de dados de provérbios e fiz um singelo script para ler alguns sites, mas era chato ter que fazer um script inteiro ou aglomerar laços pra cada site que eu encontrava. Pra evitar repetição de código, mantive uma classe por site, que, em conjunto com as classes e interfaces da Standard PHP Library (SPL), resumiram o código final a um único foreach:

$proverbios = new Proverbios;
$proverbios->append(new Proverbios_LifesABirch);
$proverbios->append(new Proverbios_Aborla);
$proverbios->append(new Proverbios_JangadaBrasil);

foreach($proverbios as $proverbio){
    echo $proverbio, “\n”;
}

Iterator

Para que isso fosse possível, cada classe implementou a interface Iterator disponível na extensão SPL, assumindo o comportamento de um iterador e podendo então ser utilizada normalmente em um loop.

O papel de uma interface é definir o que um objeto deverá ser capaz de fazer, e essa define o seguinte:

interface Iterator extends Traversable
{
function rewind();

function valid();
}

Então, todo objeto a ser utilizado como iterador precisa ter esses métodos implementados, que são executados na seguinte ordem durante um foreach:

1. rewind() – recomeça a iteração, reiniciando um possível índice interno;
2. valid() – este método deve retornar true para continuar, ou false quando não houver mais iteração;
3. current() – retorna o valor atual;
4. key() – retorna o índice atual e somente é executado caso a chave seja pedida, como em foreach($it as $key => $value);
5. next() – deve mover o índice interno para a próxima iteração;
6. Volta ao passo número 2.

ArrayIterator

No primeiro site, a busca foi apenas uma expressão regular que retornava os provérbios em uma array que seria lida depois em um loop.

Como a iteração em array é bastante óbvia, a SPL dispõe da classe ArrayIterator, que já implementa as interfaces ArrayAccess, Countable e SeekableIterator, que por sua vez estende a Iterator, sendo esta última a única que interessa no momento.

A classe recebe uma array ou objeto no constructor, e tem o mesmo resultado como se estes elementos fossem utilizados diretamente em um foreach. Se a ArrayIterator não existisse, seria necessário implementar a interface Iterator e manipular a array manual e repetidamente onde fosse necessário.

class Proverbios_LifesABirch extends ArrayIterator
{
    public function __construct()
    {
        $url = 'http://www.lifesabirch.org/proverbios/index.php';
        
        $contents = file_get_contents($url);
 
        preg_match_all('/^(?:<\/?p>)?(\S.+) <br\/>$/mU',
            $contents, $matches);
 
        if(isset($matches[1]) && is_array($matches[1])){
            parent::__construct($matches[1]);
        }
    }
}

Ao instanciar esta classe, o constructor é executado, a leitura do site é efetuada e a array retornada é passada para o constructor da ArrayIterator. A partir daí, o objeto passa a ser, de certa forma, a própria array retornada pela expressão regular, onde cada item representa um provérbio do site.

A leitura poderia ser feita da seguinte forma:

foreach(new Proverbios_LifesABirch as $proverbio){
    echo $proverbio, "\n";
}

RecursiveIterator

O segundo site que encontrei estava dividido por letras, sendo necessário percorrê-las e retornar os provérbios de cada uma delas.

Em uma estrutura básica, existiria um loop para as letras e dentro dele um outro para os provérbios. Esta estrutura é fácil de ser percebida, mas difícil de ser integrada a um sistema maior sem que todos os provérbios sejam lidos antes e retornados depois em um único array.

Utilizando iteradores recursivos, é possível navegar por entre estas divisões sem nenhuma alteração no código final, que continua sendo um único foreach. A interface RecursiveIterator estende a Iterator e acrescenta dois métodos:

interface RecursiveIterator extends Iterator
{
    function hasChildren();
 
    function getChildren();
}

Durante a iteração, o método hasChildren() é chamado pra identificar se o item atual é ou não um iterador a ser percorrido. Caso seja, o iterador, que também deve implementar a interface RecursiveIterator, é recuperado pelo getChildren() e começa uma nova iteração a partir dele até que não haja mais itens. Quando isso acontece, o processo continua no próximo item do iterador anterior, ou é finalizado caso seja o principal. Se hasChildren() retornar false, então trata-se de um item normal e o current() é chamado para recuperar seu valor.

Na classe deste site foi usada uma array com as letras a serem percorridas, e pra cada uma delas, uma classe é retornada como filha.

Para percorrer arrays multi-dimensionais, existe a classe RecursiveArrayIterator, que verifica no método hasChildren() se o item atual é uma outra array e retorna no getChildren() uma nova instância de si mesma a partir dela, fazendo o efeito recursivo.

Nesse caso a RecursiveArrayIterator não poderia ser utilizada, porque a array de letras não é multi-dimensional. Ao invés dela, foi usada a própria ArrayIterator para percorrer a array, e implementada a interface RecursiveIterator manualmente para retornar o objeto dos provérbios de cada letra.

class Proverbios_Aborla_Letras 
    extends ArrayIterator implements RecursiveIterator
{
    public function __construct()
    {
        parent::__construct(array(
            'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'l',
            'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'z'));
    }
    
    public function hasChildren()
    {
        return true;
    }
    
    public function getChildren()
    {
        return new Proverbios_Aborla_Proverbios($this->current());
    }
}

RecursiveIteratorIterator

Diferente de um iterador sem filhos, a classe acima não poderia ser utilizada diretamente em um foreach, mesmo com a interface RecursiveIterator, porque ele apenas recupera o valor atual pelo método current(), e retornaria somente as letras a cada iteração.

Uma vez implementados os métodos hasChildren() e getChildren(), é preciso que eles sejam utilizados de fato, e quem faz uso deles é o iterador externo RecursiveIteratorIterator, que recebe o iterador recursivo como parâmetro no constructor e coordena a recursividade. Portanto, a classe principal deste site fica assim:

class Proverbios_Aborla extends RecursiveIteratorIterator
{
    public function __construct()
    {
        parent::__construct(new Proverbios_Aborla_Letras);
    }
}

E já que a classe RecursiveIteratorIterator executa o método hasChildren() em todos os elementos que passam por ela, o retorno de getChildren() deve obrigatoriamente implementar a interface RecursiveIterator pra garantir ao iterador externo que os métodos existem, mesmo que não seja recursiva, como é o caso da classe de provérbios:

class Proverbios_Aborla_Proverbios 
    extends ArrayIterator implements RecursiveIterator
{
    public function __construct($letra)
    {
        $url = "http://proverbios.aborla.net/p" . $letra . ".php";
        
        $contents = file_get_contents($url);
        
        $start = strpos($contents, '</h2><p>') + 8;
        $length = strpos($contents, '<br></p>') - $start;
        
        $array = explode('<br>', substr($contents, $start, $length));
        
        parent::__construct($array);
    }
    
    public function hasChildren()
    {
        return false;
    }
    
    public function getChildren(){}
}

De uma forma bastante semelhante à primeira classe feita, o conteúdo do site é lido no constructor, e os provérbios passados como array para o constructor do parent, que é a ArrayIterator. Por esse iterador nunca conter um filho, o método getChildren() foi somente declarado, já que não será chamado pelo RecursiveIteratorIterator, dado que o hasChildren() retorna sempre false.

foreach(new Proverbios_Aborla as $proverbio){
    echo $proverbio, "\n";
}

Acompanhando o código:

1. O foreach ocorre em um objeto da classe Proverbios_Aborla, que estende RecursiveIteratorIterator. Esse iterador externo recebe o iterador recursivo Proverbios_Aborla_Letras como parâmetro no constructor e começa a iteração;
2. A cada iteração em Proverbios_Aborla_Letras, o método hasChildren() é consultado pelo RecursiveIteratorIterator. Como o retorno é sempre true, o iterador filho é requisitado;
3. Ao chamar Proverbios_Aborla_Letras::getChildren(), uma nova instância de Proverbios_Aborla_Proverbios é criada para a letra da iteração atual e repassada para o iterador externo;
4. Ao ser instanciada, Proverbios_Aborla_Proverbios obtém os dados do site e os utiliza na ArrayIterator;
5. O iterador externo consulta o método hasChildren() na classe Proverbios_Aborla_Proverbios, que vai sempre retornar false;
6. Então o método Proverbios_Aborla_Proverbios::current(), estendido da ArrayIterator, é executado e retorna um provérbio da página lida do site;
7. O iterador externo repassa o provérbio para o foreach, disponibilizando-o no código final. Os passos 5, 6 e 7 se repetem até acabarem os provérbios e o método Proverbios_Aborla_Proverbios::valid() retornar false;
8. Quando isso acontece, o iterador externo avança com o método Proverbios_Aborta_Letras::next() que foi estendido da ArrayIterator, e recomeça o processo a partir do número 2 enquanto houver letras no primeiro iterador recursivo.

O último site que usei como fonte também exigiu iteradores recursivos, e precisou ainda de mais um nível de recursividade. Os provérbios estavam divididos em letras, e em cada uma delas havia paginação de resultados.

Os passos iniciais foram os mesmos, primeiro criando o iterador externo RecursiveIteratorIterator para percorrer as letras e seus filhos.

class Proverbios_JangadaBrasil extends RecursiveIteratorIterator
{
    public function __construct()
    {
        parent::__construct(new Proverbios_JangadaBrasil_Letras);
    }
}

A classe que representa as letras funciona da mesma forma que a do site anterior, passando a array de letras para o constructor da classe que estende, ArrayIterator.

class Proverbios_JangadaBrasil_Letras
    extends ArrayIterator implements RecursiveIterator
{
    public function __construct()
    {
        parent::__construct(range('a', 'z'));
    }
    
    public function hasChildren()
    {
        return true;
    }
    
    public function getChildren()
    {
        return new Proverbios_JangadaBrasil_Paginas($this->current());
    }
}

Ao contrário das letras, a paginação não tem uma array fixa. A solução mais prática foi implementar um iterador contínuo que a cada iteração carrega os provérbios para a letra solicitada naquela página, e continua lendo a páginas seguinte enquanto provérbios forem encontrados.

class Proverbios_JangadaBrasil_Paginas implements RecursiveIterator
{
    private $_letra;
    private $_pagina;
    
    private $_valid;
    
    public function __construct($letra)
    {
        $this->_letra = $letra;
    }
    
    public function rewind()
    {
        $this->_pagina = 1;
        $this->_valid = true;
    }
    
    public function valid()
    {
        return $this->_valid;
    }
 
    public function hasChildren()
    {
        return true;
    }
    
    public function getChildren()
    {
        $it = new Proverbios_JangadaBrasil_Proverbios(
            $this->_letra, $this->_pagina);
            
        $this->_valid = count($it) > 0;
        
        return $it;
    }
    
    public function current()
    {
        return $this->_pagina;
    }
    
    public function key()
    {
        return $this->_pagina;
    }
    
    public function next()
    {
        $this->_pagina++;
    }
}

Ao ser instanciada, a letra atual é recebida como argumento no constructor. No próximo passo, o método rewind() é chamado, a página definida como 1 e uma variável interna definida como true. Esta variável será usada pelo método valid() para definir se a iteração deve continuar na próxima página dessa letra. Como o hasChildren() retorna sempre true, o RecursiveIteratorIterator recupera o iterador filho pelo método getChildren(). A classe de provérbios é instanciada, e a variável interna usada pelo valid() é atualizada; se a quantidade de provérvios nesta página não for maior que zero, o valid() retornará false e a iteração neste nível pára e recomeça na letra seguinte.

Finalizando, a classe de provérbios segue a mesma lógica da classe do site anterior, sendo que essa recebe no constructor a letra e a página, que são utilizadas pra montar o link do site:

class Proverbios_JangadaBrasil_Proverbios
    extends ArrayIterator implements RecursiveIterator
{    
    public function __construct($letra, $pagina)
    {        
        $url = 'http://www.jangadabrasil.com.br/proverbios/'
                . $letra . '.asp?PageIndex=' . $pagina;
                
        $contents = file_get_contents($url);
        
        preg_match_all(
            '/<div class="textoproverbios">([^<]+)<\/div>/i',
            $contents, $matches);
 
        if(isset($matches[1]) && is_array($matches[1])){
            parent::__construct($matches[1]);
        }
    }
    
    public function hasChildren()
    {
        return false;
    }
    
    public function getChildren(){}
}

AppendIterator

Agora que as classes já estão funcionando individualmente, basta utilizar a AppendIterator para unir todas elas. Esta classe possui o método append(), que recebe um iterador como parâmetro. Ao ser utilizada em um foreach, ela percorre cada um dos iteradores em seqüência, resultando em todos os provérbios de todos os sites em um único loop.

class Proverbios extends AppendIterator
{
    public function current()
    {
        $proverbio = parent::current();
        $proverbio = trim($proverbio, " .\"'\t\n\x0B\r");
        $proverbio = html_entity_decode($proverbio);
        $proverbio = strip_tags($proverbio);
        
        return $proverbio;
    }
}

Aproveitando que todos os provérbios são retornados para o foreach pelo método current() desta classe, apliquei alguns filtros básicos pra garantir que os dados estão no formato desejado pro que eu precisava.

Foreach

Enfim, o script final simplificado de uma forma complexa:

$proverbios = new Proverbios;
$proverbios->append(new Proverbios_LifesABirch);
$proverbios->append(new Proverbios_Aborla);
$proverbios->append(new Proverbios_JangadaBrasil);

foreach($proverbios as $proverbio){
echo $proverbio, "\n";
}

Referências

http://www.php.net/~helly/php/ext/spl/
http://somabo.de/talks/200509_toronto_iterator_debug_session_2.pdf