Zend Framework: Zend_Oembed Component Proposal

Proposed Component Name	Zend_Oembed
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Oembed
Proposers	Pawel Przeradowski
Revision	0.1 - 13 May 2008: Initial creation. 0.2 - 14 May 2008: Outlining class interface. 0.2.1 - 13 June 2008: Updated adopters (wiki revision: 31)

Zend_Oembed family of classes is a component that can consume and produce oEmbed resources with simple and straightforward API. Zend_Oembed_Client reuses possibilities of Zend_Http_Client for obtaining oEmbed resources represented by Zend_Oembed_Resource instances. It furthermore provides view helpers for rendering oEmbed resources in XML or JSON format.

oEmbed is a protocol for easily obtaining and embedding third-party media. It relies on HTTP for transfer and provides XML or JSON encoded resources. Each resource is uniquely identified by it's URL. oEmbed provider publishes API endpoint URL and oEmbed consumers can query it by using appropriate resource URLs.

Example:

API endpoint: http://www.filckr.com/services/oembed/
Resource URL: http://www.flickr.com/photos/nicolasbdotnet/1840441618/
Combined: http://www.flickr.com/services/oembed/?url=http://www.flickr.com/photos/nicolasbdotnet/1840441618/
Response:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <oembed> <version>1.0</version> <type>photo</type> <title>L'éléphant PHP</title> <author_name>nicolasbdotnet</author_name> <author_url>http://www.flickr.com/photos/nicolasbdotnet/</author_url> <cache_age>3600</cache_age> <provider_name>Flickr</provider_name> <provider_url>http://www.flickr.com/</provider_url> <width>500</width> <height>333</height> <url>http://farm3.static.flickr.com/2324/1840441618_c6dfe9b411.jpg</url> </oembed>

Early adopters:

Flickr
Viddler
Twitter (oohembed)
Qik
YouTube (oohembed)
Wikipedia (oohembed)
IMDb (oohemebd)
Amazon (oohemebd)
...

2. References

oEmbed protocol specification
Viddler oEmbed Wiki Page
Ruby implementation
oohEmbed - oEmbed compatible provider of HTML embed codes for various web sites

3. Component Requirements, Constraints, and Acceptance Criteria

This component will consume both XML and JSON OEmbed resources
This component will provide easy way of implementing OEmbed providers
This component will include a factory methods for creating resources from arrays, XML, JSON, DOMNodes etc.
This component will allow subclassing.
This component will fallow oEmbed specification.

4. Dependencies on Other Framework Components

Zend_Exception
Zend_Http_Client
Zend_Http_Response
Zend_Json (optional)

5. Theory of Operation

6. Milestones / Tasks

Milestone 1: design notes will be published here
Milestone 2: Working prototype checked into the incubator supporting use cases #1, #2, ...
Milestone 3: Working prototype checked into the incubator supporting use cases #3 and #4.
Milestone 4: Unit tests exist, work, and are checked into SVN.
Milestone 5: Initial documentation exists.

7. Class Index

Zend_Service_Oembed_Exception
Zend_Service_Oembed_Client
Zend_Service_Oembed_Client_Exception
Zend_Service_Oembed_Resource
Zend_Service_Oembed_Resource_Exception
Zend_View_Helper_OembedXml
Zend_View_Helper_OembedJson

8. Use Cases

See some of use cases in cation

Pulling a photo from Flickr
See it in action

$client = new Zend_Oembed_Client('http://www.flickr.com/services/oembed');
$photo = $client->request('http://www.flickr.com/photos/nicolasbdotnet/1840441618/');

Zend_Debug::dump($photo);

echo $photo->providerName;
//outputs: Flickr

var_dump($photo->isVideo());
//outputs: boolean(false)

Pulling several photos in a row from flickr as JSON.
See it in action

//keepalive to save connection negotiation times
$client = new Zend_Oembed_Client('http://www.flickr.com/services/oembed', array('format' => 'json', 'keepalive' = true));

//each not bigger than this
$client->setMaxDimensions(320, 240);

$elephant = $client->request('http://www.flickr.com/photos/bocavermelha/18700659/');
$lion = $client->request('http://www.flickr.com/photos/darwishh/754888124/');
$giraffe = $client->request('http://www.flickr.com/photos/gdstewart/1464968381/');

echo $elephant->cacheAge;
//outputs 3600

//bulk alter properties
$elephant->setProperty(array('tags' => 'elephant africa wild', 'cache_age' => 60));

echo $elephant->cacheAge;
//outputs 60
echo $elephant->getPropertyTags();
//outputs elephant arica wild
echo $lion->getPropertyFoo('spam');
//outputs spam

See it in action

Implementing simple provider with helper class

//controller
$alice = Zend_Oembed_Resource::fromArray(array('type' => 'photo', 'version' => '1.0', 'title' => 'Birthday'));
$alice->url = 'http://example.com/foo/spam/alice.jpg';
$alice->width = 640;
$alice->height = 480;

$this->view->alice = $alice;


//view.phtml
//turns off layouts by deafult and switches Content-Type
<?=$this->oembedXml($this->alice); ?>


/* outputs:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oembed>
 <type>photo</type>
 <version>1.0</version>
 <title>Birthday</title>
 <url>http://example.com/foo/spam/alice.jpg</url>
 <width>640</width>
 <height>480</height>
</oembed>
*/

See it in action

Embedding video from Viddler

$fish = Zend_Oembed_Resource::fromUri('http://lab.viddler.com/services/oembed', 'http://www.viddler.com/explore/dionbartrams/videos/12/');

//embed
echo $this->fish->html;

Simple Flickr client.

class FlickrClient extends Zend_Oembed_Client
{
    public function __construct()
    {
         parent::__construct('http://www.flickr.com/services/oembed', array('maxWidth' => 400, 'maxHeight' => 300);
    }
}

$flickr = new FlickrClient();
$flickr->request('http://www.flickr.com/photos/gdstewart/471797391/in/set-72157602910687510/');

9. Class Skeletons

class Zend_Service_Oembed_Client
{
    /**
     * XML resource format
     *
     */
    const FORMAT_XML = 'xml';
    
    /**
     * JSON resource format
     */
    const FORMAT_JSON = 'json';
    
    /**
     * Array of options altering client behaviour.
     *
     * @var array
     */
    protected $_options = array(
        'validate' => true,
        'filterscripts' => true
    );

    /**
     * Zend_Http_Client instance backing consumer
     *
     * @var Zend_Http_Client
     */
    protected $_httpClient = null;
    /**
     * Constructor method. Creates new Zend_Service_Oembed_Client instance.
     * Accepts oEmbed API endpoint and options array.
     *
     * @param Zend_Uri_Http|string $endpointUri
     * @param array $options
     */
    public function __construct($endpointUri, array $options = array())
    {}

    /**
     * Allows discovery of available API endpoints on given host. Returns an
     * array of Zend_Service_Oembed_Client.
     *
     * @param Zend_Uri|string $uri
     * @param array $options for each client to be instantiated with
     * @return array
     */
    public static function discover($uri, array $options = array()) {}

    /**
     * Alters behavior of client by suppling option keys and values. Standard
     * options include format, maxWidth, maxHeight, validate and filterScripts
     * keys. Some API endpoints allow additional nonstandard options.
     *
     * @param array $options
     * @return Zend_Service_Oembed_Client
     */
    public function setOptions(array $options = array())
    {}

    /**
     * Sets format of provider response
     *
     * @param string $format as of version 1.0 'json' or 'xml'
     * @return Zend_Service_Oembed_Client
     * @throws Zend_Service_Oembed_Client_Exception
     */
    public function setFormat($format)
    {}

    /**
     * Sets maximum width for requested resource
     *
     * @param int $width
     * @return Zend_Service_Oembed_Client
     * @throws Zend_Service_Oembed_Client_Exception
     */
    public function setMaxWidth($width)
    {}

    /**
     * Sets maximum height of requested resource
     *
     * @param int $height
     * @return Zend_Service_Oembed_Client
     * @throws Zend_Service_Oembed_Client_Exception
     */
    public function setMaxHeight($height)
    {}

    /**
     * Sets maximum dimensions of requested resource
     * Example usages:
     * <code>
     *  setMaxDimensions(640, 480);
     * </code>
     * <code>
     *  setMaxDimensions(array(800, 600));
     * </code>
     * @param array|int $width
     * @param int $height
     * @return Zend_Service_Oembed_Client
     */
    public function setMaxDimensions($width, $height = null)
    {}

    /**
     * Perform request for resource to provider
     *
     * @param Zend_Uri_Http|string $resourceUri
     * @return Zend_Service_Oembed_Resource
     */
    public function request($resourceUri)
    {}
    
    /**
     * Returns Zend_Http_Client instance this client is backed by
     *
     * @return Zend_Http_Client
     */
    public function getHttpClient()
    {}
}

class Zend_Service_Oembed_Resource
{
    /**
     * Default order in which properties are sorted when order() is invoked
     *
     */
    public static $order_default = array('version',
                                         'type',
                                         'title',
                                         'author_name',
                                         'author_url',
                                         'provider_name',
                                         'provider_url',
                                         'url',
                                         'html',
                                         'width',
                                         'height',
                                         'thumbnail_url',
                                         'thumbnail_width',
                                         'thumbnail_height',
                                         'cache_age');
    /**
     * Array of resource properties
     *
     * @var array
     */
    protected $_properties = array();

    /**
     * Set to Zend_Http_Reponse instance if resource was
     * constucted from HTTP response. Null otherwise.
     *
     * @var Zend_Http_Reponse
     */
    protected $_response = null;

    /**
     * Constructor method. Allow only inderect construction with
     * static methods. Still allow to implement constructors in
     * subclasses.
     */
    protected function __construct()
    {}

    /**
     * Convenience factory method for requesting a resource without
     * instantiating client yourself.
     *
     * @param string|Zend_Uri $endpointUri
     * @param string|Zend_Uri $resourceUri
     * @param array $options
     * @return Zend_Service_Oembed_Resource
     */
    public static function fromUri($endpointUri, $resourceUri, array $options = array())
    {}
    /**
     * Parse HTTP response as OEmbed resource
     *
     * @param Zend_Http_Response $response
     * @return Zend_Service_Oembed_Resource
     * @throws Zend_Service_Oembed_Resource_Exception
     */
    public static function fromHttpResponse(Zend_Http_Response $response,
    $validate = true, $filterScripts = true)
    {}

    /**
     * Parse XML as OEmbed resource.
     * XML input can be string, DOMNode or SimpleXmlElement
     *
     * @param string|DOMNode|SimpleXmlElement $xml
     * @throws Zend_Service_Oembed_Resource_Exception()
     */
    public static function fromXml($xml, $validate = true, $filterScripts = true)
    {}
    
    /**
     * Inspects properties for any anomalies and filters possibly malicious
     * parts. Also flattens if XML property has XML subtree inside.
     *
     * @param string|DOMElement $element
     * @param boolean $filterScripts
     * @return string flattened and filtered property value
     */
    protected static function _inspectProperty($element, $filterScripts)
    {}

    /**
     * Create OEmbed resource from JSON
     *
     * @param string $json
     * @return Zend_Service_Oembed_Resource
     */
    public static function fromJson($json, $validate = true, $filterScripts = true)
    {}

    /**
     * Create OEmbed resource from array of properties
     *
     * @param array $properties
     * @return Zend_Service_Oembed_Resource
     */
    public static function fromArray($properties)
    {}

    /**
     * Handy get accessor.
     * Proxies to getProperty()
     *
     * @param string $name
     * @return string
     */
    public function __get($name) {}

    /**
     * Handy set accesor.
     * Proxies to setProperty()
     *
     * @param string $name
     * @param string $value
     * @return string
     */
    public function __set($name, $value) {}

    /**
     * Magic method to suport is[Type], getProperty[Name] and
     * setProperty[Name] calls.
     *
     * <code>
     *  isPhoto()
     *  isRich()
     *  getPropertyProviderName($default = null)
     *  setPropertyUrl('http://example.com')
     * </code>
     *
     * @param unknown_type $name
     * @param array $arguments
     * @return mixed
     */
    public function __call($name, array $arguments) {}

    /**
     * Get property or return default value if not found
     *
     * @param string $name
     * @param mixed $default
     * @return string
     */
    public function getProperty($name, $default = null)
    {}

    /**
     * Set property or several properties of resource
     *
     * @param string|array $name
     * @param string value
     * @return Zend_Service_Oembed_Resource
     */
    public function setProperty($name, $value = null)
    {}

    /**
     * Checks if given property exists
     *
     * @param string $name
     * @return boolean
     */
    public function hasProperty($name)
    {}

    /**
     * Returns an array backing this resource.
     *
     * @return array
     */
    public function toArray()
    {}

    /**
     * Outputs string representation of resource
     *
     * @return string
     */
    public function __toString()
    {}

    /**
     * Converts name from camel case to words separated by _.
     *
     * @param string $name
     * @return string
     */
    protected function _underscorize($name)
    {}

    /**
     * Return Zend_Http_Reponse the object was constructed from and
     * raise exception if it wasn't constructed from it.
     *
     * @return Zend_Http_Response
     */
    public function getResponse() {}
    
    /**
     * Sorts properties in specifig order. If true is passed it will use
     * default sort order Zend_Service_Oembed_Resource::ORDER_DEFAULT. You can
     * pass custom order array instead. Does nothing if false is passed. 
     *
     * @param boolean|array $order
     * @return Zend_Service_Oembed_Client
     */
    public function order($order = true)
    {}

}

class Zend_View_Helper_OembedXml
{
    /**
     * Encodes oEmbed resource as XML. Turns layouts off by default. Switches
     * Content-Type to text/xml; charset=UTF-8.
     *
     * @param Zend_Service_Oembed_Resource $resource
     * @param boolean|array order Whether sort properties 
     * @param boolean $keepLayouts
     * @return string
     */
    public function oembedXml(Zend_Service_Oembed_Resource $resource, $order = true, $keepLayouts = false)
    {}
}

class Zend_View_Helper_OembedJson
{
    /**
     * Holds view reference
     *
     * @var Zend_View
     */
    protected $view;
    
    /**
     * Encodes oEmbed resource as JSON. Turns layouts off by default. Switches
     * Content-Type to application/json; charset=UTF-8.
     *
     * @param Zend_Service_Oembed_Resource $resource
     * @param boolean $keepLayouts
     * @param boolean|array Whether sort properties
     * @return string
     */
    public function oembedJson(Zend_Service_Oembed_Resource $resource, $order = true, $keepLayouts = false)
    {}
    
    public function setView(Zend_View_Interface $view)
    {}
    
}

Page Operations

Browse Space

Zend_Service_Oembed - Pawel Przeradowski

Labels