View Source

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


[Duo Zheng|]


1.0 - 23 June 2009: Initial Draft.

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.

* [Tumblr API|]

* 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.

* Zend_Loader
* Zend_Service_Exception
* Zend_Http_Client
* Zend_Http_Client_Adapter_Curl

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.

* Milestone 1: Proposal, Community Review and Acceptance
* Milestone 2: Unit-Testing and Development
* Milestone 3: Documentation and Testing

* 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


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

{code:php|title="Photo Post"}
//new photo post by source
$photoPost = $tumblr->createNewPost('photo');
$photoPost->setCaption('Wrecked Plane'); //optional, HTML allowed
$photoPost->setClickThroughUrl(''); //optional

//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

{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

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

{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.");

{code:php|title="Video Post"}
//new video post (embed)
$videoPost = $tumblr->createNewPost('video');
$videoPost->setEmbed(''); //complete html code or url to YouTube video page
$videoPost->setCaption('Transformers 2 HD Trailer'); //optional, HTML allowed

//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/'); //local file path
$videoPost->setCaption('Just a test showing the new autofocusing feature'); //optional, HTML allowed
$videoPost->save(); //uploads video

{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:php|title="Optional Methods"}
//optional methods - applies to every type of post
$post->setDate('2007-12-05 14:50:02');
$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
// 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


||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->setTitle('Modified Title');
$post->setBody('Modified Body'); //HTML allowed

{code:php|title="Delete Post"}


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

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

if($log->getType() == 'public'){
//methods specific to public tumblelogs only

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

||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('');
foreach($posts as $post){
//methods for every type of post

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

//methods for photo posts - Zend_Service_Tumblr_Post_Photo
if ($post->getType() == 'photo') {
//multiple sizes of the photo post.
foreach ($post->getPhotos() as $photo) {

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

//methods for link posts - Zend_Service_Tumblr_Post_Link
if ($post->getType() == 'link') {

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

//methods for video posts - Zend_Service_Tumblr_Post_Video
if ($post->getType() == 'video') {

//methods for video posts - Zend_Service_Tumblr_Post_Audio
if ($post->getType() == 'audio') {

{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('', $params);

{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('');

* 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
foreach($tumblelog->getFeeds() as $feed){


Currently "partial" working code: