Zend Framework: Zend_Service_RememberTheMilk Component Proposal

Proposed Component Name	Zend_Service_RememberTheMilk
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_RememberTheMilk
Proposers	Matthew Turland Darby Felton, Zend liaison
Revision	1.0 - 25 March 2007 Initial draft 1.1 - 20 December 2007 Added missing return types for convertTime() and parseTime() in the main class Added missing IteratorAggregate implementation declarations for the TaskList and TimezoneList classes Updated addTags(), setTags(), and removeTags() in the TaskSeries class to take a string as well as an array (wiki revision: 7)

Accepts an API key and automatically includes it as a parameter in subsequent
method calls.
Supports all API methods excluding those listed under rtm.test (for which
support is not planned) and rtm.timelines (which will be handled internally).
Naming conventions will differ from those in the API itself, but will be
similar enough that they should prove intuitive to users.
Returns server responses as lightweight data objects.

4. Dependencies on Other Framework Components

Zend_Rest_Client
Zend_Service_Exception

5. Theory of Operation

Performs the requested API call and returns the server response in the form of a
data object. Authentication is handled internally using a user-specified API
key. Timelines (essentially user session identifiers to allow for reversal of
previous transactions) are also handled internally without any user
intervention.

6. Milestones / Tasks

Milestone 1: [DONE] Design notes will be published here
Milestone 2: Working prototype will be checked into the incubator
Milestone 3: Working unit tests will be checked into the incubator
Milestone 4: Documentation will be checked into the incubator

7. Class Index

Zend_Service_RememberTheMilk
Zend_Service_RememberTheMilk_Token
Zend_Service_RememberTheMilk_Contact
Zend_Service_RememberTheMilk_ContactList
Zend_Service_RememberTheMilk_Group
Zend_Service_RememberTheMilk_GroupList
Zend_Service_RememberTheMilk_List
Zend_Service_RememberTheMilk_ListList
Zend_Service_RememberTheMilk_Method
Zend_Service_RememberTheMilk_Argument
Zend_Service_RememberTheMilk_ArgumentList
Zend_Service_RememberTheMilk_Error
Zend_Service_RememberTheMilk_ErrorList
Zend_Service_RememberTheMilk_Settings
Zend_Service_RememberTheMilk_Task
Zend_Service_RememberTheMilk_TaskList
Zend_Service_RememberTheMilk_TaskSeries
Zend_Service_RememberTheMilk_Timezone
Zend_Service_RememberTheMilk_TimezoneList

8. Use Cases

$rtm = new Zend_Service_RememberTheMilk('API_KEY');

/* rtm.auth */
$frob = $rtm->getFrob();
$token = $rtm->getToken($frob);
$token = $rtm->checkToken($token->getToken());
print_r($token->getPerms());
$contact = $token->getUser();

/* rtm.contacts */
$rtm->addContact('tobias382');
$contactList = $rtm->getContactList();
foreach ($contactList as $contact) {
  echo $contact->getId() . "\n";
  echo $contact->getFullname() . "\n";
  echo $contact->getUsername() . "\n";
}
$rtm->deleteContact($contact->getId());

/* rtm.groups */
$rtm->addGroup('Test Group');
$groupList = $rtm->getGroupList();
foreach ($groupList as $group) {
  echo $group->getId() . "\n";
  echo $group->getName() . "\n";
  print_r($group->getContacts());
}
$group->addContact($contact->getId());
$group->removeContact($contact->getId());
$rtm->deleteGroup($group->getId());

/* rtm.lists */
$list = $rtm->addList('Test List');
$rtm->setDefaultList($list->getId());
$listList = $rtm->getListList();
foreach ($listList as $list) {
  echo $list->getId() . "\n";
  echo $list->getName() . "\n";
  echo $list->getPosition() . "\n";
  echo $list->getFilter() . "\n";
  echo $list->isDeleted() . "\n";
  echo $list->isLocked() . "\n";
  echo $list->isArchived() . "\n";
  echo $list->isSmart() . "\n";
}
$list->archive();
$list->unarchive();
$list->setName('New List Name');
$rtm->deleteList($list->getId());

/* rtm.reflection */
$methods = $rtm->getMethods();
print_r($methods);
$method = $rtm->getMethodInfo(current($methods));
echo $method->getName() . "\n";
echo $method->needsLogin() . "\n";
echo $method->needsSigning() . "\n";
echo $method->requiredPerms() . "\n";
echo $method->getDescription() . "\n";
echo $method->getResponse() . "\n";
$argumentList = $method->getArguments();
foreach ($argumentList as $argument) {
  echo $argument->getName() . "\n";
  echo $argument->isOptional() . "\n";
  echo $argument->getDescription() . "\n";
}
$errorList = $method->getErrors();
foreach ($errorList as $error) {
  echo $error->getCode() . "\n";
  echo $error->getMessage() . "\n";
  echo $error->getDescription() . "\n";
}

/* rtm.settings */
$settings = $rtm->getSettings();
echo $settings->getTimezone() . "\n";
echo $settings->getDateFormat() . "\n";
echo $settings->getTimeFormat() . "\n";
echo $settings->getDefaultList() . "\n";
echo $settings->getLanguage() . "\n";

/* rtm.tasks */
$task = $list->addTask($list->getId(), 'Test Task');
echo $task->getId() . "\n";
echo $task->getDueDate() . "\n";
echo $task->hasDueTime() . "\n";
echo $task->getAddedDate() . "\n";
echo $task->getCompletedDate() . "\n";
echo $task->getDeletedDate() . "\n";
echo $task->getPriority() . "\n";
echo $task->isPostponed() . "\n";
echo $task->getEstimate() . "\n";
$task->setDueDate('2006-05-07T10:19:54Z', true, true);
$task->setEstimate('2 hrs');
$task->setPriority(3);
$task->setRecurrence('Every Tuesday');
$task->complete();
$task->uncomplete();
$task->increasePriority();
$task->decreasePriority();
$task->postpone();
$task->moveTo($list->getId());
$rtm->deleteTask($task->getId());
$taskSeries = $task->getSeries();
echo $taskSeries->getId() . "\n";
echo $taskSeries->getName() . "\n";
echo $taskSeries->getListId() . "\n";
echo $taskSeries->getCreatedDate() . "\n";
echo $taskSeries->getModifiedDate() . "\n";
echo $taskSeries->getSource() . "\n";
$taskSeries->setName('New Task Name');
$taskSeries->addTags(array('tag1', 'tag2'));
$taskSeries->setTags(array('tag1', 'tag2'));
$taskSeries->removeTags(array('tag1', 'tag2'));
$taskSeries->setUrl('http://framework.zend.com');
print_r($taskSeries->getTags());
print_r($taskSeries->getParticipants());
print_r($taskSeries->getNotes());

/* rtm.notes */
$note = $task->addNote('Note Title', 'Note Text');
$note->setTitle('Updated Note Title');
$note->setText('Updated Note Text');
$note->save();
$rtm->deleteNote($note->getId());

/* rtm.time */
$rtm->convertTime($toTimezone->getName(), $fromTimezone->getName(), 'now');
$rtm->parseTime('14/02/2006', $timezone->getName(), false);

/* rtm.timezones */
$timezoneList = $rtm->getTimezoneList();
foreach ($timezoneList as $timezone) {
  echo $timezone->getId() . "\n";
  echo $timezone->getName() . "\n";
  echo $timezone->isDST() . "\n";
  echo $timezone->getOffset() . "\n";
  echo $timezone->getCurrentOffset() . "\n";
}

/* rtm.transactions.undo */
$rtm->undo();

9. Class Skeletons

class Zend_Service_RememberTheMilk {
  
  /**
  * @param string $apiKey API Key
  * @return void
  */
  public function __construct($apiKey);
  
  /**
  * @return string
  */
  public function getFrob();
  
  /**
  * @param string $frob Frob
  * @return Zend_Service_RememberTheMilk_Token
  */
  public function getToken($frob);
  
  /**
  * @param string $token Token string
  * @return Zend_Service_RememberTheMilk_Token
  */
  public function checkToken($token);
  
  /**
  * @param string $contact Username or e-mail address of a registered Remember 
  *                        The Milk user to add
  * @return Zend_Service_RememberTheMilk_Contact
  */
  public function addContact($contact);
  
  /**
  * @return Zend_Service_RememberTheMilk_ContactList
  */
  public function getContactList();
  
  /**
  * @param int $contactId ID of the contact to delete
  * @return void
  */
  public function deleteContact($contactId);
  
  /**
  * @param string $group Name of the group to create
  * @return Zend_Service_RememberTheMilk_Group
  */
  public function addGroup($group);
  
  /**
  * @return Zend_Service_RememberTheMilk_GroupList
  */
  public function getGroupList();
  
  /**
  * @param int $groupId ID of the group to delete
  * @return void
  */
  public function deleteGroup($groupId);
  
  /**
  * @param string $name Desired list name (cannot be Inbox or Sent)
  * @param string $filter Criteria if list should be a Smart List (optional)
  * @return void
  */
  public function addList($name, $filter = null);
  
  /**
  * @param int $listId ID of the list to set as the default list
  * @return void
  */
  public function setDefaultList($listId);
  
  /**
  * @return Zend_Service_RememberTheMilk_ListList
  */
  public function getListList();
  
  /**
  * @param int $listId ID of the list to delete
  * @return void
  */
  public function deleteList($listId);
  
  /**
  * @return array Strings containing method names
  */
  public function getMethods();
  
  /**
  * @param string $methodName Name of the method to fetch information for
  * @return Zend_Service_RememberTheMilk_Method
  */
  public function getMethodInfo();
  
  /**
  * @return Zend_Service_RememberTheMilk_Settings
  */
  public function getSettings();
  
  /**
  * @param int $taskId ID of the task to delete
  * @return void
  */
  public function deleteTask($taskId);
  
  /**
  * @param string $toTimezone Target timezone
  * @param string $fromTimezone Originating timezone (optional)
  * @param string $time Time to convert in ISO 8601, defaults to now (optional)
  * @return string Converted time in ISO 8601
  */
  public function convertTime($toTimezone, $fromTimezone = null, $time = null);
  
  /**
  * @param string $text Text to parse
  * @param string $timezone Timezone with respect to which text should be parsed
  * @param bool $dateFormat TRUE to use American format (02/14/2006), FALSE to 
  *                         use European format (14/02/2006) (optional)
  * @return string Parsed time in ISO 8601
  */
  public function parseTime($text, $timezone = null, $dateFormat = false);
  
  /**
  * @return Zend_Service_RememberTheMilk_TimezoneList
  */
  public function getTimezoneList();
  
  /**
  * @return void
  */
  public function undo();

}

class Zend_Service_RememberTheMilk_Token {

  /**
  * @return string
  */
  public function getToken();
  
  /**
  * @return Zend_Service_RememberTheMilk_Contact
  */
  public function getUser();

  /**
  * @return array
  */
  public function getPerms();

}

class Zend_Service_RememberTheMilk_Contact {

  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getFullname();
  
  /**
  * @return string
  */
  public function getUsername();

}

class Zend_Service_RememberTheMilk_ContactList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc XML response to rtm.contacts.getList call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();
  
}

class Zend_Service_RememberTheMilk_Group {

  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getName();
  
  /**
  * @return array Contact ID values
  */
  public function getContacts();
  
  /**
  * @param int $contactId ID of the contact to add to the group
  */
  public function addContact($contactId);
  
  /**
  * @param int $contactId ID of the contact to delete from the group
  */
  public function deleteContact($contactId);

}

class Zend_Service_RememberTheMilk_GroupList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc XML response to rtm.groups.getList call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();

}

class Zend_Service_RememberTheMilk_List {

  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getName();
  
  /**
  * @param string $name Desired list name (cannot be Inbox or Sent)
  */
  public function setName($name);
  
  /**
  * @return int
  */
  public function getPosition();
  
  /**
  * @return string
  */
  public function getFilter();
  
  /**
  * @return bool
  */
  public function isDeleted();
  
  /**
  * @return bool
  */
  public function isLocked();
  
  /**
  * @return bool
  */
  public function isArchived();
  
  /**
  * @return bool
  */
  public function isSmart();
  
  /**
  * @return void
  */
  public function archive();
  
  /**
  * @return void
  */
  public function unarchive();
  
  /**
  * @param string $name Desired task name
  * @return Zend_Service_RememberTheMilk_Task
  */
  public function addTask($name);
  
}

class Zend_Service_RememberTheMilk_ListList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc XML response to rtm.lists.getList call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();

}

class Zend_Service_RememberTheMilk_Method {
  
  /**
  * @return string
  */
  public function getName();
  
  /**
  * @return bool
  */
  public function needsLogin();
  
  /**
  * @return bool
  */
  public function needsSigning();
  
  /**
  * @return bool
  */
  public function requiredPerms();
  
  /**
  * @return string
  */
  public function getDescription();
  
  /**
  * @return string
  */
  public function getResponse();
  
  /**
  * @return Zend_Service_RememberTheMilk_ArgumentList
  */
  public function getArguments();
  
}

class Zend_Service_RememberTheMilk_Argument {

  /**
  * @return string
  */
  public function getName();
  
  /**
  * @return bool
  */
  public function isOptional();
  
  /**
  * @return string
  */
  public function getDescription();

}

class Zend_Service_RememberTheMilk_ArgumentList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc Arguments block of the XML response to a 
  *                         rtm.reflection.getMethodInfo call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();

}

class Zend_Service_RememberTheMilk_Error {
  
  /**
  * @return int
  */
  public function getCode();
  
  /**
  * @return string
  */
  public function getMessage();
  
  /**
  * @return string
  */
  public function getDescription();

}

class Zend_Service_RememberTheMilk_ErrorList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc Errors block of the XML response to a 
  *                         rtm.reflection.getMethodInfo call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();

}

class Zend_Service_RememberTheMilk_Settings {
  
  /**
  * @return string
  */
  public function getTimezone();
  
  /**
  * @return bool TRUE for American (e.g. 02/14/06), FALSE for European 
  *         (e.g. 14/02/06)
  */
  public function getDateFormat();
  
  /**
  * @return bool TRUE for 24 hour time (e.g. 17:00), FALSE for 12 hour time
  *              (e.g. 5pm)
  */
  public function getTimeFormat();
  
  /**
  * @return int ID of the default list, or NULL if no default is set
  */
  public function getDefaultList();
  
  /**
  * @return string Language (ISO 639-1 code)
  */
  public function getLanguage();

}

class Zend_Service_RememberTheMilk_Task {
  
  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getDueDate();
  
  /**
  * @return bool
  */
  public function hasDueTime();
  
  /**
  * @return string
  */
  public function getAddedDate();
  
  /**
  * @return string
  */
  public function getCompletedDate();
  
  /**
  * @return string
  */
  public function getDeletedDate();
  
  /**
  * @return int
  */
  public function getPriority();
  
  /**
  * @return bool
  */
  public function isPostponed();
  
  /**
  * @return string
  */
  public function getEstimate();
  
  /**
  * @param string $due Due date for the task, in ISO 8601 format
  * @param bool $hasDueTime TRUE if $due has a time, FALSE otherwise (optional)
  * @param bool $parse TRUE to have $due be parsed with rtm.time.parse, FALSE
  *             otherwise
  * @return void
  */
  public function setDueDate($due, $hasDueTime = false, $parse = false);
  
  /**
  * @param string $estimate Time estimate for the task with units of days, 
  *                         hours, or minutes, or NULL to unset any existing 
  *                         estimate for the task
  * @return void
  */
  public function setEstimate($estimate = null);
  
  /**
  * @param int $priority 1, 2, or 3, or any other value to unset any existing 
  *                      priority for the task (optional)
  * @return void
  */
  public function setPriority($priority = null);
  
  /**
  * @param string $repeat Recurrence pattern, or NULL to unset any existing
  *                       recurrence pattern (optional)
  * @return void
  */
  public function setRecurrence($repeat = null);
  
  /**
  * @return void
  */
  public function complete();
  
  /**
  * @return void
  */
  public function uncomplete();
  
  /**
  * @return void
  */
  public function increasePriority();
  
  /**
  * @return void
  */
  public function decreasePriority();
  
  /**
  * @return void
  */
  public function postpone();
  
  /**
  * @param int $listId Target list ID
  * @return void
  */
  public function moveTo($listId);
  
  /**
  * @return Zend_Service_RememberTheMilk_TaskSeries
  */
  public function getSeries();

  /**
  * @param Zend_Service_RememberTheMilk_TaskSeries $series
  */
  public function setSeries(Zend_Service_RememberTheMilk_TaskSeries $series);

}

class Zend_Service_RememberTheMilk_TaskList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc XML response to a rtm.tasks.getList call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();
  
}

class Zend_Service_RememberTheMilk_TaskSeries {
  
  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getName();
  
  /**
  * @return int
  */
  public function getListId();
  
  /**
  * @return string
  */
  public function getCreatedDate();
  
  /**
  * @return string
  */
  public function getModifiedDate();
  
  /**
  * @return string
  */
  public function getSource();
  
  /**
  * @param string $name Desired task name
  * @return void
  */
  public function setName($name);
  
  /**
  * @param string|array $tags Tag(s) to add
  * @return void
  */
  public function addTags($tags);
  
  /**
  * @param string|array $tags Tag(s) to add, overwriting any existing tags, or an empty
  *                           string or array to clear any existing tags (optional)
  * @return void
  */
  public function setTags($tags = '');
  
  /**
  * @param string|array $tags Tag(s) to remove
  * @return void
  */
  public function removeTags($tags);
  
  /**
  * @param string $url URL to associate with the task
  * @return void
  */
  public function setUrl($url);
  
  /**
  * @return array
  */
  public function getTags();
  
  /**
  * @return array
  */
  public function getParticipants();
  
  /**
  * @return array
  */
  public function getNotes();
  
}

class Zend_Service_RememberTheMilk_Timezone {
  
  /**
  * @return int
  */
  public function getId();
  
  /**
  * @return string
  */
  public function getName();
  
  /**
  * @return bool
  */
  public function isDST();
  
  /**
  * @return int
  */
  public function getOffset();
  
  /**
  * @return int
  */
  public function getCurrentOffset();

}

class Zend_Service_RememberTheMilk_TimezoneList implements IteratorAggregate {
  
  /**
  * @param DOMDocument $doc XML response to a rtm.timezones.getList call
  */
  public function __construct(DOMDocument $doc);
  
  /**
  * @return IteratorIterator
  */
  public function getIterator();
  
  /**
  * @return int
  */
  public function getLength();
  
}

Page Operations

Browse Space

Zend_Service_RememberTheMilk

Labels

Zend Framework: Zend_Service_RememberTheMilk Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria