This page is currently in draft form. At a later date, it will be marked as Ready for Review.

Zend Framework: Zend_Gdata_Contacts Component Proposal

Proposed Component Name	Zend_Gdata_Contacts
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Gdata_Contacts
Proposers	Darien Hager
Zend Liaison	TBD
Revision	1.0 - 7 July 2008: Initial Draft. (wiki revision: 10)

Authenticate to the Google Contacts service ("cp")
Query and list contacts owned by the authenticated user
Retrieve pieces of information (phone, address, etc.) about a contact
Retrieve items based on category ("Work", "Personal", "Other")
Determine the "primary" item in a group (e.g. primary email, primary mailing address)
Set or alter the primary item in a group
Change the category of an item (e.g. change an e-mail from "work" to "personal")
Get/Set notes and extended properties from a contact

The chunks of information that must be handled are:

Contact Name
Contact Notes
Email addresses
IM addresses
Postal addresses
Phone numbers (incl. Fax/Mobile designations)
Organization Name
Title in organization
Extended properties

Features which are NOT part of this proposal at this time:

Photo retrieval/setting
Bulk updates (relies on core Zend_Gdata changes)
Group or Membership data and queries

4. Dependencies on Other Framework Components

Zend_Gdata

5. Theory of Operation

Instantiation and use should follow the same patterns that similar extensions do, such as Zend_Gdata_Calendar and Zend_Gdata_Docs.

6. Milestones / Tasks

Milestone 1: Publish proposal (In ProgresS)
Milestone 2: [DONE] Code working prototype
Milestone 3: Check working prototype in to Incubator (Incomplete pending legal authorization)
Milestone 4: Create Unit tests
Milestone 5: Create Documentation

7. Class Index

Zend_Gdata_Contacts_ListEntry
Zend_Gdata_Contacts_ListFeed
Zend_Gdata_Contacts_Query
Zend_Gdata_Contacts
Zend_Gdata_Contacts_Extension_Categorized (abstract superclass)
Zend_Gdata_Contacts_Extension_Email
Zend_Gdata_Contacts_Extension_Im
Zend_Gdata_Contacts_Extension_Name
Zend_Gdata_Contacts_Extension_Notes
Zend_Gdata_Contacts_Extension_Organization
Zend_Gdata_Contacts_Extension_OrgName
Zend_Gdata_Contacts_Extension_OrgTitle
Zend_Gdata_Contacts_Extension_PhoneNumber
Zend_Gdata_Contacts_Extension_PostalAddress
Zend_Gdata_Contacts_Extension_Primary (interface)

8. Use Cases

UC-01: Log on and retrieve a list of contacts, displaying name, notes, and e-mail addresses

$user = "testuser";
$pass = "testpass";
$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, Zend_Gdata_Contacts::AUTH_SERVICE_NAME);
$service = new Zend_Gdata_Contacts($client);
$feed = $service->getContactListFeed();
$entries = $feed->getEntry();
foreach($entries as $entry){
	echo("Name:\t".$entry->getName()."\n");
	echo("Notes:\t".$entry->getNotes()."\n");
	echo("Emails:\t".join(", ",$entry->getEmails())."\n");	
}

9. Class Skeletons

Most classes are complete and working. The following skeletons are just some interesting function signatures and comments for them.

Zend_Gdata_Contacts

require_once 'Zend/Gdata.php';
require_once 'Zend/Gdata/Contacts/ListFeed.php';
require_once 'Zend/Gdata/Contacts/ListEntry.php';

/**
 * Service class for interacting with the Google Contacts data API
 * @link http://code.google.com/apis/contacts/
 */
class Zend_Gdata_Contacts extends Zend_Gdata
{

    const CONTACTS_FEED_URI = 'http://www.google.com/m8/feeds/contacts/default';
    const AUTH_SERVICE_NAME = 'cp';    

    public static $namespaces = array(
            'gd' => 'http://schemas.google.com/g/2005');

    /**
     * Create Gdata_Contacts object
     *
     * @param Zend_Http_Client $client (optional) The HTTP client to use when
     *          when communicating with the Google servers.
     * @param string $applicationId The identity of the app in the form of Company-AppName-Version
     */
    public function __construct($client = null, $applicationId = 'MyCompany-MyApp-1.0');

    /**
     * Creates and returns a new query object.
     *
     * The returned object will inherit it's initial projection value.
     *
     * @return Zend_Gdata_Contacts_Query
     */
    public function newContactQuery();

    /**
     * Sets the projection for this feed. Valid values for Contacts are "full",
     * "thin", and "property-KEY" where KEY is an extended property name.
     *
     * Projections mainly influence the visibility of extended properties.
     *
     * The default is "full".
     *
     * @param string $value
     * @return Zend_Gdata_Contacts Provides a fluent interface
     */
    public function setProjection($value);


    /**
     * Gets the projection for this feed.
     *
     * @return string projection
     */
    public function getProjection();

    /**
     * Retrieve feed object
     *
     * @return Zend_Gdata_Contacts_ListFeed
     */
    public function getContactListFeed();


}

Zend_Gdata_Contacts_ListEntry

require_once 'Zend/Gdata/Entry.php';
require_once 'Zend/Gdata/Contacts/Extension/Name.php';
require_once 'Zend/Gdata/Contacts/Extension/Notes.php';
require_once 'Zend/Gdata/Contacts/Extension/Email.php';
require_once 'Zend/Gdata/Contacts/Extension/Im.php';
require_once 'Zend/Gdata/Contacts/Extension/PhoneNumber.php';
require_once 'Zend/Gdata/Contacts/Extension/PostalAddress.php';
require_once 'Zend/Gdata/Contacts/Extension/Organization.php';
require_once 'Zend/Gdata/Extension/ExtendedProperty.php';

/**
 * Represents a contact entry.
 *
 */
class Zend_Gdata_Contacts_ListEntry extends Zend_Gdata_Entry
{

    /**
     * Retrieves the name of this contact
     *
     * @return Zend_Gdata_Contacts_Extension_Name 
     */
    public function getName();
    
    /**
     * @param Zend_Gdata_Contacts_Extension_Name $value
     */
    public function setName($value);
    
    /**
     * Retrieves the text of any notes associated with this contact.
     *
     * @return Zend_Gdata_Contacts_Extension_Notes Note text
     */
    public function getNotes();
    /**
     * @param Zend_Gdata_Contacts_Extension_Notes $value
     */
    public function setNotes($value);
    /**
     * Retrieves a list of Zend_Gdata_Contacts_Extension_Email items.
     *
     * @todo return primary first, if any
     * @return array An array of Zend_Gdata_Contacts_Extension_Email objects
     */
    public function getEmails();
    /**
     * @param array $values Array of Zend_Gdata_Contacts_Extension_Email items
     * @return Zend_Gdata_Extension_ListEntry or else FALSE on error
     */
    public function setEmails($values);
    
    /**
     * Retrieves a list of Zend_Gdata_Contacts_Extension_Im items.
     *
     * @todo return primary first, if any
     * @return array An array of Zend_Gdata_Contacts_Extension_Im objects
     */
    public function getIms();
    /**
     * @param array $values Array of Zend_Gdata_Contacts_Extension_Im items
     * @return Zend_Gdata_Extension_ListEntry or else FALSE on error
     */
    public function setIms($values);
    /**
     * Retrieves a list of Zend_Gdata_Contacts_Extension_PhoneNumber items.
     *
     * @todo return primary first, if any
     * @return array An array of Zend_Gdata_Contacts_Extension_PhoneNumber objects
     */
    public function getPhones();
    /**
     * @param array $values Array of Zend_Gdata_Contacts_Extension_PhoneNumber items
     * @return Zend_Gdata_Extension_ListEntry or else FALSE on error
     */
    public function setPhones($values);

    /**
     * Sets the "primary" flag on the given object, and unsets it on all
     * sibling objects.
     *
     * @param Zend_Gdata_Contacts_Extension_Primary $object
     * @return boolean True on success, false on failure.
     */
    public function setPrimary(Zend_Gdata_Contacts_Extension_Primary $object);
    
    /**
     * Retrieves a list of Zend_Gdata_Contacts_Extension_PostalAddress items.
     *
     * @todo return primary first, if any
     * @return array An array of Zend_Gdata_Contacts_Extension_PostalAddress objects
     */
    public function getAddresses();
    
    /**
     * @param array $values Array of Zend_Gdata_Contacts_Extension_PostalAddress items
     */
    public function setAddresses($values);
    
    /**
     * Retrieves a list of Zend_Gdata_Contacts_Extension_Organization items.
     * 
     * @todo return primary first, if any
     * @return array An array of Zend_Gdata_Contacts_Extension_Organization objects
     */
    public function getOrgs();
    
    /**
     * @param array $values Array of Zend_Gdata_Contacts_Extension_Organization items
     * @return Zend_Gdata_Extension_ListEntry or else FALSE on error
     */
    public function setOrgs($values);

    /**
     * Retrieves a list of Zend_Gdata_Extension_ExtendedProperty items.
     *
     * @return array An array of Zend_Gdata_Extension_ExtendedProperty objects
     */
    public function getExtendedProperties();

    /**
     * Will fail if there are duplicate ExtendedProperty keys.
     * @param array $values Array of Zend_Gdata_Extension_ExtendedProperty items
     * @return Zend_Gdata_Contacts_ListEntry or else FALSE on error
     */
    public function setExtendedProperties($values);
    
    /**
     * Returns all detected categories for elements
     *
     * @return array Array of string labels
     */
    public function getCategories();

    /**
     * Returns all categorizable elements of a specific type (e.g. "work", "other", "MyCategory")
     *
     * @param string $name
     * @param string $caseSensitive
     * @return array Array of Zend_Gdata_Extension objects
     */
    public function getByCategory($name,$caseSensitive = true);
}

Zend_Gdata_Contacts_Query

<?php


require_once('Zend/Gdata/Query.php');

/**
 * Assists in constructing queries for Google Document List documents
 *
 * @link http://code.google.com/apis/gdata/spreadsheets/
 */
class Zend_Gdata_Contacts_Query extends Zend_Gdata_Query
{
        
	const ORDER_LASTMODIFIED = "lastmodified";
	    
    /**
     * Sets the ordering for results. Some supported ordering schemes may be
     * found using the self::ORDER_* constants.
     *
     * @param string $type Ordering scheme label
     * @return boolean True if successfully set, false otherwise
     */
    public function setOrdering($type);
    
    /**
     * Retrieves the ordering used when making queries. 
     *
     * @return string
     */
    public function getOrdering();
    
    /**
     * Sets sort order. True for ascending, false for descending.
     *
     * @param boolean $asc
     */
    public function setAscending($asc);
    
    /**
     * Retrieves sort order. True for ascending, false for descending.
     *
     * @return boolean
     */
    public function isAscending();
    
    /**
     * Sets whether "deleted" contacts are returned in results or not.
     *
     * @param boolean $show
     */
    public function setShowingDeleted($show);
    
    /**
     * Retrives whether or not "deleted" contacts will appear in results.
     *
     * @return boolean
     */
    public function isShowingDeleted();

    /**
     * Sets the group ID that a contact must exist within in order to be in the
     * query result. This group ID will typically be an URI.
     * 
     * Any setting other than a positive-length string will disable this 
     * result restriction.
     * 
     * @link http://code.google.com/apis/contacts/reference.html#GroupElements
     * @param string $uri
     */
    public function setGroup($uri);
    
    /**
     * Sets the projection for this query. Valid values for Contacts are "full", 
     * "thin", and "property-KEY" where KEY is an extended property name. 
     * 
     * Projections mainly influence the visibility of extended properties.
     *
     * @param string $value
     */
    public function setProjection($value);


    /**
     * Gets the projection for this query.
     *
     * @return string projection
     */
    public function getProjection();
    

    /**
     * Gets the full query URL for this query.
     *
     * @return string url
     */
    public function getQueryUrl();

}

Zend_Gdata_Contacts_Extension_PhoneNumber

<?php

require_once 'Zend/Gdata/Contacts/Extension/Categorized.php';
require_once 'Zend/Gdata/Contacts/Extension/Primary.php';

/**
 * Represents the gd:phoneNumber element used by the Contacts data API
 */
class Zend_Gdata_Contacts_Extension_PhoneNumber extends Zend_Gdata_Contacts_Extension_Categorized implements Zend_Gdata_Contacts_Extension_Primary
{
   
    /**
     * Extends parent implementation to deal with storying phone number subtypes
     */
    public function setCategory($value);

    /**
     * Returns the subtype label, e.g. "Mobile", "Pager", "Fax"...
     * May be a blank string.
     */
    public function getSubType();
    
    /**
     * Sets the subtype label, e.g. "Mobile", "Pager", "Fax" ...
     * May be a blank string.
     *
     * @param string $label The label to set
     */
    public function setSubType($label);

    /**
     * Gets the (textual) phone number for this element.
     *
     * @return string The phone number, may contain parenthesis, spaces, dashes, etc.
     */
    public function getNumber();
    /**
     * Sets the (textual) phone number for this element.
     *
     * @param string $number The phone number to set
     */
    public function setNumber($number);


    /**
     * Whether or not this object is marked as the 'primary' item of this type for the contact
     *
     * @return boolean True if primary, false otherwise
     */
    public function isPrimary();

    /**
     * Returns the label used to prevent multiple primaries.
     *
     * All objects with the same label may only have one "primary" item between
     * them, e.g. "email" elements.
     *
     * @return string 	A label unique to a set of items where only one item may
     * 					be set as primary
     */
    public function getPrimaryLabel();

    /**
     * Changes the flag for whether this is the primary object among it's peers.
     * Note that this does NOT change the flag on any sibling elements.
     * That task must be managed by caller code.
     *
     * @param boolean $value True to set as primary, false otherwise.
     */
    public function setPrimary($value);


}

Page Operations

Browse Space

Zend_Gdata_Contacts - Darien Hager

Labels

Zend Framework: Zend_Gdata_Contacts Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria