Specifications for AMFPHP 2

Technical Specifications for AMFPHP 2.0

This document details the different classes that are contained in AMFPHP 2.0.

It builds on the following documents :

https://www.silexlabs.org/2010/08/amfphp-2-0-roadmap/

design goals
  • to be compatible as much as possible with the existing system, so that users can update their systems painlessly
  • to be modular to decentralize development. Actions and Fillters as they exist now are to be done away now as nearly no one understands them. They will be replaced by plugins.
  • The integration of amfphp within larger projects should no longer be an issue. The distribution will be made so that it functions as a gateway as before, but it should be flexible to just use the distribution as a library.
  • The core should be as lean as possible. This means deserializing, routing to a class function, serializing, and that’s it. All the other functionality users might want should be pushed towards plugins.
  • To be compatible with the latest and greatest in PHP, while staying compatible with PHP 5. Support for PHP 4 will be dropped.
  • Performance. AMFPHP is fast, let’s try to keep it that way.
  • Of course fix up the bugs that are in AMFPHP 1.9. PHP 5.3 compatibilty issues, date encoding, Iexternalizable, etc.

Please feel free to disagree in the comments!

The Plan

The following milestones are planned:

  • an amf library with unit tests
  • a barebones amfphp setup with just deserialization, service routing, and serialization
  • the minimal plugins to be functional. The priority here is support for charsets and security, but we’re open to lobbying.

File Structure

Here is the file structure, with classes in italics :

trunk -> amfphp. Contains the main distribution code

Tests. The tests

plugins : the plugin repository

amfphp -> core

plugins : installed plugins

gateway.php

core -> common

amf

Gateway

Context

PluginManager(defined elsewhere)

HookManager(defined elsewhere)

common -> IDeserializer

ISerializer

IServiceRouter

IExceptionHandler

DefaultServiceRouter

amf -> AmfDeserializer

AmfSerializer

AmfExceptionHandler

→ services folder where the developer puts service classes

Class Details

Gateway

the gateway is at gateway.php, whose only job is to instantiate the actual gateway class, eventually tweak its parameters the necessary inits, and call its « init » and « execute» functions, and then echo its response. This is quite like the actual setup, except that it should be much simpler because of plugins, and that because the response is not necessarily output in the Gateway class, AMFPHP can be more easily integrated into other platforms.

some pseudo code for the gateway class

function init(){
try{
loadHookManager()
loadCore()
loadPlugins()
initContext()
loop steps in context with a hook before and after
}catch{
handleException()
}
}

function execute(){
try{
deserialize()

routeService()

serialize()
}catch{
handleException()
}
}

Hooks will be added at various steps in the process so that plugins can interact with the main code and data when needed.

Context

Contains the data being manipulated in its various formats and flavours, as well as pointers to the various classes that will be called during the process. Is meant to be remoting protocol agnostic, i.e. work just as well for amf as for json or xml.

This is initialized by the gateway, and can be tweaked by the plugins as needed. For all purposes the context could be a singleton, but it is safer to attach it to the gateway.

  • requestHeaders
  • requestBody
  • getParams (optional, this might not be a good idea)
  • serviceName
  • serviceFunction
  • functionCallParameters
  • functionCallReturnValue
  • responseHeaders
  • responseBody
  • deserializer : IDeserializer
  • serviceRouter : IServiceRouter
  • serializer : Iserializer
  • exceptionHandler : IexceptionHandler
  • pluginData (an array to hold any persistent plugin data)

IDeserializer

Interface for classes that deserialize AMFPHP data.

  • function deserialize (context :Context)

ISerializer

Interface for classes that serialize AMFPHP data.

  • function serialize (context :Context)

IServiceRouter

Interface for routing services

  • function route (context :Context)

DefaultServiceRouter

The default implementation for routing a call to a service.

AmfDeserializer, AmfSerializer, AmfExceptionHandler

The implementations of IDeserializer, ISerializer, and IexceptionHandler for AMF remoting.

Plans for Plugins

The system described above is a bare bones amf remoting system. To be useful to most people though, it will need to be enhanced with some of the following plugins. This is not meant to be full specifications, rather some ideas on how the functionality could be built into plugins and how these plugins would interact with the main system.

Authentication

Looks for a static « authentication » descriptor on the service class, containing the roles needed by the user to access the service and/or its functions. The roles would be defined and stored in a session. As such would need to intervene just before the class instantiation in the service router. An API would be available in the services to manipulate the user roles.

Cache

Ideally this would be remoting protocol agnostic, so it would intervene between deserialization and service routing. The actual cache data would be manipulated through an API in the service code.

Security

In its most basic form security is just about blocking requests coming from other domains. This can be done before deserialization.

Custom VO (Value-Object) mapping

Can be done after deserialization and after serialization

Charsets

Can be done after deserialization and after serialization

Logging

Can be done at any point, really, but it would be most helpful to log exceptions and the like.

JSON/XML-RPC/Haxe Remoting/PHP amf extension

These would look at the data type and replace the deserializer and serializer on the context.

Service Browser

The existing service browser can be refactored as a plugin

Server compatibility test suite

A plugin to generate a report on whether or not the server configuration is compatible with AMFPHP, and if not to try to provide some helpful remarks on how to fix it

Rejoignez nous