WURFL-PHP API
=======================================

:Author: Fantayeneh Asres Gizaw
:Revision: $Rev$
:Date: $Date$
:Status: Draft

.. contents::

Scope
=====

The scope of this document is to describe the design of the wurfl php api in order to make easy 
the integration or extension of the api.

Design overview
===============
Because of the variaty Mobile Devices and formats that a modern Mobile application
should handle, this api will provide an abstraction/layer on top of the wurfl.xml
that makes easier 
	- device detection
	- capability quering


Layers
======

The api is devided into 2 layers:

The api Initialization layer that is represented by the 
	- All Classes in WURFL/Xml/ package 

The Classes in the WURFL/Xml/ package are responsible for parsing the main wurfl.xml and 
patch files and creating the appropriate data structures :

	- $devicesMap 
		Associative array of <deviceID, device>
		where device is a snapshot of the xml device element
	- $groupIDCapabilitiesMap 
		Associative array of <groupID, capabilitiesName>
	- $userAgentsWithDeviceIDMap
		Associative array of <userAgent, deviceID>
		

Classes
=======

WURFL_Xml_Interface
-------------------

The WURFL_Xml_Interface interface has to be implemented by classes that will
parse a wurfl.xml or patch files and create an WURFL_Xml_ParsingResult object.

Methods::
	/**
	 * Parses the given file and returns a WURFL_Xml_ParsingResult 
	 * object
	 *
	 * @param string $fileName
	 * @return WURFL_Xml_ParsingResult
	 */	
	public function parse($fileName);
	
	
WURFL_Xml_ParsingResult
------------------------
An instance of this class encapsulates a the result of the parsing phase
	
	- $devicesMap
	- $groupIDCapabilitiesMap;
	

WURFL_Xml_XMLResourceManager
----------------------------------
This Class is responisble for coordinating the parsing and patching the xml file 
containing devices and persisting the resulting data structures.
i.e
	- every device will be persisted(Serialized) on file system using as identifier
	  the device id
	- $groupIDCapabilitiesMap
	- $userAgentsWithDeviceIDMap
	
Methods::
	
	
	/**
	 * Returns an associative array containing <userAgent, deviceID> 
	 *
	 * @return array
	 */
	public function getUserAgentsWithDeviceID();
	
	
	/**
	 * Returns an associative array containing <groupID, capabilities>
	 *
	 * @return array
	 */
	public function getGroupIDCapabilitiesMap() {
		
 
WURFL_Xml_ModelDevice
============================
 This class incapsulates a single device found in the wurfl files.
 
 

WURFL_Handlers_Handler
===============================================

This class gives a base implementations of the  two interfaces  WURFL_Handlers_Filter and WURFL_Handlers_Matcher
 




The main idea behind the Handler class is to create as many classes that can handle
a specific task.

i.e There are NokiaUserAgentHandler, VodafoneUserAgentHandlre,....
    thare are specialized handles for the specific brands.
    
    
    
    If a request comes in ( can be classification, or matching request) the first thing to 
    decide is if that specified instance can handle it.
    If that is not the case, the request will be bassed to the next handler available.
    Otherwise if the request is:
    	Classification :
    		
    		- 

Classification:	
		
		
WURFL_Handlers_Filters
----------------------------------------------
This interface has to be implemented by classes that can handle 
	- devices classification process. i.e the process of grouping the devices
	  based on some patterns. In this case we use some patterns found in the user agent of
	  the devices
	- persisting the output of the classification process

Methods::

	/**
	 * The filter() method is used to classify devices based on patterns
	 * in their user agents.
	 *  
	 * @param string $userAgent User Agent of the device
	 * @param string $deviceID  id of the the device
	 * 
	 */
	public function filter($userAgent, $deviceID);

	/**
	 * The persistData() method is resposible to 
	 * saving the classification output(associative arrays that holds <userAgent, deviceID> pair))  
	 *
	 */
	public function persistData();
	

WURFL_Handlers_Matcher
----------------------------------------------
This interface has to be implemented by classes that can find(match) an apropriate device id for
the given request

Methods::
	/**
	 * Returns a matching device id for the given request
	 * 
	 * If no matching device is foud will return "generic"
	 * 
	 * @param WURFL_Request_GenericRequest $request
	 */
	public function match(WURFL_Request_GenericRequest $request);
	





WURFL_Request_GenericRequest
-----------------------------------		  
An instance of this class encapsulates a request containing 
 - userAgent
 - xhtml profile
 -