Alguns sites insistem em atrapalhar a navegação utilizando alert() inadvertidamente, e isso sempre me irritou bastante. Resolvi procurar e acabei descobrindo uma forma no Firefox de desabilitar funcionalidades Javascript de acordo com políticas para cada site.

Como o Firefox ainda não tem uma interface para configurar estas regras, é necessário editar o arquivo user.js manualmente. Se o arquivo ainda não existir, basta criá-lo no seu diretório pessoal do Firefox.

Aqui o caminho é ~/.mozilla/firefox/5mmyfmm7.default, mas provavelmente esta última parte será diferente.

Depois é só reiniciar o Firefox.

Quando o site tentar utilizar o recurso desabilitado o console do Javascript irá mostrar Error: Permission denied to call method Window.alert.

Para aplicar a mesma política para mais de um site, separe os endereços por espaço. Se precisar criar diferentes políticas, separe cada uma por vírgula na configuração policynames.

O legal é que dá pra desabilitar todas as funções ou propriedades do DOM. Quem quiser pode dar uma olhada nos links Configurable Security Policies e Customizing Mozilla para mais detalhes.

E então, vai usar? Já faz isso de outra forma?

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.

Teste online

A aplicação de exemplo está disponível para testes no seguinte link:

http://garotosopa.com/dslcatalog-r39/demo/public/index.php

Foi publicada a versão da revisão 39, onde até então não houve nenhuma preocupação com compatibilidade do autocomplete em todos os browsers no Internet Explorer. Sugiro que teste no Firefox ou Opera.

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

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

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.

• Chat funcionando
• Código fonte com highlight
• Código fonte para download

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