View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{note:title=Abandoned}
The author of this proposal has indicated that they have abandoned development on it. If you would like to take over development, please contact the Community Review Team.
{note}

{zone-data:component-name}
Zend_Service_SmugMug
{zone-data}

{zone-data:proposer-list}
Tom Rix
{zone-data}

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

{zone-data:revision}
1.0 - 8 October 2008: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Service_SmugMug implements SmugMug's API version 1.2
{zone-data}

{zone-data:references}
* [SmugMug website|http://www.smugmug.com/]
* [SmugMug API 1.2.0 documentation|http://wiki.smugmug.net/display/SmugMug/API+1.2.0]
{zone-data}

{zone-data:requirements}
* This component *will* implement version 1.2.0 of the SmugMug API.
* This component *will* have a fluent, sensible objective interface
* This component *will not* implement the albumtemplates sector of the API
* This component *will* use the PHP interface over SOAP or XML-RPC.
* This component *will* use a binary upload method, rather than base64
{zone-data}

{zone-data:dependencies}
* Zend_Exception
* Zend_Http_Client
{zone-data}

{zone-data:milestones}
All dependencies are satisfied by the current release of the Zend Framework (1.6). Documented prototype code has been written that conforms to the requirements above.

* Milestone 1: \[DONE\] Write design docs
* Milestone 2: \[DONE\] Create prototype code
* Milestone 3: \[DONE\] Document prototype code
* Milestone 4: Working prototype checked into the incubator supporting use cases below
* Milestone 5: Adjust code based on peer review
* Milestone 6: Unit tests exist, work, and are checked into SVN.

{zone-data}

{zone-data:operation}
This works by making HTTP(S) calls to SmugMug's server, and deserializing the PHP response.
{zone-data}

{zone-data:class-list}
* Zend_Service_SmugMug
* Zend_Service_SmugMug_Album
* Zend_Service_SmugMug_User
* Zend_Service_SmugMug_Category
* Zend_Service_SmugMug_Subcategory
* Zend_Service_SmugMug_Image
* Zend_Service_SmugMug_Authentication
{zone-data}

{zone-data:use-cases}
||UC-01: Logging in||
{code}
$smugmug = new Zend_Service_SmugMug('API-KEY');
Zend_Service_SmugMug_Authentication::loginWithPassword($smugmug, 'tom@rixth.org', 'password');
{code}
||UC-02: Creating an album||
{code}
$smugmug = new Zend_Service_SmugMug('API-KEY');
Zend_Service_SmugMug_Authentication::loginWithPassword($smugmug, 'tom@rixth.org', 'password');
$albums = new Zend_Service_SmugMug_Album();
$albums->create('My new album', 0);
{code}
||UC-03: Uploading a picture||
{code}
$smugmug = new Zend_Service_SmugMug('API-KEY');
Zend_Service_SmugMug_Authentication::loginWithPassword($smugmug, 'tom@rixth.org', 'password');
$albums = new Zend_Service_SmugMug_Album();
$albums->create('My new album', 0);
{code}
||UC-04: Retrieving album statistics||
{code}
$smugmug = new Zend_Service_SmugMug('API-KEY');
Zend_Service_SmugMug_Authentication::loginWithPassword($smugmug, 'tom@rixth.org', 'password');
$albums = new Zend_Service_SmugMug_Album();
$albums->getStats(123456);
{code}
{zone-data}

{zone-data:skeletons}
||Zend_Service_SmugMug||
{code}/**
* Zend_Service_SmugMug is an implementation of the smugmug api
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug
{
const USER_AGENT = 'Zend_Service_SmugMug 1.6';

const API_VERSION = '1.2.0';

const API_URI = 'http://api.smugmug.com/hack/php/1.2.0/';
const SECURE_API_URI = 'https://api.smugmug.com/hack/php/1.2.0/';
const UPLOAD_API_URI = 'http://upload.smugmug.com/';
const SECURE_UPLOAD_API_URI = 'https://upload.smugmug.com/';

/**
* application api key
*
* @var string
*/
protected $_apiKey = '';

/**
* URL for the next request
*
* @var string
*/
protected $_forceUrl = '';

/**
* are we using the secure API urls
*
* @var bool
*/
protected $_secure = false;

/**
* authentication session id
*
* @var string
*/
protected $_sessionId = '';

/**
* httpClient is the Zend_Http_Client object used for the api calls
*
* @var Zend_Http_Client
*/
protected $_httpClient;

/**
* Constructs a new smugmug api client
*
* @param string $apiKey API key provided by smugmug
* @param bool $secure whether to use the https API endpoint
* @return void
*/
public function __construct($apiKey, $secure = false)

/**
* Make a request
*
* @param string $method request method
* @param bool $resetParameters reset the params after the request
* @param bool $resetClient reset the whole client (to clear out headers)
* @return Zend_Http_Response
*/
public function makeRequest($method = Zend_Http_Client::GET, $resetParameters = true, $resetClient = false)

/**
* Force the next request to go over specific URL (such as SSL, or to the upload URL)
*
*/
public function forceUrl($url)

/**
* Replace the HTTP client with another, IE, if you want to use a proxy
*
* @param Zend_Http_Client $client
*/
public function setHttpClient(Zend_Http_Client $client)

/**
* Set the sessionID to use on requests
*
* @param string $sessionId
*/
public function setSessionId($sessionId)

/**
* Get the sessionID to used on requests
*
* @return string
*/
public function getSessionId()

/**
* Is the session secure?
*
* @return bool
*/
public function isSecure()

/**
* Get the http client used by the service
*
* @return Zend_Http_Client
*/
public function getClient()
}{code}
||Zend_Service_SmugMug_Album||
{code}/**
* Represents an album on smugmug
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2006 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_Album implements SeekableIterator, Countable
{

/**
* @see SeekerableIterator
*
* @var int
*/
protected $_pointer = 0;

/**
* @see SeekerableIterator
*
* @var array
*/
protected $_data = array();

/**
* the service class
*
* @var Zend_Service_SmugMug
*/
protected $_service;

/**
* Creates a new Album interface
*
* @param Zend_Service_SmugMug $service
*/
public function __construct(Zend_Service_SmugMug $service)

/**
* Create a new album
*
* @param string $title
* @param int $categoryId
* @param array $otherParams as specified in the API documentation 1.2
* @return array
*/
public function create($title, $categoryId, $otherParams = array())

/**
* Change settings for an album
*
* @param int $albumId
* @param array $settings as specified in the API documentation 1.2
* @return array
*/
public function changeSettings($albumId, $settings)

/**
* Delete an album
*
* @param int $albumId
* @return bool
*/
public function delete($albumId)

/**
* Get information about an album
*
* @param int|null $albumId
* @param string|null $albumKey
* @param string|null $password
* @param string|null $sitePassword
* @return array
*/
public function getInfo($albumId = null, $albumKey = null, $password = null, $sitePassword = null)

/**
* Get statistics about an album
*
* @param int $albumId
* @param int|null $month the month to get stats for, if left null, will default to current month
* @param int|null $year the year to get stats for, if left null, will default to current year
* @param bool $heavy whether to get stats for each image in the album (default: false)
* @return array
*/
public function getStats($albumId, $month = null, $year = null, $heavy = false)

/**
* Re-order the images in an album
*
* @param int $albumId
* @param string $sortBy can be FileName, Caption or DateTime
* @param string $sortDirection either ASC or DESC
* @return array
*/
public function reSort($albumId, $sortBy, $sortDirection)

/**
* Get a user's albums
*
* @param string $nickname user to retrieve albums for
* @param string $sitePassword the password if the user has one
* @param bool $heavy if true, more information about each album will be retrieved (default: false)
* @return Zend_Service_SmugMug_Album
*/
public function getAlbums($nickname, $sitePassword, $heavy)

/**
* Get an albums' images
*
* @oaram int $albumId
* @param bool $heavy if true, more information about each album will be retrieved (default: false)
* @return Zend_Service_SmugMug_Image
*/
function getImages($albumId, $heavy = false) {

/**
* Add an album to the internal array
*
* @param array $album
*/
public function addAlbum($album)
}{code}
||Zend_Service_SmugMug_User||
{code}<?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: Digg.php 6673 2007-10-22 10:28:51Z lcrouch $
*/

/**
* Zend_Service_SmugMug_User represents a user/session on SmugMug
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_User
{
/**
* the service class
*
* @var Zend_Service_SmugMug
*/
protected $_service;

/**
* user's nickname
*
* @var string
*/
protected $_nickname;

/**
* user's display name
*
* @var string
*/
protected $_displayName;

/**
* user's account type
*
* @var string
*/
protected $_accountType;

/**
* user's filesize limit
*
* @var int
*/
protected $_fileSizeLimit;

/**
* user's password hash
*
* @var string
*/
protected $_passwordHash;

/**
* Create a new representation of a user
*
* @param Zend_SmugMug_Service $service
* @param string $sessionId
* @param string $nickname
* @param string $displayName
* @param string $accountType
* @param string $fileSizeLimit
*/
function __construct(Zend_Service_SmugMug $service, $sessionId = null, $nickname = null, $displayName = null, $accountType = null, $fileSizeLimit = null, $passwordHash = null) {

/**
* Get this users' albums
*
* @param bool $heavy if true, more information about each album will be retrieved (default: false)
* @return Zend_Service_SmugMug_Album
*/
function getAlbums($heavy = false) {

/**
* Get this users' categories
*
* @return Zend_Service_SmugMug_Category
*/
function getCategories($heavy = false) {

/**
* Get all of this users' subcategories
*
* @return Zend_Service_SmugMug_Subategory
*/
function getSubcategories() {

/**
* Get statistics about this user
*
* @param int|null $month the month to get stats for, if left null, will default to current month
* @param int|null $year the year to get stats for, if left null, will default to current year
* @param bool $heavy whether to get stats for each image in each album (default: false)
* @return array
*/
public function getTransferStats($month = null, $year = null, $heavy = false)

/**
* Get the album tree structure for a user
*
* @param string $nickname user to retrieve albums for if null, will default to current user
* @param string $sitePassword the password if the user has one
* @param bool $heavy if true, more information about each album will be retrieved (default: false)
* @return Zend_Service_SmugMug_Album
*/
public function getTree($nickname = null, $sitePassword = null, $heavy = false)

/**
* @return string
*/
public function getAccountType() {

/**
* @return string
*/
public function getDisplayName() {

/**
* @return integer
*/
public function getFileSizeLimit() {

/**
* @return string
*/
public function getNickname() {

/**
* @return session id
*/
public function getSessionId() {
}{code}
||Zend_Service_SmugMug_Category||
{code}/**
* Represents categories on smugmug
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2006 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_Category implements SeekableIterator, Countable
{
/**
* @see SeekerableIterator
*
* @var int
*/
protected $_pointer = 0;

/**
* @see SeekerableIterator
*
* @var array
*/
protected $_data = array();

/**
* the service class
*
* @var Zend_Service_SmugMug
*/
protected $_service;

/**
* Creates a new Category interface
*
* @param Zend_Service_SmugMug $service
*/
public function __construct(Zend_Service_SmugMug $service)

/**
* Create a new category
*
* @param string $name
* @return int the category ID
*/
public function create($name)

/**
* Delete a category
*
* @param int $categoryId
* @return bool
*/
public function delete($categoryId)

/**
* Rename a category
*
* @param int $categoryId
* @param string $name
* @return bool
*/
public function rename($categoryId, $name)

/**
* Get a user's categories
*
* @param string $nickname user to retrieve categories for
* @param string $sitePassword the password if the user has one
* @return Zend_Service_SmugMug_Category
*/
public function getCategories($nickname, $sitePassword = null)

/**
* Add a category to the internal array
*
* @param array $category
*/
public function addCategory($category) {

}{code}
||Zend_Service_SmugMug_Subcategory||
{code}/**
* Represents subcategories on smugmug
*
* @subcategory Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2006 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_Subcategory implements SeekableIterator, Countable
{

/**
* @see SeekerableIterator
*
* @var int
*/
protected $_pointer = 0;

/**
* @see SeekerableIterator
*
* @var array
*/
protected $_data = array();

/**
* the service class
*
* @var Zend_Service_SmugMug
*/
protected $_service;

/**
* Creates a new Subcategory interface
*
* @param Zend_Service_SmugMug $service
*/
public function __construct(Zend_Service_SmugMug $service)

/**
* Create a new subcategory
*
* @param int $categoryId - parent category ID
* @param string $name
* @return int the subcategory ID
*/
public function create($categoryId, $name)

/**
* Delete a subcategory
*
* @param int $subcategoryId
* @return bool
*/
public function delete($subcategoryId)

/**
* Rename a subcategory
*
* @param int $subcategoryId
* @param string $name
* @return bool
*/
public function rename($subcategoryId, $name)

/**
* Get all a user's subcategories
*
* @param string $nickname user to retrieve subcategories for
* @param string $sitePassword the password if the user has one
* @return Zend_Service_SmugMug_Subcategory
*/
public function getAllSubcategories($nickname, $sitePassword = null)

/**
* Get a categories' subcategories
*
* @param string $nickname category to retrieve subcategories for
* @param string $nickname user to retrieve subcategories for
* @param string $sitePassword the password if the user has one
* @return Zend_Service_SmugMug_Subcategory
*/
public function getSubcategories($categoryId, $nickname = null, $sitePassword = null)

/**
* Add a subcategory to the internal array
*
* @param array $subcategory
*/
public function addSubcategory($subcategory) {
}{code}
||Zend_Service_SmugMug_Image||
{code}/**
* Represents images on smugmug
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2006 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_Image implements SeekableIterator, Countable
{

/**
* @see SeekerableIterator
*
* @var int
*/
protected $_pointer = 0;

/**
* @see SeekerableIterator
*
* @var array
*/
protected $_data = array();

/**
* the service class
*
* @var Zend_Service_SmugMug
*/
protected $_service;

/**
* Creates a new Image interface
*
* @param Zend_Service_SmugMug $service
*/
public function __construct(Zend_Service_SmugMug $service)

/**
* Upload an image to an album
*
* @param int $albumId
* @param string $filename
* @param string|null $caption
* @param array $settings as specified in the API documentation 1.2
* @return array
*/
public function upload($albumId, $filename, $caption = null, $settings = array())

/**
* Change settings for an image
*
* @param int $albumId
* @param array $settings as specified in the API documentation 1.2
* @return array
*/
public function changeSettings($imageId, $settings)

/**
* Move image to another album
*
* @param int $imageId
* @param int $albumId
* @return array
*/
public function relocate($imageId, $albumId)

/**
* Set the caption on an image
*
* @param int $imageId
* @param string $caption
* @return array
*/
public function setCaption($imageId, $caption)

/**
* Set the keywords of an image
*
* @param int $imageId
* @param string $keywords
* @return array
*/
public function setKeywords($imageId, $keywords)

/**
* Set an image to hidden, or not
*
* @param int $imageId
* @param bool $hidden
* @return array
*/
public function setHidden($imageId, $hidden)

/**
* Change the position of an image in an album
*
* @param int $imageId
* @param int $position
* @return array
*/
public function changePosition($imageId, $position)

/**
* Delete an image
*
* @param int $imageId
* @return bool
*/
public function delete($imageId)

/**
* Get EXIF information about an image
*
* @param int|null $imageId
* @param string|null $imageKey
* @param string|null $password
* @param string|null $sitePassword
* @return array
*/
public function getEXIF($imageId = null, $imageKey = null, $password = null, $sitePassword = null)

/**
* Get URLs for an image
*
* @param int|null $imageId
* @param string|null $imageKey
* @param int|null $templateId 3, 4, 7, 8, 9 as referenced on the API docs (default: 3)
* @param string|null $password
* @param string|null $sitePassword
* @return array
*/
public function getURLs($imageId = null, $imageKey = null, $templateId = 3, $password = null, $sitePassword = null)

/**
* Get information about an image
*
* @param int|null $imageId
* @param string|null $imageKey
* @param string|null $password
* @param string|null $sitePassword
* @return array
*/
public function getInfo($imageId = null, $imageKey = null, $password = null, $sitePassword = null)

/**
* Get statistics about an image
*
* @param int $imageId
* @param int|null $month the month to get stats for, if left null, will default to current month
* @param int|null $year the year to get stats for, if left null, will default to current year
* @return array
*/
public function getStats($imageId, $month = null, $year = null)

/**
* Get images in an album
*
* @param int $albumId
* @param string $nickname user to retrieve albums for
* @param string $sitePassword the password if the user has one
* @param bool $heavy if true, more information about each album will be retrieved (default: false)
* @return Zend_Service_SmugMug_Image
*/
public function getImages($albumId, $nickname = null, $sitePassword = null, $heavy = false)

/**
* Add an image to the internal array
*
* @param array $image
*/
public function addImage($image) {
}{code}
||Zend_Service_SmugMug_Authentication||
{code}/**
* Zend_Service_SmugMug_Authentication implements the authentication API methods for SmugMug
*
* @category Zend
* @package Zend_Service
* @subpackage SmugMug
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Service_SmugMug_Authentication
{
/**
* Login anonymously
*
* @param Zend_Service_SmugMug $service
* @return Zend_Service_SmugMug_User
*/
static public function loginAnonymously(Zend_Service_SmugMug $service)

/**
* Login with a username and hash
*
* @param Zend_Service_SmugMug $service
* @param string $userId
* @param string $hash
* @return Zend_Service_SmugMug_User
*/
static public function loginWithHash(Zend_Service_SmugMug $service, $userId, $hash)

/**
* Login with a username and password
*
* @param Zend_Service_SmugMug $service
* @return Zend_Service_SmugMug_User
*/
static public function loginWithPassword(Zend_Service_SmugMug $service, $emailAddress, $password)

/**
* Log a session out
*
* @param Zend_Service_SmugMug $service
* @param string $emailAddress
* @param string $password
* @return string Zend_Service_SmugMug_User
*/
static public function logout(Zend_Service_SmugMug $service)
}{code}
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>