The following sections describe a PHP script named mysocial.php, which uses the libraries of the Yahoo! Social SDK for PHP. The mysocial.php script will perform Web authorization, call the Yahoo! Social Directory APIs, and then display your social data. For step-by-step instructions on setting up and running mysocial.php, see the Getting Started tutorial.

Because mysocial.php uses the Yahoo! Social SDK for PHP, it must include the file that contains the SDK:

Before calling the Social Directory APIs, mysocial.php authorizes with OAuth. Behind the scenes, OAuth uses an algorithm that involves passing requests, keys, and secrets between the end user (User), the hosting Web application (Service Provider), and the third-party website or application (Consumer). The Yahoo! Social SDK for PHP takes care of this complexity for you, allowing you to focus on the goals of your application. The PHP SDK authorizes the REST request in the background and returns a YahooSession object defined in the PHP SDK. The application can then use the YahooSession to access Social Directory data.

Note the constants that define the application's Consumer Key (API Key) and Shared Secret (Consumer Secret). These values are required for authorization with OAuth. When you register (create) your application on My Projects, Yahoo! will create values for the Consumer Key and Shared Secret. Then, you will insert those values in the following two lines of code.

The constants CONSUMER_KEY and SHARED_SECRET are passed to the method requireSession in the class YahooSession . The static method call will return the YahooSession object $yahoo_session, which is an authorized session:

Debugging is very important because of the complexity of the OAuth authorization. To enable debugging, make a static call to the method setDebug from the YahooLogger class. Debugging information is logged by the PHP function error_log, which writes errors to the Web server's error log. Starting the debugger will yield more descriptive error messages:

The Profile contains vital information about a user. By accessing the Profile, you can obtain user data such as the person's gender, location, age, and online image.

After getting the YahooSession object, you use the method getSessionedUser to return a YahooUser object. To get the profile of the current user, call the method loadProfile from the YahooUser object $yahoo_user. The $user_profile is assigned an anonymous object that is created from the JSON response. Member variables from the PHP object can then be referenced, which we will see in the next section. Here's the code that gets the user profile:

The Global User Identifier (GUID) is a 26-byte string that identifies a user associated with his or her Social Directory data. A GUID exists for every Yahoo! user, but is never the same as the user's Yahoo! ID. The GUID can be obtained from the user profile or used to capture the user profile. The GUID can also be used to access specific user data by passing it as an argument to methods.

The member variable guid belongs to the YahooUser class, so you can reference the user's GUID from a YahooUser object. You can also retrieve the YahooUser object associated with a user running your application by calling the method getUser from a YahooSession object with the GUID as an argument.

With the YahooUser object $user_profile, the application can access user data by referencing the member variables of the profile object. The code sample below shows how to obtain the URL of the user's image, the status message, and the physical location of a user:

Updates are records of activity for a particular user that can be shared with friends or connections. For example, when a user creates a new message or adds a new application, this information can be passed to the user's connections. The PHP SDK allows you to view and create updates. The code that follows below, adds an update of a user and then gets a list of 20 updates for that user.

First, let's add an update. The method insertUpdate takes three arguments of which the source unique identifier (SUID) is the most important. The SUID identifier connects a user to an action; this connection is called an update. The code below shows how to title the update and link it to a URL.

Next, we will get an update. The method listUpdates takes two integers for the parameters. The two integers represent the start and the number of updates you want to retrieve. In the example below, a list of the first 20 (0-20) updates of the user are returned. The list of updates can then be iterated through to access data for each status update. Update information, such as the user's location, URLs for the icon, and the update itself, can then be accessed through member variables.

User Contacts represent users found in a user's Yahoo! Address Book. These contacts have been chosen by the user, but not reciprocally confirmed as with a Connection. (That is, when a user adds a contact to his address book, the new contact is not asked to confirm, so there is no connection made between the two users.) The PHP SDK has methods that allow you to obtain the entire list of user contacts or a single contact associated with a GUID. The code below shows how to get a list of user contacts and a single user contact. The method getContacts is called from the YahooUser object $yahoo_user and returns a list of user contacts to the variable $user_contacts.

The method getContacts returns a list of the first ten contacts by default, but you can specify the starting point and number of contacts to be returned by calling getContacts with two parameters. If you wanted 12 contacts starting from the third contact, you would call getContacts with the values 2 (offset from start) and 12 (number of contacts): getContacts(2,12). Our example program gets the first 20 contacts:

User connections are different than user contacts in that the relationships have been reciprocally confirmed: Both the user and the connection have mutually agreed to form a relationship. When two users have a connection, they have the ability to share more information. For example, if Jack becomes Jim's friend, then Jack can see Jim's photos or Jim's other friends.

Like the method listUpdates, the parameters of getConnections include a starting connection and the number of connections to retrieve. In this example, we are asking for the first ten connections of the user; these connections are stored in the list $user_connections. The variable $total is passed by reference and is assigned the number of actual, not requested, connections returned.

By iterating through the list of connections, you can obtain specific information about an individual connection.

The last part of mysocial.php accesses the status (also called "presence") of the user. The status, a short string entered by the user, typically indicates the user's current activity or location. For example, a user named Joe might want his friends to know that he's in the Bahamas on vacation. He would then enter his status in the form of plain text: "Hi everyone, I'm in the Bahamas." His connections would be able to see this message when visiting his profile page or in their news feeds. In the examples below, you will update and retrieve the user's status (presence).

To set the status, call the method setPresence. This method takes a string, the user's message, as an argument. Once again, you call this method from the YahooUser object $yahoo_user. The return value will be an HTTP status code indicating the success or failure of the method call:

To get the status, call the method getPresence. This method is called on the YahooUser object $yahoo_user and returns the status message entered by the user (or null if there is no status):

This code example shows how the Canvas view of your application can detect whether the user is signed out from Yahoo!. For users that are signed out from Yahoo!, you should present the application in a way that encourages them to sign in and install your application. (For related best practices, see Helping Users Discover Your Application.)

If the GUID is set, then the user running your application is signed in to Yahoo!. The following code snippet shows how to check the yap_viewer_guid variable:

Another way to check the GUID is to call getSessionedUser method, for example:

To run this application: