mpratt / simple-lifestream
A library that returns lifestream events from a bunch of social sites/services.
Installs: 187
Dependents: 0
Suggesters: 0
Security: 0
Stars: 44
Watchers: 9
Forks: 10
Open Issues: 0
Requires
- php: >=5.3.2
README
A very simple and flexible library for your life-streaming purposes. It supports a bunch of third party providers and makes it easy for you to display all that information in one single place.
The sweet thing about this library is that it only returns an array with all the important data (date, html, etc). This empowers you to play with that information and display it however you like. A couple of formatters are also available and you can use them to ouput data in any way you like, see the examples below for more information.
In order to have a decent performance and avoid making too many requests to other sites the library uses internally a Cache System based on files (file cache). The duration of each cache is 10 minutes by default, however you can modify that behaviour easily.
The name of this library is inspired by that old cheap reality show with Paris Hilton and Nicole Ritchie.
Supported Sites
- DaliyMotion
- Delicious
- Deviantart
- Dribble
- FacebookPages
- Atom/RSS Feeds
- Github
- GimmeBar
- StackExchange/StackOverflow
- Twitter (Important! You have to register an app first)
- Instagram (Important! You must register an app first.)
- Pinboard (Important! You need to have an API Token. You can find yours on the settings page)
- Youtube
For a more detailed information about each provider read the STREAMS.md file.
Remember that the Atom/RSS provider can be very useful, giving you the hability to fetch actions from sites that provide RSS/Atom feeds for user actions, like for example Vimeo, Flickr, LastFM, Wordpress blogs, Blogger blogs and the list goes on.
So in Theory, there are many more sites that can be used to enhance your lifestream.
Requirements
- PHP >= 5.3
- Curl or
allow_url_fopen
must be enabled
Installation
Install with Composer
If you're using Composer to manage your dependencies, you can use this library by creating a composer.json and adding this:
{
"require": {
"mpratt/simple-lifestream": "~4.0"
}
}
Save it and run composer.phar install
Standalone Installation (without Composer)
Download the latest release or clone this repository, place the Lib/SimpleLifestream
directory on your project. Afterwards, you only need to include
the Autoload.php
file.
require '/path/to/SimpleLifestream/Autoload.php'; $lifestream = new \SimpleLifestream\SimpleLifestream();
Or if you already have a PSR-0 complaint autoloader, you just need to register the library
$loader->registerNamespace('SimpleLifestream', 'path/to/SimpleLifestream');
Basic Usage
Create an array with valid stream providers and pass it to the SimpleLifestream
object.
$streams = array( new \SimpleLifestream\Stream('Reddit', 'mpratt'), new \SimpleLifestream\Stream('Github', 'mpratt'), new \SimpleLifestream\Stream('Youtube', 'ERB'), new \SimpleLifestream\Stream('StackOverflow', '430087'), new \SimpleLifestream\Stream('FacebookPages', '27469195051'), new \SimpleLifestream\Stream('Feed', 'http://www.michael-pratt/blog/rss/'), ); $lifestream = new \SimpleLifestream\SimpleLifestream(); $lifestream->loadStreams($streams); $data = $lifestream->getLifestream(); foreach ($data as $d) { echo $d['html']; }
The getLifestream(int 0)
method accepts a number, which can be used to limit the latest information you want to get.
$data = $lifestream->getLifestream(10); echo count($data); // 10
Configuration Directives
The SimpleLifestream
constructor, accepts an array with configuration directives
that you can use to modify some parts of the library.
$config = array( 'date_format' => 'Y-m-d H:i', // Date format returned on by the streams 'link_format' => '<a href="{url}">{text}</a>', // Link template used by the streams 'language' => 'English', // The Output language 'cache_ttl' => (60*10), // Optional: Duration of the cache in seconds 'cache_dir' => '/path/bla/bla', // Optional: A place where the cache should be stored ); $lifestream = new \SimpleLifestream\SimpleLifestream($config);
This library has support for English and Spanish languages. If you want the output to be in spanish, you just need to write:
$config = array( 'language' => 'Spanish', ); $streams = array( new \SimpleLifestream\Stream('Reddit', 'mpratt'), new \SimpleLifestream\Stream('Github', 'mpratt'), ); $lifestream = new \SimpleLifestream\SimpleLifestream($config); $data = $lifestream->loadStreams($streams)->getLifestream(); foreach ($data as $d) { echo $d['html']; }
Stream Configuration
The \SimpleLifestream\Stream
object requires two parameters. The first one is a string containing the name of the Provider.
When an Invalid Provider is given, an InvalidArgumentException
is thrown.
The second argument can be a string with the relevant resource/url/username or an array with important configuration options. The regular way of registring a stream is:
$streams = array( new \SimpleLifestream\Stream('Github', 'mpratt'), new \SimpleLifestream\Stream('Youtube', 'ERB'), );
Or use an associative array with the resource
key:
$streams = array( new \SimpleLifestream\Stream('Github', array('resource' => 'mpratt')), new \SimpleLifestream\Stream('Youtube', array('resource' => 'ERB')), );
The resource
key is used internally and is interpreted as the relevant username/url/userid needed for
the provider.
That being said, some streams require additional information in order to work, lets take a look to the Twitter
provider.
Remember that if you wish to use the Twitter Provider, first you have to register an app.
$streams = array( new \SimpleLifestream\Stream('twitter', array( 'consumer_key' => 'your consumer key', 'consumer_secret' => 'your consumer secret', 'access_token' => 'you access token', 'access_token_secret' => 'your access token secret', 'resource' => 'your twitter username', )) ); $lifestream = new \SimpleLifestream\SimpleLifestream(); $output = $lifestream->loadStreams($streams)->getLifestream(); print_r($output);
You can use this technique on a few providers to modify their behaviour in some ways. Another example could be The StackExchange
Provider.
The provider gives you access to all the sites inside the StackExchange web ring, not just StackOverflow. Let's say for example we want
to get the data from a user in http://programmers.stackexchange.com
.
$streams = array( new \SimpleLifestream\Stream('StackExchange', array( 'site' => 'programmers', 'resource' => '430087', )) ); $lifestream = new \SimpleLifestream\SimpleLifestream(); $output = $lifestream->loadStreams($streams)->getLifestream(); print_r($output);
For More Information about streams and their individual configuration options read the STREAMS.md file.
Advanced Usage
Error Checking
There are 3 methods for error checking bool hasErrors()
, array getErrors()
and string getLastError()
$data = $lifestream->getLifestream(); if ($lifestream->hasErrors()) { echo $lifestream->getLastError(); } if ($lifestream->hasErrors()) { var_dump($lifestream->getErrors()); }
Accessing the Raw Response (Adding your own keys)
As of version 4.7.0, you can access the raw response from a provider and return custom keys for your own usage. You can modify the response on a provider basis.
$streams = array( new \SimpleLifestream\Stream('Reddit', array( 'resource' => 'mpratt', 'callback' => function ($value) { return array( 'modified_title' => str_replace(' ', '-', $value['data']['title']) ); }, )), new \SimpleLifestream\Stream('Github', 'mpratt'), new \SimpleLifestream\Stream('Youtube', 'ERB'), ); $lifestream = new \SimpleLifestream\SimpleLifestream(); $output = $lifestream->loadStreams($streams)->getLifestream(); print_r($output);
Or you can register the callback by using the addCallback()
method of each stream.
$reddit = new \SimpleLifestream\Stream('Reddit', 'mpratt'); $reddit->addCallback(function ($v) { return array( 'modified_title' => str_replace(' ', '', $v['data']['title']) ); }); $streams = array( $reddit, new \SimpleLifestream\Stream('Github', 'mpratt'), new \SimpleLifestream\Stream('Youtube', 'ERB'), ); $lifestream = new \SimpleLifestream\SimpleLifestream(); $output = $lifestream->loadStreams($streams)->getLifestream(); print_r($output);
Ignoring Actions/Types
As you can see, some services detect multiple actions, but in some cases you might not want to have
all that information. You can ignore concrete actions using the ignore()
method.
// Tell the library to Ignore all favorited actions/types $lifestream->ignore('favorited'); $data = $lifestream->getLifestream();
Or you can restrict the action to a particular stream provider
// Tell the library to Ignore all starred actions/types only from the Github Provider $lifestream->ignore('favorited', 'Github'); $data = $lifestream->getLifestream();
Output Formatting
Lets talk about output formatters. There are 2 formatters (HtmlList
and Template
) that can help you
display the data in different ways.
In order to use them, you have to apply the decorator pattern. When doing this, the getLifestream()
method gets
transformed and instead of returning an array with information, it returns a string with the requested data inside
a template.
Let's have a look at the HtmlList
decorator:
<?php $config = array(); $streams = array( new \SimpleLifestream\Stream('Reddit', 'mpratt') ); $lifestream = new \SimpleLifestream\SimpleLifestream($config); $lifestream = new \SimpleLifestream\Formatters\HtmlList($lifestream); $lifestream->loadStreams($streams); echo $lifestream->getLifestream(4); /* This prints something around this lines: <ul class="simplelifestream"> <li class="servicename">Y-m-d H:i - <a href="...">text 1</a></li> <li class="servicename">Y-m-d H:i - <a href="...">text 2</a></li> <li class="servicename">Y-m-d H:i - <a href="...">text 3</a></li> <li class="servicename">Y-m-d H:i - <a href="...">text 4</a></li> </ul> */ ?>
The other decoration is named Template
and is a little more flexible, you can use it define your own templates
and with the help of some placeholders, you can interpolate the data fetched by the library.
<?php $lifestream = new \SimpleLifestream\Formatters\Template(new \SimpleLifestream\SimpleLifestream()); $lifestream->setTemplate('<div class="{service}">{text} {link}</div>'); echo $lifestream->loadStreams($streams)->getLifestream(); /* This prints something round this lines: <div class="servicename">a text <a href="..">a link</a></div> <div class="servicename">another text <a href="..">a link</a></div> <div class="servicename">and more text <a href="..">a link</a></div> */ ?>
If you want to see more examples of how to use this library take a peak inside the Tests
directory and view the files.
Otherwise inspect the source code of the library, I would say that it has "decent" english documentation and it should be easy to follow.
License
MIT
For the full copyright and license information, please view the LICENSE file.