sfAmfPlugin - 1.5.0

This Plugin to handle AMF requests from Flex client frontends

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

sfAmfPlugin

Overview

The sfAmfPlugin provides you with all you need to write symfony backends for Flex clients. The communication is done via Adobes AMF protocol. On serverside the SabreAMF library is used to encode/decode the AMF streams. For parsing the annotations the Addendum library use used

If you look for a tutorial you can find one here: http://www.symfony-zone.com/wordpress/2009/04/15/helloworld-example-with-flex-and-symfony/

Installation

The easiest way to install the plugin is to use the plugin:install command of symfony.

$ php symfony plugin:install sfAmfPlugin

If you preffer you can use the current development version from the subversion repository (http://svn.symfony-project.com/plugins/sfAmfPlugin) instead. Copy the checked out version to the plugins folder of your project and execute the command

$ symfony cc

That's it

Usage

AMF-Client Requests are try to execute Services on the backend. Therefore you have to create a RemoteObject in Flex that has a Symfony-URL (i.e http://flextest/Test/amf).

All your services you can call will need to be saved the Service class in any lib-folder of your project. Just create a service folder under lib and put your class there.

Examples: sf_root_dir/lib/services sf_root_dir/apps/appname/libs/services sf_root_dir/apps/appname/modules/modulname/libs/services sf_root_dir/plugins/pluginname/libs/services

In the lib/service you can add as many subfolders as you need/want. Services on Flex-Side can use package names like org.company.project.Servicename. You can use this with symfony too. All you need to do is to save this Service under lib/services/org/company/project/Servicename.php. That's it!

A service can look like this: [php] class TestService extends sfAmfService { public function getValues() { return array('value1', 'value2', 'value3'); } }

Please keep in mind that your service needs to extend the sfAmfService class. By default every public function is accessable via a AMF-Request (you can change this with annotations, see below).

Instead of creating the Services by hand, you can use the amf:create-service commandline task.

$ symfony amf:create-service [--package=...] service_name

Sample 1:

$ symfony amf:create-service User

will create the file UserService.class.php in the folder lib/services of your project

Sample 2:

$ symfony amf:create-service --package=de.shiftup.projectname User

will create the file UserService.class.php in the folder lib/services/de/shiftup/projectname of your project

But how is this service called from client side? We need an URL to do so. For symfony this means you need a module and an action. The following listing shows you how an AMF action should look like:

The preferred way is to use the plugin amf gateway module. For that just enable the module in the settings.yml of your application:

enabled_modules:  [default, amfgateway]

In this case you use the following URL for your Flex services calls:

http://host/amfgateway/service

Alternativly you can create your own module and action:

public function executeAmf() {
      $this->setLayout(false);
      sfAmfGateway::getInstance()->handleRequest();
      return sfView::NONE;
  }

And last but not least, this is possible too:

public function executeAmf() {
      $this->setLayout(false);
 
      $gateway = new sfAmfGateway();
      $response = sfContext::getInstance()->getResponse();
      $response->setContent($gateway->service());
      return sfView::NONE;
  }

AMF-Service Browser

You can call a AMF-Service-Browser to test your Service-Classes. The Plugin contains a Service-Browser to do so. For that just enable the module in the settings.yml of your application:

enabled_modules:  [default, amfbrowser]

Please keep in mind that you should activate this module only for the DEV-Environment. Otherwise you will create a big security issue for your application. After you have added the browser to your enabled_modules run the following symfony commands:

$ symfony cc
$ symfony plugin:publish-assets sfAmfPlugin

Now you can call the Service-Browser via calling http://host/amfbrowser

ORM-Support

The sfAmfPlugin supports both ORM-Layers of Symfony (Propel and Doctrine). So you are able to return Doctrine_Recordset, Doctrine_Collection and Propel-Objects from your service. The plugin is doing the conversion to AMF for you.

Sample:

class TestService extends sfAmfService {
      public function getValues() {
          $result = Doctrine::getTable('Menu')->findAll();
          return $result;
      }
  }

Annotations

You can control the behaviour of the Service via setting annotations in the DocBlock comments of the function.

AmfIgnore

By default every public funtion is accessable via a AMF-Request. With the @AmfIgnore Annotation you can set a public function to inaccessable. If you try to access this function you get an error message.

/**
   * @AmfIgnore
   */
  public function getValues() {
    ...
  }

AmfClassMapping

AMF has a nice feature called class mapping. In this case your result of the PHP will be automatically mapped to a ActionScript class on the Flex client side. Cause Flex can not do this without some informations you have to define the ActionScript class before returning the values from PHP. With the sfAmfPlugin you can use the AmfClassMapping annotation to define this class name.

/**
   * @AmfClassMapping(name="ActionScriptClassName")
   */
  public function getValues() {
    ...
  }

AmfReturnType

Besides class mapping the AMF plugin can convert your return data in some special ActionScript data types before sending them back to the Flex-Client

ArrayCollection

If you want to transfer array data you can use the return type ArrayCollecion. If so the data will casted in a ArrayCollection on Clientside automaticaly.

/**
   * @AmfReturnType("ArrayCollection")
   */
  public function getImage() {
      $values = array();
      $values[] = ...;
      $values[] = ...;
 
      return $values;
  }
ByteArray

Sometimes it can be useful to transfer byte array data (i.e. images) from PHP to Flex. Therefore you can set the returning data type of a service method to ByteArray. This is done via the @AmfReturnType annotation

/**
   * @AmfReturnType("ByteArray")
   */
  public function getImage() {
      $image = file_get_content('path/to/image.png');
      return $image;
  }

TODO

  • Annotations for authorization
  • Possibility to define project and class wide class mappings
  • Adding factory class for AMF controller
  • Task for creating VO ActionScript classes from Doctrine or Propel classes
  • Support for Doctrine nested sets
  • Caching

I like to hear from you! Maybe you have an idea how to enhance the plugin. Just send me an email!

Changelog

  • 1.5.0 (01-11-2010)
    • Added Support for Symfony 1.3 and 1.4
    • Updated to most current development version of SabreAMF
    • Added first version of an AMF service browser (thanks to Beno