# Zend_Amf_Server

`Zend_Amf_Server` fornece um servidor no estilo RPC para manipular requisições feitas com Adobe Flash Player usando o protocolo AMF. Como todas as classes de servidor do Zend Framework, ela segue a API SoapServer, fornecendo uma interface fácil de lembrar para criar servidores.

## Servidor AMF Básico

Vamos assumir que você tenha criado uma classe `Foo` com uma variedade de métodos públicos. Você pode criar um servidor AMF usando o código a seguir:

    $server = new Zend_Amf_Server();
    $server->setClass('Foo');
    $response = $server->handle();
    echo $response;

Alternativamente, você pode optar por atribuir uma simples função como chamada de retorno:

    $server = new Zend_Amf_Server();
    $server->addFunction('myUberCoolFunction');
    $response = $server->handle();
    echo $response;

Você também pode misturar e combinar várias classes e funções. Quando fizer isso, sugerimos que utilize namespaces para que nenhuma colisão de nomes de métodos ocorra; isso pode ser feito simplesmente passando uma string como segundo argumento, tanto para `addFunction()` ou `setClass()`.

    $server = new Zend_Amf_Server();
    $server->addFunction('myUberCoolFunction', 'my')
           ->setClass('Foo', 'foo')
           ->setClass('Bar', 'bar');
    $response = $server->handle();
    echo $response;

O `Zend_Amf_Server` também permite que serviços sejam dinamicamente carregados baseado em um caminho de diretório fornecido. Você pode adicionar tantos quantos diretórios desejar ao servidor. A ordem em que você adiciona os diretórios ao servidor será a ordem em que a pesquisa LIFO será realizada nos diretórios para encontrar a classe. Adição de diretórios é feita com o método `addDirectory()`.

    $server->addDirectory(dirname(__FILE__) .'/../services/');
    $server->addDirectory(dirname(__FILE__) .'/../package/');

Ao chamar serviços remotos, os nomes de seus fontes podem conter sublinhados ("_") e pontos (".") como delimitadores de diretórios. Quando um sublinhado é usado, as conveções PEAR e Zend Framework para nomenclaturas serão respeitadas. Isso significa que se você chamar um serviço `com_Foo_Bar` o servidor procurará pelo arquivo `Bar.php` em cada caminho incluído em `com/Foo/Bar.php`. Se a notação de ponto é usada para seu serviço remoto como em `com.Foo.Bar`, `com/Foo/Bar.php` será adicionado ao final de cada caminho incluído para autocarregar `Bar.php`

Todas as requisições AMF enviadas ao script serão manipuladas posteriormente pelo servidor, e uma resposta AMF será retornada.

## Todas as Funções e Métodos atribuídos precisam de Blocos de Documentação (Docblocks)

Como todos os componentes de servidor no Zend Framework, você precisa documentar seus métodos de classe usando docblocks PHP. Você precisa fornecer, no mínimo, anotações para cada argumento obrigatório assim como o valor de retorno. Exemplo:

    // Função para atribuição:

    /**
     * @param  string $name
     * @param  string $greeting
     * @return string
     */
    function helloWorld($name, $greeting = 'Hello')
    {
        return $greeting . ', ' . $name;
    }

    // Classe atribuída

    class World
    {
        /**
         * @param  string $name
         * @param  string $greeting
         * @return string
         */
        public function hello($name, $greeting = 'Hello')
        {
            return $greeting . ', ' . $name;
        }
    }

Outras anotações podem ser usadas, mas serão ignoradas.

## Conectando ao servidor com Flex

Conectar a seu `Zend_Amf_Server` a partir de seu projeto Flex é bem simples; você simplesmente precisa apontar sua URI de ponto de extremidade (endpoint) para seu script `Zend_Amf_Server`

Digamos, por exemplo, que você tenha criado seu servidor e o colocado no arquivo `server.php` na raiz de sua aplicação, e seu URI é `http://example.com/server.php`. Neste caso, você modificaria seu arquivo `services-config.xml` para definir o atributo uri de ponto de extremidade, channel, para este valor.

Se você nunca criou um arquivo `services-config.xml` você poderá fazê-lo abrindo seu projeto na janela 'Navigator' do Flex Builder. Clique com o botão direito sobre nome do projeto e selecione 'properties'. Na janela de diálogo de propriedades do projeto vá para o menu 'Flex Build Path', aba 'Library path' e tenha certeza de que o arquivo '`rpc.swc`' foi adicionado aos caminhos de seus projetos e pressione 'Ok' para fechar a janela.

Você também precisará informar ao compilador para usar o arquivo `services-config.xml` para encontrar o ponto de extremidade do `RemoteObject`. Para isso, abra novamente o painel de propriedades de seu projeto clicando com o botão direito do mouse no diretório do projeto a partir da janela 'Navigator' e selecionando 'properties'. Na popup de propriedades selecione 'Flex COmpiler' e adicione a seqüência de caracteres: `-services "services-config.xml"`. Pressione 'Apply' e depois 'OK' para voltar e atualizar a opção. O que você acabou de fazer foi dizer ao compilador Flex para procurar por variáveis de tempo de execução no arquivo `services-config.xml` que serão usadas pela classe `RemoteObject`

Agora precisamos dizer ao Flex qual arquivo de configuração de serviços usar para conectar a nossos métodos remotos. Por essa razão crie um novo arquivo '`services-config.xml`' em seu diretório `src` do seu projeto Flex. Pra fazer isso clique com o botão direito no diretório do projeto e selecione 'new'; 'File' que uma nova janela se abrirá. Selecione o diretório do projeto e nomeie o arquivo '`services-config.xml`' e pressione 'finish'.

O Flex criou um novo `servies-config.xml` e o abriu. Use o texto de exemplo a seguir para seu arquivo `services-config.xml`. Tenha certeza de atualizar seu ponto de extremidade (endpoint) para coincidir com seu servidor de testes e que você salve o arquivo.

    <?xml version="1.0" encoding="UTF-8"?>
    <services-config>
        <services>
            <service id="zend-service"
                class="flex.messaging.services.RemotingService"
                messageTypes="flex.messaging.messages.RemotingMessage">
                <destination id="zend">
                    <channels>
                        <channel ref="zend-endpoint"/>
                    </channels>
                    <properties>
                        <source>*</source>
                    </properties>
                </destination>
            </service>
        </services>
        <channels>
            <channel-definition id="zend-endpoint"
                class="mx.messaging.channels.AMFChannel">
                <endpoint uri="http://example.com/server.php"
                    class="flex.messaging.endpoints.AMFEndpoint"/>
            </channel-definition>
        </channels>
    </services-config>

Há dois pontos chave no exemplo. Primeiro, mas por último na listagem, criamos um canal AMF e especificados o poonto de extremidade (endpoint) como URL para nosso `Zend_Amf_Server`:

    <channel-definition id="zend-endpoint"
        <endpoint uri="http://example.com/server.php"
            class="flex.messaging.endpoints.AMFEndpoint"/>
    </channel-definition>

Note que demos a este canal um identificador, "zend-endpoint". O exemplo cria um destino de serviço que se refere a este canal, atribuindo a ele um ID também - neste caso "zend".

Em nossos arquivos MXML do Flex, precisamos ligar um `RemoteObject` ao serviço. Em MXML, isto é feito como a seguir:

    <mx:RemoteObject id="myservice"
        fault="faultHandler(event)"
        showBusyCursor="true"
        destination="zend">

Aqui, definimos um novo objeto remoto identificado por "myservice" ligado ao destino de serviço "zend" que definimos no arquivo `services-config.xml`. Nós depois chamamos métodos em nosso ActionScript simplesmente chamando "myservice.<método>". Como no exemplo:

    myservice.hello("Wade");

Quando usando espaços de nomes (namespaces), usamos: "myservice.<espaço de nome>.<método>":

    myservice.world.hello("Wade");

Para mais informações sobre como utilizar o `RemoteObject` do Flex, visite o site da Ajuda do Adobre Flex 3.

## Manipulação de Erros

Por padrão, todas as exceções lançadas em suas classes ou funções anexadas serão obtidas e retornadas como `ErrorMessage`s do AMF. No entando, o conteúdos destes objetos `ErrorMessage` variam se o servidor está ou não em modo de "produção" (o estado padrão).

Quando em modo de produção, somente o código da exceção será retornado. Se você desabilitar o modo de produção - algo que você deve fazer apenas para testes - a maioria dos detalhes de exceção serão retornados: a mensagem de exceção, linha, e pilha de execução (backtrace) serão todos anexados.

Para desabilitar o modo de produção, faça o seguinte:

    $server->setProduction(false);

Para habilitá-lo novamnete, passe um valor booleano `TRUE`:

    $server->setProduction(true);

### Desabilite o modo de produção com moderação!

Recomendamos desabilitar o modo de produção somente durante o desenvolvimento. Mensagens de exceção e pilhas de execução podem conter informações sensíveis que você provavelmente não deseje que terceiros tenham acesso. Mesmo AMF sendo um formato binário, a especificação é aberta, o que quer dizer que qualquer um pode, potencialmente, desserializar os dados carregados.

Uma área para ser especialmente cuidadoso são os próprios erros PHP. Quando a diretiva display_errors do INI está habilitada, qualquer erro PHP para o nível atual de reltório de erros são mostrados diretamente na saída - potencialmente interrompendo a carga de dados AMF. Sugerimos desabilitar a diretiva display_errors em modo de produção para evitar tais problemas

## Respostas AMF

Ocasionalmente você pode desejar manipular levemente o objeto de resposta, tipicamente para retornar cabeçalhos de mensagem extra. O método `handle()` do servidor retorna o objeto da resposta, possibilitando a você fazer isto.

### Adicionando Cabeçalhos de Mensagem à Resposta AMF

Neste exemplo, adicionamos um `MessageHeader` 'foo' com o valor 'bar' à resposta antes de retorná-la.

    $response = $server->handle();
    $response->addAmfHeader(new Zend_Amf_Value_MessageHeader('foo', true, 'bar'))
    echo $response;

## Objetos Tipados

De modo similar ao SOAP, AMF permite que sejam passados objetos entre o cliente e o servidor. Isso permite uma grande quantidade de flexibilidade e coerência entre os dois ambientes.

`Zend_Amf` fornece três métodos para mapeamento entre objetos ActionScript e PHP.

- Primeiro, você deve criar explicitamente ligações no nível do servidor, usando o método `setClassMap()`. O primeiro argumento é o nome da classe ActionScript, o segundo é a classe PHP que a mapeia:

      // Mapeia a classe ActionScript 'ContactVO' para a classe PHP 'Contact':
      $server->setClassMap('ContactVO', 'Contact');

- Em segundo lugar, você definir a propriedade pública `$_explicitType` em sua classe PHP, com o valor representando a classe ActionScript para mapear:

      class Contact
      {
          public $_explicitType = 'ContactVO';
      }

- Terceiro, de maneira similar, você pode definir o método público `getASClassName()` em sua classe PHP; este método deve retornar a classe ActionScript apropriada:

      class Contact
      {
          public function getASClassName()
          {
              return 'ContactVO';
          }
      }

Embora tenhamos criado o ContactVO no servidor precisamos agora fazer a classe correspondente em AS3 para que o objeto de servidor seja mapeado.

Clique com o botão direito na pasta `src` de seu projeto Flex e selecione 'New' -> 'ActionScript File'. Nomeie o arquivo como 'ContactVO' e pressione 'finish' para ver o novo arquivo. Copie o seguinte código para finalizar a criação da classe.

    package
    {
        [Bindable]
        [RemoteClass(alias="ContactVO")]
        public class ContactVO
        {
            public var id:int;
            public var firstname:String;
            public var lastname:String;
            public var email:String;
            public var mobile:String;
            public function ContactVO():void {
            }
        }
    }

A classe é sintaticamente equivalente à classe PHP com o mesmo nome. Os nomes de variáveis são exatamente os mesmos e precisam estar sob o mesmo caso para que funcione apropriadamente. Existem duas marcações meta (meta tags) AS3 únicas nesta classe. A primeira é Bindable, que faz com que um evento de alteração (change) seja disparado quando ela é atualizada. A segunda marcação é RemoteClass, que define que esta classe pode ter um objeto remoto mapeado a ela com um apelido, neste caso ContactVO. É obrigatório que o valor desta marcação seja definido seja estritamente equivalente ao da classe PHP.

    [Bindable]
    private var myContact:ContactVO;

    private function getContactHandler(event:ResultEvent):void {
        myContact = ContactVO(event.result);
    }

O evento de resultado gerado pela chamada ao serviço é instantaneamente convertido para o ContactVO do Flex. Qualquer coisa que seja direcionada a `myContact` será atualizado e os dados de ContactVO serão retornados.

## Recursos

`Zend_Amf` fornece ferramentas para mapear tipos de recursos retornados por classes de serviços em informações consumíveis pelo ActionScript.

A fim de lidar com tipo de recurso específico, o usuário precisa criar uma classe plugin chamado após o nome do recurso, com palavras em maiúsculas e espaços removidos (assim recurso do tipo "resultado mysql" torna-se ResultadoMysql), com algum prefixo, ex.: `Meu_ResultadoMysql`. Esta classe precisa implementar um método, `parse()`, recebendo um argumento - o recurso - e retornando o valor a ser enviado para o ActionScript. A classe deve estar localizada no arquivo chamado após o nome do componente, ex.: `ResultadoMysql.php`.

O diretório contendo os plugins para manipulação de recursos devem ser registrados com o carregador de tipo `Zend_Amf`:

    Zend_Amf_Parse_TypeLoader::addResourceDirectory(
        "Meu",
        "application/library/recursos/Meu"
    );

Para uma discussão detalhada sobre o plugins carregadores, por favor veja a seção plugin carregador.

O diretório padrão para recursos `Zend_Amf` é registrado automaticamente e atualmente contém manipuladores para recursos "resultado mysql" e "stream".

    // Classe de exemplo implementando a manipulação de recursos do tipo "resultado mysql"
    class Zend_Amf_Parse_Recurso_ResultadoMysql
    {
        /**
         * Decodifica o recurso em uma matriz
         *
         * @param resource $resource
         * @return array
         */
        public function parse($resource) {
            $result = array();
            while($row = mysql_fetch_assoc($resource)) {
                $result[] = $row;
            }
            return $result;
        }
    }

Ao tentar retornar um tipo desconhecido de recirso (ex., um para o qual não haja plugin manipulador existente) resultará em uma exceção.

## Conectando ao Servidor a partir do Flash

Conectando ao seu `Zend_Amf_Server` a partir de seu projeto Flash é ligeiramente diferente do que com Flex. Contudo, depois da conexão, Flash funciona com `Zend_Amf_Server` da mesma forma que com Flex. O exemplo a seguir também pode ser usado com um arquivo AS3 do Flex. Reutilizaremos a mesma configuração `Zend_Amf_Server` com a classe Mundo para nossa conexão.

Abra o Flash CS e crie um novo arquivo Flash (ActionScript 3). Nomeie o documento `ExemploZend.fla` e salve o documento em uma pasta que você usará para este exemplo. Crie uma nova classe AS3 no mesmo diretório e nomeie o arquivo como `Principal.as`. Tenha ambos os arquivos abertos em seu editor. Vamos conectar os dois arquivos através da classe de documento. Selecione ExemploZend e clique no palco. No painel de propriedade dos palco, altere a classe de documento (Document class) para Principal. Isso ligará o arquivo ActionScript `Principal.as` com a interface do usuário do arquivo `ExemploZend.fla`. Quando você executa o arquivo Flash ExemploZend, a classe `Principal.as` será executada agora. Agora, vamos adicionar o código ActionScript para fazer a chamada AMF.

Agora nós faremos a classe Principal de modo que possamos enviar dados ao servidor e exibir o resultado. Copie o código a seguir para seu arquivo `Principal.as` e depois vamos descrever, passo a passo, o papel de cada elemento nele.

    package {
      import flash.display.MovieClip;
      import flash.events.*;
      import flash.net.NetConnection;
      import flash.net.Responder;

      public class Principal extends MovieClip {
        private var gateway:String = "http://exemplo.com/server.php";
        private var connection:NetConnection;
        private var responder:Responder;

        public function Principal() {
          responder = new Responder(onResult, onFault);
          connection = new NetConnection;
          connection.addEventListener(NetStatusEvent.NET_STATUS, onComplete);
          connection.connect(gateway);
        }

        public function onComplete( e:NetStatusEvent ):void {
          if(e.info.code == "NetGroup.Connect.Succcess") {
            var params = "Sent to Server";
            connection.call("Mundo.alo", responder, params);
          }
        }

        private function onResult(result:Object):void {
          // Display the returned data
          trace(String(result));
        }
        private function onFault(fault:Object):void {
          trace(String(fault.description));
        }
      }
    }

Primeiro precisamos importar duas bibliotecas ActionScriot que executam a maior parte do trabalho. A primeira é NetConnection que atua como um tubo bi-direcional entre o cliente e o servidor. A segunda é o objeto Responder, que manipula os valores de retorno do servidor relacionados ao sucesso ou falha da chamada.

    import flash.net.NetConnection;
    import flash.net.Responder;

Na classe, precisamos de três variáveis para representar a NetConnection, Responder e a URL da porta de entrada (gateway) para nossa instalação `Zend_Amf_Server`.

    private var gateway:String = "http://exemplo.com/server.php";
    private var connection:NetConnection;
    private var responder:Responder;

No contrutor de Principal criamos um respondedor e uma nova conexão ao ponto de extremidade (gateway) `Zend_Amf_Server`. O respondedor define dois métodos diferentes para manipular as respostas do servidor. Por simplicidade eles foram chamados de onResult e onFault.

    responder = new Responder(onResult, onFault);
    connection = new NetConnection;
    connection.addEventListener(NetStatusEvent.NET_STATUS, onComplete);
    connection.connect(gateway);

Na função onComplete, que é executada assim que o construtor tenha sido terminado, nós enviamos dados ao servidor. Precisamos adicionar mais uma linha que realiza a chamada a função Mundo->alo do `Zend_Amf_Server`

    connection.call("Mundo.alo", responder, params);

Quando instanciamos a variável responder, definimos uma função onResult e onFault para manipular a resposta do servidor. Adicionamos esta função para um resultado de sucesso vindo do servidor. Um manipulador de eventos de sucesso é executado sempre que uma conexão é manipulada apropriadamente no servidor.

    private function onResult(result:Object):void {
        // Mostra os dados retornados
        trace(String(result));
    }

A função onFault é chamada se há uma resposta inválida vinda do servidor. Isso acontece quando há um erro no servidor, a URL para o servidor é inválida, o serviço remoto ou método não existe ou se há qualquer outro problema relacionado à conexão.

    private function onFault(fault:Object):void {
        trace(String(fault.description));
    }

Completamos então a inclusão do ActionScript para realizar a conexão remota. Executando o arquivo ExemploZend agora faz a conexão ao `Zend_Amf`. Numa revisão, você adicionou as variáveis necessárias para abrir uma conexão ao servidor remoto, definiu quais métodos devem ser usados em sua aplicação para receber respostas do servidor e finalmente exibido os dados retornados através da função `trace()`.

## Autenticação

`Zend_Amf_Server` permite que você especifique ganchos de autentcação e autorização para controlar acesso aos serviços. Isso é feito usando a infraestrutura fornecida pelos componentes `Zend_Auth` e `Zend_Acl`.

Para definir autenticação, o usuário fornece um adaptador de autenticação extendendo a classe abstrata `Zend_Amf_Auth_Abstract`. O adaptador deve implementar o método `authenticate()` como qualquer outro adaptador de autenticação.

O adaptador deve utilizar as propriedades _username e _password da classe pai, `Zend_Amf_Auth_Adapter`, para autenticar. Estes valores são definidos pelo servidor usando o método `setCredentials()` antes da chamada à `authenticate()` se as credenciais forem recebidas nos cabeçalhos da requisição AMF.

A identidade retornada pelo adaptador deve ser um objeto contendo a propriedade role para que o controle de acesso da ACL funcione.

Se o resultado da autenticação não for bem sucedido, a requisição não é mais procesada e uma mensagem de falha é retornada contendo as razões da falha obtida do resultado.

O adaptador é conectado ao servidor usando o método `setAuth()`:

    $server->setAuth(new My_Amf_Auth());

O controle de acesso é realizado usando um objeto `Zend_Acl` definido pelo método `setAcl()`:

    $acl = new Zend_Acl();
    criarPermissoes($acl); // Cria a estrutura de permissões
    $server->setAcl($acl);

Se o objeto ACL é definido e a classe sendo chamada define o método `initAcl()`, este método será chamado com o objeto ACL como um argumento. A classe depois cria regras ACL adicionais e retorna `TRUE`, ou retorna `FALSE` se nenhum controle de acesso for necessário para esta classe.

Depois de a ACL ser definida, o servidor verificará se o acesso é permitido com o papel definido pela autenticação, sendo o recurso o nome da classe (ou `NULL` para chamadas de funções) e o privileǵio sendo o nome da função. Se nenhuma autenticação for fornecida, e se o papel anonymous foi definido, ele será usado, em outro caso o acesso será negado.

    if($this->_acl->isAllowed($role, $class, $function)) {
        return true;
    } else {
        require_once 'Zend/Amf/Server/Exception.php';
        throw new Zend_Amf_Server_Exception("Accesso não permitido");
    }