Welcome to the Gnip PHP convenience library!

== VERSION ==
This library complies with API version 2.1

== Overview ==

This library provides a PHP API for accessing Gnip web services.  This library 
supports activities related to publishing and subscribing to data.

== Dependencies == 
Dependencies can be installed via command line or by running the install script.

= Required Dependencies =
  - php5 with SimpleXML (included by default in PHP5, unless disabled)
  - A user account on Gnip https://api-v21.gnip.com/

= Optional Dependencies =
  - PEAR
  - MacPorts

= Test Dependencies =
  - PHPUnit 
  - Phing 

Resource links for the above dependencies can be found here:
  http://www.php.net/manual/en/book.simplexml.php
  http://pear.php.net/
  http://www.phpunit.de/
  http://phing.info
  http://www.macports.org/

== Quick Start ==
If you do not wish to install the optional dependencies, you can get Gnip up 
and running fairly quickly.

Gnip has a test publisher "gnip-sample":
https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/

The following example retrieves notification data from the current bucket for 
gnip-sample. Please note that both the current and 0-1 minute old buckets are not 
static and therefore will contain a variable amount of data, but you'll get 
quick feedback to know if you can connect and access the public notification data.

Also note that your requests must be scoped, "gnip" for publicly accessible publishers 
and "my" for publishers you own. Please see Gnip.php for documentation.

	<?php
	require_once 'src/Services/Gnip.php';
	$gnip = new Services_Gnip("<your account email>", "<your account password>");
	$pub = new Services_Gnip_Publisher("gnip-sample");
	$notifications = $gnip->getPublisherNotifications($pub, "current", "gnip");
	print_r($notifications);
	?>
	
You should see an array of objects printed to your browser.

== Installing ==

= OSX and Ubuntu = 
If you have MacPorts set up on the mac and are running the factory-installed 
apache or Ubuntu, you can run the INSTALL script included. It will install 
all of the dependencies.

Otherwise, assuming you have PHP and PEAR ready to go, you can install the 
optional dependencies as follows:

Make sure PEAR is upgraded to the latest version:
    % sudo pear channel-update pear.php.net

= Install phpunit 3.3.* =

    % sudo pear channel-discover pear.phpunit.de
    % sudo pear install phpunit/PHPUnit-3.3.5
	
= Install phing 2.3.* =

    % sudo pear channel-discover pear.phing.info
    % sudo pear install phing/phing

= Tips =
Make sure the memory_limit is high enough in your php.ini. The PEAR installers 
sometimes need 18M.

= Debugging =
The Gnip PHP library uses the PHP Logger to send messages to the logs. You can 
configure the messages to be sent to the console by setting debugging:

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $gnip->setDebugging(true);

= Unit Tests Tips =
PHPUnit tests are set up for these libraries. There are unit tests and 
integration tests. 

PublisherIntegrationTest.php is for publishers only and you must set up the correct
information in the setup section of the test file.

FilterIntegrationTest.php and RuleIntegrationTest.php can be run by anyone, but 
you must set up the correct information in the setup section of the test file.

You can run the entire test suite at once by running the following command
from the root of this directory:

  % phing

Integration tests can be run by using the command:

  % phpunit test/integration/FilterIntegrationTest.php

Unit tests can be run by using the command:

  % phpunit test/unit/ActivityTest.php



==== Subscriber Actions ====

=== Notification vs. Activity ===

As a subscriber you can retrieve notification data or activity data. The main 
difference between these two types of data buckets are:

*** Notifications contain a reduced meta-data subset of attributes for an activity
*** Activities contain full data, including the raw payload. There are some 
    restrictions on activity data. You can only request unfiltered activities 
    on publishers that you own (have authorization access to). You can create 
    filters on any publisher and request activity data.

=== Example 1: Retrieve notifications from a publisher ===

As a consumer one thing you might be interested in immediately is
grabbing data from a publisher. To do this you must create a connection to Gnip 
using your username and password.  Once the connection is established you can 
get the publisher and request the stream. These examples uses the publisher 
"gnip-sample".

*** Notification data stream request ***

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $pub = new Services_Gnip_Publisher("gnip-sample");
    $notifications = $gnip->getPublisherNotifications($pub, "current", "gnip");
    print_r($notifications);

You can also view the current notifications bucket via web on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/current.xml
	
	
*** Notification data stream request with optional date param ***

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $pub = new Services_Gnip_Publisher("gnip-sample");
    $notifications = $gnip->getPublisherNotifications($pub, time() -120, "gnip");
    print_r($notifications);

You can see the running list of notification buckets on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/notification/
	
=== Example 2: Filter notifications or activities by a set of users ===

You can create a filter to stream activity data for the users you care about. 
Posts from the users that have already occurred will not be included in a 
filter. Therefore any new filter you create will be empty until the users you 
specify perform an action (make a tweet, digg a story, create a bookmark in 
delicious, etc.). 

You can only retrieve activity data (full data) from publishers that you don't own 
by creating a filter.

The test actor for "gnip-sample" is "jvaleski". To test your filter, be sure 
"jvaleski" appears in your rule set.

The following examples illustrate creating filters for both notification and activity 
data. Additionally, the two examples show how to use/not use the post URL parameter.

*** Notification Filter without POST URL ***

Note that the full data (second parameter) of the filter object must be set to 
false. This example does not include a POST Url, meaning you'll have to poll 
Gnip for the results when you need them. The following snippet creates (and 
retrieves) a notification filter called "myNotificationFilter" on the publisher 
gnip-sample.

    $gnip = new Services_Gnip("<your account email>", "<your account password>");

    $rules = array(new Services_Gnip_Rule("actor", "you"),  
                   new Services_Gnip_Rule("actor", "me"), 
                   new Services_Gnip_Rule("actor", "mary"));
    $filter = new Services_Gnip_Filter("myNotificationFilter", 'false', '', $rules);
    // while you have the filter object you can add or remove rules
    $filter->addRules(array(new Services_Gnip_Rule("actor", "jvaleski")));
    $filter->removeRules(array(new Services_Gnip_Rule("actor", "me")));

    $status = $gnip->createFilter("gnip-sample", $filter, "gnip");
    echo $status;
    
The server will return :
<result>Success</result>
	
You can view your filters by running:
    print_r($gnip->getFilter("gnip-sample", "myNotificationFilter", "gnip"));

Your actors list should be (not necessarily in this order): you, mary, jvaleski

You can also see your filters list for each publisher by going to the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters
	
You can view notification buckets on the Gnip site by going to:
    
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myNotificationFilter/notification
	
*** Activity Filter with POST URL ***

Note that the full data (second parameter) of the filter object must be set to 
true to view activity data. This example includes the optional POST Url, 
meaning Gnip will POST via an HTTP HEAD request to this URL. The following 
snippet creates (and gets) a notification filter called "myActivityFilter" on 
the publisher gnip-sample. 

If you want notifications to be sent to a script on your server for processing, 
you must ensure that the postURL parameter you set responds successfully to an 
HTTP HEAD request. (note that this example will throw an error because the POST 
url is invalid).

    $gnip = new Services_Gnip("<your account email>", "<your account password>");

    $rules = array(new Services_Gnip_Rule("actor", "you"),  
                   new Services_Gnip_Rule("actor", "me"), 
                   new Services_Gnip_Rule("actor", "mary"));
    $filter = new Services_Gnip_Filter("myActivityFilter", 'true', 'http://mysite.com/processingscript.php', $rules);
    // while you have the filter object you can add or remove rules
    $filter->addRules(array(new Services_Gnip_Rule("actor", "jvaleski")));
    $filter->removeRules(array(new Services_Gnip_Rule("actor", "me")));

    $status = $gnip->createFilter("gnip-sample", $filter, "gnip");
    echo $status;
	
If you've turned debugging on, you'll see that the postURL in this case is invalid.

You can view your filters by running:
	print_r($gnip->getFilter("gnip-sample", "myActivityFilter", "gnip"));

You can see your filters by going to the Gnip site:
	https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters
Your actors list should be (not necessarily in this order): you, mary, jvaleski

Once data is available, you can see it here:
	https://api-v21.gnip.com/gnip/publishers/gnip-sample/activity
	
=== Example 3: Add rules to an existing filter ===

You can add rules later to an existing filter. The following code snippet adds 
two new rules to the filter we created above, myNotificationFilter:

    $gnip = new Services_Gnip("<your account email>", "<your account password>");

    $filter = $gnip->getFilter("gnip-sample", "myNotificationFilter");
    $filter->addRules(array(new Services_Gnip_Rule("actor", "sam"),
                            new Services_Gnip_Rule("actor", "judy")));

    $gnip->updateFilter("gnip-sample", $filter, "gnip");
	
    print_r($gnip->getFilter("gnip-sample", "myNotificationFilter", "gnip"));

You should see the following actors: mary, you, sam, jvaleski, judy

Adding rules in large batches is the fastest way to augment an existing Filter, and 
for Filters that already contain large rule sets, batch additions must be used to 
change the Filter.  Here's an example of a batch add:

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $rulesArray = array(new Services_Gnip_Rule("actor", "bob"),
                        new Services_Gnip_Rule("actor", "sally"),
                        new Services_Gnip_Rule("actor", "joe"));
    echo $gnip->addBatchRules("gnip-sample", "myNotificationFilter", $rulesArray, "gnip");

If the server receives the message successfully, you should receive an HTTP response code 
of 200 and a message of "Success".  Note, Gnip processes rule addition asynchronously, so 
there may be a delay beteween completion of the request and Gnip's finishing adding rules
to the Filter.  
	
You can test if a rule already exists by calling:

    $rule = new Services_Gnip_Rule("actor", "bob");
    if($gnip->ruleExists("gnip-sample", "myNotificationFilter", $rule, "gnip")){
        echo "yay, the rule exists!";
    }

If you like, you can delete the rule:
    echo $gnip->deleteRule("gnip-sample", "myNotificationFilter", $rule, "gnip");
	
You should see a response message of "Success".

=== Example 4: Delete a filter ===

Filters can be easily deleted. The following code sample deletes the filter 
that was created above:

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $filter = $gnip->getFilter("gnip-sample", "myNotificationFilter", "gnip");
    echo $gnip->deleteFilter("gnip-sample", $filter, "gnip");
	
You should get a response message of "Success".
	
=== Example 5: Retrieve activities from a publisher ===

*** Activity Data Stream Request ***

NOTE: You must create a filter (see Example 2 above) before you can view 
activities for a publisher that you do not own.

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $filter = $gnip->getFilter("gnip-sample", "myActivityFilter", "gnip");
    $activities = $gnip->getFilterActivities("gnip-sample", $filter, "current", "gnip");

You can also view the current activity bucket via web on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myActivityFilter/activity/current.xml

*** Activity Data Stream Request with Date Param ***

NOTE: You must create a filter (see Example 3 below) before you can view 
activities for a publisher that you do not own.

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    $pub = new Services_Gnip_Publisher("gnip-sample");
    $filter = $gnip->getFilter("gnip-sample", "myActivityFilter", "gnip");
    $activities = $gnip->getFilterActivities("gnip-sample", $filter, time() -120, "gnip");

You can see the running list of activity buckets on the Gnip site:
    https://api-v21.gnip.com/gnip/publishers/gnip-sample/filters/myActivityFilter/activity/


==== Publisher Actions ====

In order to utilize the publisher API, you must first create a publisher. The 
publisher name should be descriptive to you. Currently publisher's you create
are private to your account only, and fall under the "my" scope. For now, 
publishers cannot be deleted once they are created, so be mindful when naming
and testing your publishers.

Publishers must have one or more rule types specified so that filters can be 
created based on the rule types. The following rule types are supported by 
Gnip:
	Actor 
	To
	Regarding
	Source
	Tag
	
=== Example 1: Create a publisher
	
    $gnip = new Services_Gnip("<your account email>", "<your account password>");
	
    $name = "myPublisher";
    $supported_rule_types = array(new Services_Gnip_Rule_Type('actor'),
                                  new Services_Gnip_Rule_Type('tag'));
    $publisher = new Services_Gnip_Publisher($name, $supported_rule_types);

    echo $gnip->createPublisher($publisher, "my");
	
You should see a response message of "Success".

=== Example 2: Updating a publisher

The following example takes an existing publisher and updates it with a new set 
of supported rule types.
	
    $gnip = new Services_Gnip("<your account email>", "<your account password>");
	
    $pub = $gnip->getPublisher("myPublisher", "my");

    $rule_types = array(new Services_Gnip_Rule_Type('to'));
    $pub->addRuleTypes($rule_types);
    echo $gnip->updatePublisher($pub, "my");	
	
    You should see a response message of "Success".

=== Example 3: Publishing activities

Here is how you can publish activities to the activity stream. You'll want to review the
Gnip xsd for specifics on what is required/optional. 

https://api-v21.gnip.com/schema/gnip.xsd

You can also review the class files for specific definitions.

    $gnip = new Services_Gnip("<your account email>", "<your account password>");
    
    $place = array(new Services_Gnip_Place("38.2638886 -106.126131", 5.343, 4, "blah", "Chloride Mine", "nearby"));
    $payload = new Services_Gnip_Payload("raw", "title", "body", 
                            array(
                                array("mediaURL" => "http://gnip.com", 
                                    "height" => "300", 
                                    "width" => "300", 
                                    "duration" => "120",
                                    "mimeType" => "video/quicktime", 
                                    "type" => "movie"),
                                array("mediaURL" => "http://gnipcentral.com", 
                                    "height" => "200", 
                                    "width" => "200", 
                                    "duration" => "107",
                                    "mimeType" => "video/quicktime", 
                                    "type" => "movie"))
                                );
	
    $activity = new Services_Gnip_Activity(
                "2008-07-02T11:16:16+00:00", 
                "upload", 
                strval(rand(0, 9999999)), 
                "http://www.gnipcentral.com", 
                array(
                    array('source' => 'sms')),
                array(
                    array('keyword' => 'ping'), 
                    array('keyword'=>'pong')), 
                $place, 
                array(
                    array('actor' => 'bob',
                    'metaURL' => 'http://somewhere.com/users/bob',
                    'uid' => '12234')), 
                array(
                    array('destinationURL' => 'http://somewhere.com', 
                    'metaURL' => 'http://somewhere.com/someplace')), 
                array(
                    array('tag'=>'pongtag'), 
                    array('tag'=>'pingtag')), 
                array(
                    array('to'=>'sally', 
                    'metaURL' => 'http://gnipcentral.com/users/sally')), 
                array(
                    array('regardingURL' => 'http://someurl.com',
                    'metaURL' => 'http://someurlmeta.com')), 
                $payload);
                                           
                                           	
    $mypub = $gnip->getPublisher("myPublisher", "my");
    echo $gnip->publish($mypub, array($activity), "my");
	
You should see a response message of "Success".

=== Contributing ===
 
Contributions to this library are welcome.
 
Source :: git://github.com/gnip/gnip-php.git
Community Site :: http://groups.google.com/group/gnip-community
Mailing List :: gnip-community@googlegroups.com
Twitter Status :: @gnipsupport
 
To get started create a clone of the main repository,
<git://github.com/gnip/gnip-php.git>, and start improving it. Feel
discuss any changes you are making on the mailing list to get feed
back from the other users. Once you are ready to publish your changes
you can send them to the mailing list or, if you are using GitHub,
send a pull request to the owner of the main repository.