The symfony Cookbook

symfony 1.1 adiciona suporte nativo a diferentes formatos e mime-types. Isso significa que o mesmo modelo e controller pode ter diferentes templates baseado no formato requisitado. O padrão continua sendo HTML, mas o symfony suporta inúmeros outros formatos por padrão, como definido no arquivo factories.yml:

request:
  class: sfWebRequest
    param:
      formats:
        txt:  text/plain
        js:   [application/javascript, application/x-javascript, text/javascript]
        css:  text/css
        json: [application/json, application/x-json]
        xml:  [text/xml, application/xml, application/x-xml]
        rdf:  application/rdf+xml
        atom: application/atom+xml

Cada formato é associado com um ou mais mime-types. Esses mime-types são usados para determinar automaticamente o formato requisitado lendo o cabeçalho HTTP Accept. Isso ajuda se você quer disponibilizar seus dados via navegador e também via Web Service. Para mudar o formato da resposta, um cliente Web Service pode simplesmente mudar o cabeçalho Accept, como mostrado abaixo:

$ curl -H "Accept: application/xml"  http://ws.example.com/api/article # to get a XML representation of the data
$ curl -H "Accept: application/json" http://ws.example.com/api/article # to get a JSON representation of the data

Ter diferentes formatos é tão fácil quanto criar templates diferentes. Então, vamos dizer que um web service é gerenciado pela ação api/article. Aqui esta a lista de templates que você vai criar em apps/frontend/modules/api/templates para suportar os formatos HTML,XML e JSON:

• articleSuccess.php
• articleSuccess.xml.php
• articleSuccess.json.php

Por padrão o symfony vai mudar o cabeçalho de resposta Content-Type de acordo com o formato, e para todos os formatos não-HTML, o layout sera desabilitado. Até mesmo partials e layouts podem ser diferentes baseados no formato requisitado. Por exemplo, se você inclui um partial list em um template, o nome do partial carregado vai depender do formato atual:

• _list.php
• _list.xml.php
• _list.json.php

Vamos ver um outro exemplo. Você quer criar alguns arquivos JavaScript e CSS dinamicamente. Como você não pode confiar sempre no cabeçalho Accept do navegador, nesses casos você pode forçar um formato usando a variável especial sf_format nas suas regras de roteamento.Aqui vai como criar uma rota para um CSS dinâmico.

css1:
  url:   /css/dynamic1.css
  param: { module: css, action: dynamic, sf_format: css }

Você também pode usar a variável sf_format na URL pattern para habilitar vários formatos para uma ação.

api_article:
  url:   /api/article.:sf_format
  param: { module: api, action: article }
  requirements:
    sf_format: (?:html|xml|json)

Na maior parte do tempo você não precisa mudar uma linha sequer nas suas ações para suportar novos formatos, mas se você realmente precisa algo especial para um determinado formato, você pode chamar $request->getRequestFormat() para pegar o formato atual e agir de acordo.

Ok, agora vem a parte divertida. Vamos supor que você quer criar uma versão otimizada do seu site para o iPhone. O formato iphone não existe por padrão, mas é bem fácil de adiciona-lo. Primeiro, nós precisamos de uma maneira para saber que uma requisição veio de um iPhone. Se o cabeçalho User-Agent contém as palavras Mobile e Safari, nós podemos seguramente dizer que o navegador é um iPhone. Colocamos essa lógica na classe ProjectConfiguration registrando um listener para o evento request.filter_parameters:

// config/ProjectConfiguration.class.php
class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    // ...
 
    $this->dispatcher->connect('request.filter_parameters', array($this, 'filterRequestParameters'));
  }
 
  public function filterRequestParameters(sfEvent $event, $parameters)
  {
    $request = $event->getSubject();
 
    if (preg_match('#Mobile/.+Safari#i', $request->getHttpHeader('User-Agent')))
    {
      $request->setRequestFormat('iphone');
    }
 
    return $parameters;
  }
}

Agora, cada vez que vier uma requisição o método filterParameters sera chamado e se o navegador for um iPhone, o formato da requisição sera alterado para iphone.

E isso é tudo. Cada requisição de um iPhone vai usar os templates *Success.iphone.php ao invés dos *Success.php

Se você usa algum CSS ou JavaScript para iPhone(se você usa por exemplo a biblioteca iui), você pode configurar a view também ouvindo o view.configure_format:

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    // ...
 
    $this->dispatcher->connect('view.configure_format', array($this, 'configureIPhoneFormat'));
  }
 
  public function configureIPhoneFormat(sfEvent $event)
  {
    if ('iphone' == $event['format'])
    {
      // add some CSS, javascript, or whatever you want
    }
  }
}

Graças ao novo suporte a formatos no symfony 1.1, desenvolver websites que permitam acesso Web Service, via API ou iPhone nunca foi tão fácil. Suportar novos formatos é tão fácil quanto criar novos templates.