View Source

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

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

{zone-data:proposer-list}
[Duo Zheng|mailto:duozheng@gmail.com]
{zone-data}

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

{zone-data:revision}
1.0 - 23 June 2009: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Service_Tumblr is a full implementation of the Tumblr API. It provides an object oriented interface to the API and returns data as PHP data objects.
{zone-data}

{zone-data:references}
* [Tumblr API|http://www.tumblr.com/docs/api]
{zone-data}

{zone-data:requirements}
* This component *will* implement the full Tumblr API.
* This component should namespace the various API methods similar to Tumblr's API documentation where appropriate.
* This component should provide php data object representations for different post types that Tumblr offers.
{zone-data}

{zone-data:dependencies}
* Zend_Loader
* Zend_Service_Exception
* Zend_Http_Client
* Zend_Http_Client_Adapter_Curl
{zone-data}

{zone-data:operation}
Zend_Service_Tumblr will allow a developer to easily interact with the Tumblr API in a object oriented manner, supporting such actions as reading posts, creating posts, editing posts, validating credentials and getting account information. All data returned are represented as php data objects. Zend_Service_Tumblr creates a php client for the Tumblr API.
{zone-data}

{zone-data:milestones}
* Milestone 1: Proposal, Community Review and Acceptance
* Milestone 2: Unit-Testing and Development
* Milestone 3: Documentation and Testing
{zone-data}

{zone-data:class-list}
* Zend_Service_Tumblr_Exception
* Zend_Service_Tumblr
* Zend_Service_Tumblr_PostList
* Zend_Service_Tumblr_Post_Abstract
* Zend_Service_Tumblr_Post_Text
* Zend_Service_Tumblr_Post_Photo
* Zend_Service_Tumblr_Post_Quote
* Zend_Service_Tumblr_Post_Link
* Zend_Service_Tumblr_Post_Video
* Zend_Service_Tumblr_Post_Conversation
* Zend_Service_Tumblr_Post_Audio
* Zend_Service_Tumblr_Tumblelog
* Zend_Service_Tumblr_User
* Zend_Service_Tumblr_Feed
{zone-data}

{zone-data:use-cases}

||Creating New Posts||
{code:php|title="Text Post"}
//new text post
$post = $tumblr->createNewPost('text'); //also called "regular" post on Tumblr
$post->setTitle('Title');
$post->setBody('Body'); //HTML allowed
$post->save();
{code}

{code:php|title="Photo Post"}
//new photo post by source
$photoPost = $tumblr->createNewPost('photo');
$photoPost->setSource('http://farm4.static.flickr.com/3301/3520339109_4b734d9c5d_o.jpg');
$photoPost->setCaption('Wrecked Plane'); //optional, HTML allowed
$photoPost->setClickThroughUrl('http://www.flickr.com/photos/35149745@N02/3520339109/'); //optional
$photoPost->save();

//new photo post by data (local file)
$photoPost = $tumblr->createNewPost('photo');
$photoPost->setData('/path/to/photo.jpg'); //local file path
$photoPost->setCaption('Wrecked Plane'); //optional, HTML allowed
$photoPost->save();
{code}

{code:php|title="Quote Post"}
//new quote post
$quotePost = $tumblr->createNewPost('quote');
$quotePost->setQuote('A dog is the only thing on earth that loves you more than you love yourself.');
$quotePost->setSource('Josh Billings'); //optional, HTML allowed
$quotePost->save();
{code}

{code:php|title="Link Post"}
//new link post
$linkPost = $tumblr->createNewPost('link');
$linkPost->setName('Tumblr API Docs'); //optional
$linkPost->setUrl('http://www.tumblr.com/docs/api');
$linkPost->setDescription('Tumblr API documentation.'); //optional, HTML allowed
$linkPost->save();
{code}

{code:php|title="Conversation Post"}
//new conversation post
$conversationPost = $tumblr->createNewPost('conversation');
$conversationPost->setTitle('NYC Directions'); //optional
$conversationPost->setConversation("Tourist: Could you give us directions to Olive Garden?\nNew Yorker: No, but I could give you directions to an actual Italian restaurant.");
$conversationPost->save();
{code}

{code:php|title="Video Post"}
//new video post (embed)
$videoPost = $tumblr->createNewPost('video');
$videoPost->setEmbed('http://www.youtube.com/watch?v=7InTpNWJ4HQ'); //complete html code or url to YouTube video page
$videoPost->setCaption('Transformers 2 HD Trailer'); //optional, HTML allowed
$videoPost->save();

//new video post (vimeo upload)
$videoPost = $tumblr->createNewPost('video');
$videoPost->setTitle('Canon 5D Mark II Autofocusing'); //optional, only applies to Vimeo uploads
$videoPost->setData('/path/to/video.mov'); //local file path
$videoPost->setCaption('Just a test showing the new autofocusing feature'); //optional, HTML allowed
$videoPost->save(); //uploads video
{code}

{code:php|title="Audio Post"}
//new audio post
$audioPost = $tumblr->createNewPost('audio');
$audioPost->setData('/path/to/audio.mp3'); //local file path
$audioPost->setCaption('Awesome song'); //optional, HTML allowed
$audioPost->save(); //uploads file
{code}

{code:php|title="Optional Methods"}
//optional methods - applies to every type of post
$post->setGenerator('Zend_Service_Tumblr');
$post->setDate('2007-12-05 14:50:02');
$post->setPrivate(true);
$post->setTags(array(
'awesome',
'awesomeness',
'l33t'
));
//or
$post->addTag('awesome');
$post->setFormat('html');
$post->setGroup('mygroup.tumblr.com');
$post->setSlug('special string in url');
/**
* Valid State Values:
* Zend_Service_Tumblr::STATE_PUBLISHED
* Zend_Service_Tumblr::STATE_DRAFT
* Zend_Service_Tumblr::STATE_SUBMISSION
* Zend_Service_Tumblr::STATE_QUEUE
*/
$post->setState(Zend_Service_Tumblr::STATE_PUBLISHED);
// set publish on date in the future - both date and time are expressed in Tumblr's local time
$post->setPublishOnDate('2010-12-10 14:50:02');
/**
* Valid Values:
* boolean - true to send with auto generated summary of post., false to not send
* string - custom message to send to twitter for the post
*/
$post->setSendToTwitter(true);

{code}

||Modifying Posts||
{code:php|title="Edit Text Post"}
$post = $tumblr->editPost('text');
//set the id of the post you want to edit. This is essentially the same as making a new post just this replaces insteads of creating a new post
$post->setId('123456');
$post->setTitle('Modified Title');
$post->setBody('Modified Body'); //HTML allowed
{code}

{code:php|title="Delete Post"}
$tumblr->deletePost('123456');
{code}

||Authentication||

{code:php|title="Retrieving user attributes"}
$user = $tumblr->getUser();
$user->canUploadAudio();
$user->canUploadAiff();
$user->canUploadVideo();
$user->getMaxVideoBytesUploaded();
{code}

{code:php|title="Retrieving tumblelog attributes"}
$tumblelogs = $tumblr->getMyTumblelogs();
foreach($tumblelogs as $log){
$log->getTitle();
$log->getType(); //public or private
$log->isPrimary();

if($log->getType() == 'public'){
//methods specific to public tumblelogs only
$log->getName();
$log->getUrl();
$log->getAvatarUrl();
}

if($log->getType() == 'private'){
//methods specific to private tumblelogs only
$log->getPrivateId();
}
}
{code}

||Reading Posts||

{code:php|title="Get Posts"}
/**
* Does not require authentication
* ex. $tumblr = new Zend_Service_Tumblr(); is fine.
**/
//default behavior is to retrieve last 20 posts
$posts = $tumblr->getPosts('tumblraddress.tumblr.com');
foreach($posts as $post){
//methods for every type of post
$post->toArray();
$post->getId();
$post->getUrl();
$post->getDate();
$post->getFormat();

//methods for regular text posts - Zend_Service_Tumblr_Post_Text
if ($post->getType() == 'text') {
$post->getTitle();
$post->getBody();
}

//methods for photo posts - Zend_Service_Tumblr_Post_Photo
if ($post->getType() == 'photo') {
$post->getCaption();
$post->getLinkUrl();
//multiple sizes of the photo post.
foreach ($post->getPhotos() as $photo) {
$photo['maxWidth'];
$photo['url'];
}
}

//methods for quote posts - Zend_Service_Tumblr_Post_Quote
if ($post->getType() == 'quote') {
$post->getQuote();
$post->getSource();
}

//methods for link posts - Zend_Service_Tumblr_Post_Link
if ($post->getType() == 'link') {
$post->getLink();
$post->getUrl();
$post->getDescription();
}

//methods for conversation posts - Zend_Service_Tumblr_Post_Conversation
if ($post->getType() == 'conversation') {
$post->getTitle();
$post->getConversation();
}

//methods for video posts - Zend_Service_Tumblr_Post_Video
if ($post->getType() == 'video') {
$post->getCaption();
$post->getVideoSource();
$post->getVideoPlayer();
}

//methods for video posts - Zend_Service_Tumblr_Post_Audio
if ($post->getType() == 'audio') {
$post->getCaption();
$post->getAudioPlayer();
}
}
{code}

{code:php|title="Get Posts with optional paramaters"}
/**
* Full List of optional paramaters
start - The post offset to start from. The default is 0.
num - The number of posts to return. The default is 20, and the maximum is 50.
type - The type of posts to return. If unspecified or empty, all types of posts are returned.
Must be one of text, quote, photo, link, chat, video, or audio.
id - A specific post ID to return. Use instead of start, num, or type.
filter - Alternate filter to run on the text content. Allowed values:
text - Plain text only. No HTML.
none - No post-processing. Output exactly what the author entered.
(Note: Some authors write in Markdown, which will not be converted to HTML when this option is used.)
tagged - Return posts with this tag in reverse-chronological order (newest first).
Optionally specify chrono=1 to sort in chronological order (oldest first).
search - Search for posts with this query.
**/

//example of passing in an array of optional paramaters
$params = array(
'start' => 10,
'num' => 40
);
$posts = $tumblr->getPosts('tumblraddress.tumblr.com', $params);
{code}

{code:php|title="Get Tumblelog"}
/**
* Does not require authentication necessarily, but limited to certain data
* ex. $tumblr = new Zend_Service_Tumblr(); is fine.
**/
$tumblr = new Zend_Service_Tumblr(); //no email and password needed
$tumblelog = $tumblr->getTumblelog('tumblraddress.tumblr.com');
$tumblelog->getName();
$tumblelog->getTimezone();
$tumblelog->getTitle();
$tumblelog->getDescription();

/**
* Not authenticated tumblelog access can only retrieve:
* name
* timezone
* title
* description
**/

/**
* See use case labeled "Retrieving tumblelog attributes" for methods for authenticated tumblelog retrievals.
**/

//Feeds imported to tumblelog
if($tumblelog->feedsExist()){
foreach($tumblelog->getFeeds() as $feed){
$feed->getId();
$feed->getImportType();
$feed->getNextUpdateInSeconds();
}
}
{code}

{zone-data}

{zone-data:skeletons}
Currently "partial" working code: http://github.com/duoduo/Zend_Service_Tumblr/tree/master

{zone-data}

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