A highly advanced Twitter library in PHP
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
CHANGELOG
LICENSE
README-Japanese.md
README.md
UltimateOAuth.php

README.md

UltimateOAuth

A highly advanced Twitter library in PHP.

日本語

@Version: 5.1.5
@Author : CertaiN
@License: FreeBSD
@GitHub : http://github.com/certainist

[System Requirements]

  • Requires PHP 5.2.0 or later.
  • Not depends on cURL.
  • Not depends on any other files.
  • Supports both UNIX and Windows.

[Supported Classes and Methods]

UltimateOAuth

$uo = new UltimateOAuth( $consumer_key, $consumer_secret, $access_token="", $access_token_secret="" );

(stdClass|Array)      $uo->get                   ( $endpoint,                $params=array()                      );
(stdClass|      Void) $uo->post                  ( $endpoint,                $params=array(), $wait_response=true );
(stdClass|Array|Void) $uo->OAuthRequest          ( $endpoint, $method="GET", $params=array(), $wait_response=true );
(stdClass|      Void) $uo->OAuthRequestMultipart ( $endpoint,                $params=array(), $wait_response=true );

(stdClass) $uo->directGetToken ( $username, $password );

(String) $uo->getAuthorizeURL    ( $force_login=false );
(String) $uo->getAuthenticateURL ( $force_login=false );

UltimateOAuthMulti

$uom = new UltimateOAuthMulti;

(Void)  $uom->enqueue ( &$uo, $method, $arg1, $arg2, $arg3, ... );
(Array) $uom->execute ();

UltimateOAuthRotate

UltimateOAuthRotate supports get, post, OAuthRequest, OAuthRequestMultipart of UltimateOAuth, by using __call().

$uor = new UltimateOAuthRotate;

(mixed)              $uor->__call       ( $name, $arguments );

(Bool)               $uor->register     ( $name, $consumer_key, $consumer_secret );
(Bool|Array)         $uor->login        ( $username, $password, $return_array=false );
(Bool)               $uor->setCurrent   ( $name );
(UltimateOAuth|Bool) $uor->getInstance  ( $name );
(Array)              $uor->getInstances ( );

  1. Multiple Request Settings

Edit constants of UltimateOAuthConfig.

  • For the environment that proc_open() is disabled for security reasons

    • USE_PROC_OPEN: FALSE
    • FULL_URL_TO_THIS_FILE: Not an absolute path, but an absolute URL.
  • Otherwise

    • USE_PROC_OPEN: TRUE (default)
  1. OAuth Authentication

To authenticate or authorize, take the following steps.

prepare.php

<?php

// Load this library
require_once('UltimateOAuth.php');

// Start session
session_start();

// Create a new UltimateOAuth instance and set it into the session
$_SESSION['uo'] = new UltimateOAuth('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');
$uo = $_SESSION['uo'];

// Get request_token
$res = $uo->post('oauth/request_token');
if (isset($res->errors)) {
    die(sprintf('Error[%d]: %s',
        $res->errors[0]->code,
        $res->errors[0]->message
    ));
}

// If you want to AUTHENTICATE,
$url = $uo->getAuthenticateURL();
// If you want to AUTHORIZE,
// $url = $uo->getAuthorizeURL();

// Jump to Twitter
header('Location: '.$url);
exit();

After user has logined, the page will be jumped back to Callback URL with oauth_verifier.
You have to configure this parameter in Twitter Developers.

callback.php

<?php

// Load this library
require_once('UltimateOAuth.php');

// Start session
session_start();

// Check session timeout
if (!isset($_SESSION['uo'])) {
    die('Error[-1]: Session timeout.');
}
$uo = $_SESSION['uo'];

// Check oauth_verifier
if (!isset($_GET['oauth_verifier']) || !is_string($_GET['oauth_verifier'])) {
    die('Error[-1]: No oauth_verifier');
}

// Get access_token
$res = $uo->post('oauth/access_token', array(
    'oauth_verifier' => $_GET['oauth_verifier']
));
if (isset($res->errors)) {
    die(sprintf('Error[%d]: %s',
        $res->errors[0]->code,
        $res->errors[0]->message
    ));
}

// Jump to your main page
header('Location: main.php');
exit();

main.php

<?php

// Load this library
require_once('UltimateOAuth.php');

// Start session
session_start();

// Check session timeout
if (!isset($_SESSION['uo'])) {
    die('Error[-1]: Session timeout.');
}
$uo = $_SESSION['uo'];

// Let's tweet
$uo->post('statuses/update', 'status=Whohoo, I just tweeted!');

Note1:
If you already have access_token and access_token_secret,
you can build up by just doing like this:

<?php

require_once('UltimateOAuth.php');

$uo = new UltimateOAuth($consumer_key, $consumer_secret, $access_token, $access_token_secreet);

Note2:
For saving authenticated UltimateOAuth object as string, use serialize() and unserialize().


2-1. Class Detail - UltimateOAuth

UltimateOAuth::__construct()

<?php
$uo = new UltimateOAuth($consumer_key, $consumer_secret, $access_token, $access_token_secret);

Arguments

  • $consumer_key, $consumer_secret
    Required.

  • $access_token, $access_token
    Not necessary if you authenticate or authorize later.

=========================================

UltimateOAuth::OAuthRequest()

<?php
$uo->OAuthRequest($endpoints, $method, $params, $wait_response);

Arguments

  • $endpoints
    See API Documentation.
    Examples:
    statuses/update, 1.1/statuses/update, https://api.twitter.com/1.1/statuses/update.json

  • $method
    GET or POST. Case-insensitive.

  • $params
    Query String (Not URL encoded) or Associative Array.
    Examples:

    <?php
    $params = 'status=TestTweet';
    $params = array('status' => 'TestTweet');

    For uploading files:

    <?php
    $params = '@image='.$filename;
    $params = array('@image' => $filename);
    $params = array('image' => base64_encode(file_get_contents($filename)));

    Note:
    You can't use this with statuses/update_with_media.
    Use UltimateOAuth::OAuthRequestMultipart() instead.

  • $wait_resposne
    TRUE as default. See below.

Return Value

  • If successfully, return decoded JSON.
    Basically it is returned as stdClass.
    Some endpoints return Array.
    Example: statuses/home_timeline, users/lookup
    Some endpoints get Query String, but it is parsed and returned as stdClass.
    Example: oauth/request_token, oauth/access_token

  • If it failed, return Error Object. It has the following structure:

    • (int) $response->errors[0]->code
      HTTP STATUS CODE. Not an error code.
      All error codes are overwritten with HTTP status codes.
      If a local error occurred, this will be -1.

    • (string) $response->errors[0]->message
      An error message.

  • If $wait_response has been set to FALSE, return NULL.

=========================================

UltimateOAuth::get()
UltimateOAuth::post()

<?php
$uo->get($endpoints, $params);
$uo->post($endpoints, $params, $wait_response);

Wrapper for UltimateOAuth::OAuthRequest().

=========================================

UltimateOAuth::OAuthRequestMultipart()

Mainly used for the endpoint statuses/update_with_media.

<?php
$uo->OAuthRequestMultipart($endpoints, $params, $wait_response);

Arguments

  • $endpoints
    Example: statuses/update_with_media

  • $params
    Examples:

    <?php
    $params = '@media[]='.$filename;
    $params = array('@media[]' => $filename);
    $params = array('media[]' => file_get_contents($filename));
  • $wait_response
    Same as UltimateOAuth::OAuthRequest(). TRUE as default.

Return Value

  • Same as UltimateOAuth::OAuthRequest().

=========================================

UltimateOAuth::directGetToken()

This method enables you to use OAuth like xAuth. I named this para-xAuth authentication.

<?php
$uo->directGetToken($username, $password);

Arguments

  • $username
    screen_name or E-mail Address.

  • $password
    password.

Return Value

  • Same as UltimateOAuth::OAuthRequest() when requesting oauth/access_token.

=========================================

UltimateOAuth::getAuthenticateURL()
UltimateOAuth::getAuthorizeURL()

<?php
$uo->getAuthenticateURL($force_login);
$uo->getAuthorizeURL($force_login);

Arguments

  • $force_login
    Whether force logined user to login again. FALSE as default.

Return Value

  • URL String.

Note: What is the difference between Authenticate and Authorize ?

Authenticate Authorize
New User Jump to Twitter Jump to Twitter
Logined User Jump to Twitter, but if you set your application
Allow this application to be used to Sign in with Twitter,
quickly jump back to your callback URL.
Jump to Twitter

2-2. Class Detail - UltimateOAuthMulti

This class enables you to execute multiple request parallelly.

=========================================

UltimateOAuthMulti::__construct()

<?php
$uom = new UltimateOAuthMulti;

=========================================

UltimateOAuthMulti::enqueue()

Enqueue a new job.

<?php
$uom->enqueue($uo, $method, $arg1, $arg2, ...);

=========================================

Arguments

  • $uo
    UltimateOAuth object. Passed by reference.

  • $method
    Example: post

  • $arg1, $arg2, ...
    Example: 'statuses/update', 'status=TestTweet'

=========================================

UltimateOAuthMulti::execute()

Execute All jobs.
After executing, all queues are dequeued.

<?php
$uom->execute($wait_processes);

Arguments

  • $wait_processes
    Same as $wait_response of UltimateOAuth::OAuthRequest().
    TRUE as default.

Return Value

  • Return an Array, collection of the results.

=========================================

2-3. Class Detail - UltimateOAuthRotate

This class enables you to avoid API limits easily.
Also you can use very useful secret endpoints, like:

  • GET activity/about_me
    Get activities about me.

  • GET activity/by_friends
    Get activities by friends.

  • GET statuses/:id/activity/summary
    Get activities about a specified status.

  • GET conversation/show/:id
    Get statuses related to a specified status.

  • POST friendships/accept
    Accept a specified follower request.

  • POST friendships/deny
    Deny a specified follower request.

  • POST friendships/accept_all
    Accept all follower requests.

=========================================

UltimateOAuthRotate::__construct()

<?php
$uor = new UltimateOAuthRotate;

=========================================

UltimateOAuthRotate::register()

Register your own application.

<?php
$uor->register($name, $consumer_key, $consumer_secret);

Arguments

  • $name
    Any name is okay as long as not duplicate with official applications already registered.
    Just used for identification.
    Example: my_app_01
  • $consumer_key
  • $consumer_secret

Return Value

  • Return result as TRUE or FALSE.

=========================================

UltimateOAuthRotate::login()

Login with all registered applications. This method depends on UltimateOAuthMulti class.

<?php
$uor->login($username, $password, $return_array);

Arguments

  • $username
    screen_name or E-mail Address.

  • $password
    password.

  • $return_array
    FALSE as default.
    See below.

Return Value

  • If $return_array is FALSE, return result as TRUE or FALSE.

  • If $return_array is TRUE, return an Array, collection of the results.

=========================================

UltimateOAuthRotate::setCurrent()

Select an application for POST requesting. GET requests have nothing to do with this.

<?php
$uor->setCurrent($name);

Arguments

  • $name
    Example: my_app_01

Return Value

  • Return result as TRUE or FALSE.

=========================================

UltimateOAuthRotate::getInstance($name)

Get clone of specified UltimateOAuth Instance.

<?php
$uor->getInstance($name);

Arguments

  • $name
    Example: my_app_01

Return Value

  • Return UltimateOAuth instance or FALSE.

=========================================

UltimateOAuthRotate::getInstances()

Get clones of all UltimateOAuth Instance.

<?php
$uor->getInstances($type);

Arguments

  • $type
    0 - Return all instances (Default)
    1 - Return official instances
    2 - Return original instances

Return Value

  • Return an Array, collection of the UltimateOAuth instances.

=========================================

UltimateOAuthRotate::__call()

Call an UltimateOAuth method.

Example:

<?php
$uor->get('statuses/home_timeline');