webvariants/sallycms-twitter

support for Twitter's REST API 1.1

dev-default / 1.x-dev 2014-03-11 08:27 UTC

This package is not auto-updated.

Last update: 2020-08-17 10:33:53 UTC


README

a SallyCMS AddOn

build for Twitter's REST API 1.1

1. About

The Twitter Client is an AddOn, build for the SallyCMS, to give developers easy access to the Twitter API. It takes use of two common authentication models: "ApplicationOnly" and "OAuth Signed Request".

While there isn't every single feature of the Twitter API implemented (mostly because not every feature makes sense to use in a content management system), its easy to add them to the API stack.

This Project is licensed under the MIT license.

2. Setup

The Twitter Client takes advantage of Sally's global settings to set up the AddOn.

  1. create an Twitter Application (you probably want to use your clients twitter account for this)
  2. create an Access Token and Access Token Secret on the Twitter Application Profile and make sure you give your application the right permissions (ex. Read & Write)
  3. copy the following informations/credentials in the Twitter Client global settings:
    • Application Name
    • Application Version (if you don't have one, just use "0.1")
    • Consumer Key
    • Consumer Secret
    • Access Token
    • Access Token Secret
    • Caching duration (ex. "120" for a 2 min. data cache)
  4. save the settings and you are ready to go

3. Usage

  1. since Sally is using PHP Synphony like "service containers", start by loading the Sly_Core::getContainer() function, or skip this step if the function is already loaded somewhere in the project.
**example:**

`$container = sly_Core::getContainer();`
  1. next, load any of the twitter-* containers
**notice:**

the *Twitter Client* is using multiple "service containers", beacause of the amount of functions implemented in the AddOn. Each function is bundled by categories, such as *Timeline*, *Tweets* or *Favorites*
**examples:**
	
	:::php
		// single container:
			$twitter = $container['twitter-timeline'];
		// multiple containers:
			$twitter_timeline = $container['twitter-timeline'];
			$twitter_tweets = $container['twitter-tweets'];
			// or any other twitter-* container
  1. now you are able to use the API stack inside the chosen container(s)
**important:**

Most of the implemented API functions use a variaty of parameters, to costumize the result. Please make you use the right value for the right argument/parameter. Here are some ways to do so:

1. read the PHP file where the *API function* is hosted ([example](https://bitbucket.org/till_lange/twitter-engine-for-sallycms/src/76ddc5d9e0583c7b6bc69c7b34e2835659118b34/lib/Twitter/Requests/Timeline.php?at=default))
2. use the provided *inline documentation* (if you use an IDE)
3. check out the parameters on the [Twitter REST API](https://dev.twitter.com/docs/api/1.1) website

'Not so common' parameters/arguments will be sometimes accepted as *Array*, to avoid to many arguments in a function.

Those paramters are listed under 'optional parameters' in the *inline documentation*.

To use them, write the prefered parameter(s) in array form, at the end of the *API function* call (see 'example 3' in the code example below).

The use of 'optional parameters' is only supported in some *API functions*! Make sure you set up the *Array* with `$key => $value` pairs, where the `$key` is the **correct typed** name of the parameter and the `$value` the parameter value.
**examples:**

	:::php
		// example 1:
			$result = $twitter->home_timeline('20');
		// example 2:
			$result = $twitter_timeline->user_timeline('', 'twitterapi', '20');
		// example 3:
			$result = $twitter_tweets->send('Tweet text goes here...', '', array(
				'lat'  => '52.130807',
				'long' => '11.628878'
			));

4. Technical Specifications

  1. support for...
  2. implemented functions
    • uses two different authentication models ("ApplicationOnly" and "OAuth Signed Request"), to raise up the rate limit
    • lots of API features, stacked in 12 "service containers"
    • easy to add new API features
    • build in compiler that validates "common used" parameters
    • takes use of Sally's build in Babel Cache
  3. requires...
    • Sally CMS (0.8 or higher)
    • PHP (5.2.0 or higher)
    • Global Settings (Sally AddOn)
  4. using...
  5. license
Build @ WebVariants Magdeburg, 2013