Zend_Service_Flickr 2.0 - Mickael Perraud

{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
ZF2: Zend_Service_Flickr
{zone-data}

{zone-data:proposer-list}
[~mikaelkael]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 10 August 2010: Initial Draft.
{zone-data}

{zone-data:overview}

{note:title=Note}
Even if you can find similarity with another [proposal|http://framework.zend.com/wiki/display/ZFPROP/Zend_Service_Flickr+-+Jurian+Sluiman], this one is only designed for ZF2 with no try to maintain backward compatibility.
{note}

Zend\Service\Flickr is a component to fetch data from Flickr, using the available [API|http://www.flickr.com/services/api/].

{info:title=Backwards compatibility}
Because the old Zend_Service_Flickr object has a complete different strucure, keeping backwards compatibility is impossible.
{info}
{zone-data}

{zone-data:references}
* [Flickr|http://flickr.com]
* [Flickr API overview|http://www.flickr.com/services/api/]
* [ZF1 doc: Zend_Service_Flickr|http://framework.zend.com/manual/en/zend.service.flickr.html]
* [ZF2 code: Zend\Service\Flickr|http://github.com/mikaelkael/zf2/tree/zsflickr]
{zone-data}

{zone-data:requirements}
* This component *will* use the Flickr API to handle requests.
* This component *will* be able to process authentication
* This component *will* be able to find users, photos, sets, collections, groups, tags, activities, blogs, favorites, interestingness, machinetags, pandas, geolocation, comments, notes and places
* This component *will* be able to write operations.
{zone-data}

{zone-data:dependencies}
* Zend\Service\Exception
* Zend\Config
* Zend\Cache
* Zend\Loader\PluginLoader
* Zend\Rest\Client
{zone-data}

{zone-data:operation}
This component can be use with or without knowing Flickr API. All Flickr objects are represented as PHP classes which have methods to load associated informations (eg. user::getPhotos or photo::getOwner).
The Flickr API is called with a REST client.

With a factory method from the Zend\Service\Flickr\Flickr class it's possible to instantiate all objects.
Each object extends FlickrObject (ObjectInterface) even a FlickrCollection (CollectionInterface). A FlickrCollection is a set of FlickrObject.
There are no magic methods.
Zend\Service\Flickr uses a plugin loader (ShortNameLocater) to load classes.
These classes needs to implement the Zend\Service\Flickr\ObjectInterface.
{zone-data}

{zone-data:milestones}
* Milestone 1: Design notes ready at proposers wiki
* Milestone 2: Working prototype and associated tests ready
* Milestone 3: Documentation ready
* Milestone 4: Component included in the framework
{zone-data}

{zone-data:class-list}
* Zend\Service\Flickr\Flickr
* Zend\Service\Flickr\ObjectInterface
* Zend\Service\Flickr\CollectionInterface
* Zend\Service\Flickr\FlickrObject
* Zend\Service\Flickr\FlickrCollection
* Zend\Service\Flickr\Exception
* Zend\Service\Flickr\Auth
* Zend\Service\Flickr\Bandwidth
* Zend\Service\Flickr\People
* Zend\Service\Flickr\Photo
* Zend\Service\Flickr\Photos
* Zend\Service\Flickr\Size
* Zend\Service\Flickr\Sizes
...
{zone-data}

{zone-data:use-cases}
{composition-setup}

{deck:id=use-cases1}
{card:label=UC 1: Initialize Flickr broker}
{code:type=php}
// Without authenticated access
$flickr = new Zend\Service\Flickr\Flickr(array('api_key' => 'MY-KEY',
'secret' => 'MY-SECRET'));
{code}
{card}

{card:label=UC 2: Authentication}
This is based on Flickr workflow (see also http://www.flickr.com/services/api/auth.howto.web.html)
h3. index.php
{code:type=php}
$auth = new Zend\Session\Container('Flickr');

if (!isset($auth['token'])) {
$flickr = new Zend\Service\Flickr\Flickr(array('api_key' => 'MY-KEY',
'secret' => 'MY-SECRET'));
$link = $flickr->auth()->generateTokenLink('read');
header('Location: ' . $link);
} else {
$flickr = new Flickr(array('api_key' => API_KEY,
'secret' => SECRET,
'token' => $auth['token']));
// do authenticated stuff...
}
{code}
h3. login.php
{code:type=php}
$auth = new Zend\Session\Container('Flickr');

$flickr = new Zend\Service\Flickr\Flickr(array('api_key' => 'MY-KEY',
'secret' => 'MY-SECRET'));
$flickrAuth = $flickr->auth()->getTokenFromFrob($_GET['frob']);
$auth['token'] = $flickrAuth->getToken();
echo '<a href="/flickr/index.php">Return to index</a>';
{code}
h3. logout.php
{code:type=php}
$auth = new Zend\Session\Container('Flickr');
unset($auth['token']);
{code}
{card}

{card:label=UC 3: Find user's photos}
{code:type=php}
// Case 1: based on API 'format' (http://www.flickr.com/services/api/flickr.people.findByUsername.html)
$user = $flickr->people()->findByUsername('zf.test'); // $user instanceof Zend\Service\Flickr\People
// Case 2: object oriented by user name
$user = new People($flickr);
$user->findByUsername('zf.test');
// Case 3: object oriented by Flickr ID
$user = new People(array('broker' => $flickr, 'nsid' => '52412852@N07');

$photos = $user->getPhotos(); // $photos instanceof Zend\Service\Flickr\Photos

foreach ($photos as $photo) { // $photo instanceof Zend\Service\Flickr\Photo
echo '<img src="' . $photo->getSizes()->get(Size::THUMBNAIL)->getSource() . " alt="' . $photo->getTitle() . '">';
}
{code}
{card}
{deck}
{zone-data}

{zone-data:skeletons}
{deck:id=use-cases1}

{card:label=SK 1: Zend\Service\Flickr\Flickr}
{code:type=php}

{code}
{card}

{deck}
{zone-data}

{zone-template-instance}