Skip to content
This repository
Browse code

Cleaned up the historics implementation.

Added SSL support.
Updated docs.
Bumped version to 2.0.0.
  • Loading branch information...
commit 5b4e9057383bb1919e207edc5c4c539e7217cf1f 1 parent e105f5f
3ft9 Ltd authored June 17, 2012
56  README.md
Source Rendered
@@ -18,16 +18,33 @@ prints the content to the screen as they come in.
18 18
 
19 19
 ```php
20 20
 <?php
21  
-	require 'lib/datasift.php';
22  
-	$user = new DataSift_User('your username', 'your api_key');
23  
-	$def = $user->createDefinition('interaction.content contains "datasift"');
24  
-	$consumer = $def->getConsumer(
25  
-		DataSift_StreamConsumer::TYPE_HTTP,
26  
-		function($consumer, $data) {
27  
-			echo $data['interaction']['content']."\n";
28  
-		}
29  
-	);
30  
-	$consumer->consume();
  21
+  // Load the library
  22
+  require 'lib/datasift.php';
  23
+  // An object of this type will receive events
  24
+  class EventHandler implements DataSift_IStreamConsumerEventHandler
  25
+  {
  26
+    public function onInteraction($consumer, $interaction, $hash)
  27
+    {
  28
+      echo $data['interaction']['content']."\n";
  29
+    }
  30
+
  31
+    // Ignore the other events for the purposes of this example.
  32
+    public function onConnect($consumer)                      { }
  33
+    public function onDeleted($consumer, $interaction, $hash) { }
  34
+    public function onStatus($consumer, $type, $info)         { }
  35
+    public function onWarning($consumer, $message)            { }
  36
+    public function onError($consumer, $message)              { }
  37
+    public function onDisconnect($consumer)                   { }
  38
+    public function onStopped($consumer, $reason)             { }
  39
+  }
  40
+  // Create the user
  41
+  $user = new DataSift_User('your username', 'your api_key');
  42
+  // Create a definition looking for the word "datasift"
  43
+  $def = $user->createDefinition('interaction.content contains "datasift"');
  44
+  // Get an HTTP stream consumer for that definition
  45
+  $consumer = $def->getConsumer(DataSift_StreamConsumer::TYPE_HTTP, new EventHandler());
  46
+  // Consume it - this will not return unless the stream gets disconnected
  47
+  $consumer->consume();
31 48
 ?>
32 49
 ```
33 50
 
@@ -38,9 +55,13 @@ http://dev.datasift.com/docs/targets/twitter/tweet-output-format
38 55
 Requirements
39 56
 ------------
40 57
 
41  
-* PHP 5 with the cURL extension enabled
  58
+* PHP 5 with the cURL extension enabled and openssl for SSL support
42 59
 * JSON (included in PHP 5.2+, otherwise use http://pecl.php.net/package/json)
43 60
 
  61
+The library will use SSL connections by default. While we recommend using SSL
  62
+you may disable it if required by passing false as the third parameter when
  63
+creating a user, or by calling $user->enableSSL(false) on the user object.
  64
+
44 65
 License
45 66
 -------
46 67
 
@@ -52,6 +73,19 @@ more details.
52 73
 Changelog
53 74
 ---------
54 75
 
  76
+* v.2.0.0 Changed event handling to an object instead of functions. Implemented
  77
+          historic streaming. Added SSL support for streams. (2012-06-18)
  78
+
  79
+  Consumers no longer take functions for event handling. Instead you define a
  80
+  class that implements the DataSift_IStreamConsumerEventHandler interface and
  81
+  pass an instance of that. In addition to switching to an object-based event
  82
+  handler we have also introduced the following new events: onConnect,
  83
+  onDisconnect and onStatus.
  84
+
  85
+  SSL is enabled by default and can be disabled by passing false as the third
  86
+  parameter to the User constructor, or calling enableSSL(false) on the User
  87
+  object.
  88
+
55 89
 * Added the develop branch as required by git flow (2012-05-24)
56 90
 
57 91
 * v.1.3.0 Improved error handling (2012-03-08)
18  examples/consume-stream.php
@@ -63,6 +63,24 @@ public function onDeleted($consumer, $interaction, $hash)
63 63
 	}
64 64
 
65 65
 	/**
  66
+	 * Called when a status message is received.
  67
+	 *
  68
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  69
+	 *                                             event.
  70
+	 * @param string                  $type        The status type.
  71
+	 * @param array                   $info        The data sent with the
  72
+	 *                                             status message.
  73
+	 */
  74
+	public function onStatus($consumer, $type, $info)
  75
+	{
  76
+		switch ($type) {
  77
+			default:
  78
+				echo 'STATUS: '.$type.PHP_EOL;
  79
+				break;
  80
+		}
  81
+	}
  82
+
  83
+	/**
66 84
 	 * Called when a warning occurs or is received down the stream.
67 85
 	 *
68 86
 	 * @param DataSift_StreamConsumer $consumer The consumer object.
14  examples/deletes.php
@@ -55,6 +55,20 @@ public function onDeleted($consumer, $interaction, $hash)
55 55
 	}
56 56
 
57 57
 	/**
  58
+	 * Called when a status message is received.
  59
+	 *
  60
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  61
+	 *                                             event.
  62
+	 * @param string                  $type        The status type.
  63
+	 * @param array                   $info        The data sent with the
  64
+	 *                                             status message.
  65
+	 */
  66
+	public function onStatus($consumer, $type, $info)
  67
+	{
  68
+		// Ignored for this example
  69
+	}
  70
+
  71
+	/**
58 72
 	 * Called when a warning occurs or is received down the stream.
59 73
 	 *
60 74
 	 * @param DataSift_StreamConsumer $consumer The consumer object.
64  examples/football.php
@@ -29,7 +29,9 @@ class EventHandler implements DataSift_IStreamConsumerEventHandler
29 29
 	/**
30 30
 	 * Called when the stream is connected.
31 31
 	 *
32  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
  32
+	 * @param DataSift_StreamConsumer $consumer The consumer sending the event.
  33
+	 *
  34
+	 * @return void
33 35
 	 */
34 36
 	public function onConnect($consumer)
35 37
 	{
@@ -37,10 +39,15 @@ public function onConnect($consumer)
37 39
 	}
38 40
 
39 41
 	/**
40  
-	 * Handle incoming data.
  42
+	 * Called for each interaction consumed.
  43
+	 *
  44
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  45
+	 *                                             event.
  46
+	 * @param array                   $interaction The interaction data.
  47
+	 * @param string                  $hash        The hash of the stream that
  48
+	 *                                             matched this interaction.
41 49
 	 *
42  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
43  
-	 * @param array $interaction The interaction data.
  50
+	 * @return void
44 51
 	 */
45 52
 	public function onInteraction($consumer, $interaction, $hash)
46 53
 	{
@@ -55,10 +62,15 @@ public function onInteraction($consumer, $interaction, $hash)
55 62
 	}
56 63
 
57 64
 	/**
58  
-	 * Handle DELETE requests.
  65
+	 * Called for each deletion notification consumed.
59 66
 	 *
60  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
61  
-	 * @param array $interaction The interaction data.
  67
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  68
+	 *                                             event.
  69
+	 * @param array                   $interaction The interaction data.
  70
+	 * @param string                  $hash        The hash of the stream that
  71
+	 *                                             matched this interaction.
  72
+	 *
  73
+	 * @return void
62 74
 	 */
63 75
 	public function onDeleted($consumer, $interaction, $hash)
64 76
 	{
@@ -68,10 +80,30 @@ public function onDeleted($consumer, $interaction, $hash)
68 80
 	}
69 81
 
70 82
 	/**
  83
+	 * Called when a status message is received.
  84
+	 *
  85
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  86
+	 *                                             event.
  87
+	 * @param string                  $type        The status type.
  88
+	 * @param array                   $info        The data sent with the
  89
+	 *                                             status message.
  90
+	 */
  91
+	public function onStatus($consumer, $type, $info)
  92
+	{
  93
+		switch ($type) {
  94
+			default:
  95
+				echo 'STATUS: '.$type.PHP_EOL;
  96
+				break;
  97
+		}
  98
+	}
  99
+
  100
+	/**
71 101
 	 * Called when a warning occurs or is received down the stream.
72 102
 	 *
73  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
  103
+	 * @param DataSift_StreamConsumer $consumer The consumer sending the event.
74 104
 	 * @param string $message The warning message.
  105
+	 *
  106
+	 * @return void
75 107
 	 */
76 108
 	public function onWarning($consumer, $message)
77 109
 	{
@@ -79,10 +111,12 @@ public function onWarning($consumer, $message)
79 111
 	}
80 112
 
81 113
 	/**
82  
-	 * Called when a error occurs or is received down the stream.
  114
+	 * Called when an error occurs or is received down the stream.
83 115
 	 *
84  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
  116
+	 * @param DataSift_StreamConsumer consumer The consumer sending the event.
85 117
 	 * @param string $message The error message.
  118
+	 *
  119
+	 * @return void
86 120
 	 */
87 121
 	public function onError($consumer, $message)
88 122
 	{
@@ -92,7 +126,9 @@ public function onError($consumer, $message)
92 126
 	/**
93 127
 	 * Called when the stream is disconnected.
94 128
 	 *
95  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
  129
+	 * @param DataSift_StreamConsumer $consumer The consumer sending the event.
  130
+	 *
  131
+	 * @return void
96 132
 	 */
97 133
 	public function onDisconnect($consumer)
98 134
 	{
@@ -100,10 +136,12 @@ public function onDisconnect($consumer)
100 136
 	}
101 137
 
102 138
 	/**
103  
-	 * Called when the consumer has stopped.
  139
+	 * Called when the consumer stops for some reason.
104 140
 	 *
105  
-	 * @param DataSift_StreamConsumer $consumer The consumer object.
  141
+	 * @param DataSift_StreamConsumer consumer The consumer sending the event.
106 142
 	 * @param string $reason The reason the consumer stopped.
  143
+	 *
  144
+	 * @return void
107 145
 	 */
108 146
 	public function onStopped($consumer, $reason)
109 147
 	{
30  examples/historic-dump.php
@@ -88,6 +88,36 @@ public function onDeleted($consumer, $interaction, $hash)
88 88
 	}
89 89
 
90 90
 	/**
  91
+	 * Called when a status message is received.
  92
+	 *
  93
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  94
+	 *                                             event.
  95
+	 * @param string                  $type        The status type.
  96
+	 * @param array                   $info        The data sent with the
  97
+	 *                                             status message.
  98
+	 */
  99
+	public function onStatus($consumer, $type, $info)
  100
+	{
  101
+		switch ($type) {
  102
+			case 'initialised':
  103
+			case 'connected':
  104
+				// Ignored
  105
+				break;
  106
+
  107
+			case 'info':
  108
+				if (isset($info['progress'])) {
  109
+					echo $info['progress'].'% complete'.PHP_EOL;
  110
+					break;
  111
+				}
  112
+				// Deliberate fall-through
  113
+
  114
+			default:
  115
+				echo 'STATUS: '.$type.PHP_EOL;
  116
+				break;
  117
+		}
  118
+	}
  119
+
  120
+	/**
91 121
 	 * Called when a warning occurs or is received down the stream.
92 122
 	 *
93 123
 	 * @param DataSift_StreamConsumer $consumer The consumer object.
18  examples/twitter-track.php
@@ -63,6 +63,24 @@ public function onDeleted($consumer, $interaction, $hash)
63 63
 	}
64 64
 
65 65
 	/**
  66
+	 * Called when a status message is received.
  67
+	 *
  68
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  69
+	 *                                             event.
  70
+	 * @param string                  $type        The status type.
  71
+	 * @param array                   $info        The data sent with the
  72
+	 *                                             status message.
  73
+	 */
  74
+	public function onStatus($consumer, $type, $info)
  75
+	{
  76
+		switch ($type) {
  77
+			default:
  78
+				echo 'STATUS: '.$type.PHP_EOL;
  79
+				break;
  80
+		}
  81
+	}
  82
+
  83
+	/**
66 84
 	 * Called when a warning occurs or is received down the stream.
67 85
 	 *
68 86
 	 * @param DataSift_StreamConsumer $consumer The consumer object.
2  lib/DataSift/ApiClient.php
@@ -41,7 +41,7 @@ static public function call($username, $api_key, $endpoint, $params = array(), $
41 41
 	{
42 42
 		// Curl is required
43 43
 		if (!function_exists('curl_init')) {
44  
-			throw new DataSift_Exception_NotYetImplemented('Curl is required for DataSift_User::callAPI');
  44
+			throw new DataSift_Exception_NotYetImplemented('Curl is required for DataSift_ApiClient');
45 45
 		}
46 46
 
47 47
 		// Build the full endpoint URL
13  lib/DataSift/IStreamConsumerEventHandler.php
@@ -62,6 +62,19 @@ public function onInteraction($consumer, $interaction, $hash);
62 62
 	public function onDeleted($consumer, $interaction, $hash);
63 63
 
64 64
 	/**
  65
+	 * Called for each status message received.
  66
+	 *
  67
+	 * @param DataSift_StreamConsumer $consumer    The consumer sending the
  68
+	 *                                             event.
  69
+	 * @param string                  $type        The status type.
  70
+	 * @param array                   $info        The data sent with the
  71
+	 *                                             status message.
  72
+	 *
  73
+	 * @return void
  74
+	 */
  75
+	public function onStatus($consumer, $type, $info);
  76
+
  77
+	/**
65 78
 	 * Called when a warning occurs or is received down the stream.
66 79
 	 *
67 80
 	 * @param DataSift_StreamConsumer $consumer The consumer sending the event.
13  lib/DataSift/StreamConsumer.php
@@ -216,6 +216,19 @@ protected function onDeleted($interaction, $hash = false)
216 216
 	}
217 217
 
218 218
 	/**
  219
+	 * Called for each status message received from the stream.
  220
+	 *
  221
+	 * @param string $type The status type.
  222
+	 * @param array  $info The data received along with the status message.
  223
+	 *
  224
+	 * @return void
  225
+	 */
  226
+	protected function onStatus($type, $info = array())
  227
+	{
  228
+		$this->_eventHandler->onStatus($this, $type, $info);
  229
+	}
  230
+
  231
+	/**
219 232
 	 * This is called when an error notification is received on a stream
220 233
 	 * connection.
221 234
 	 *
24  lib/DataSift/StreamConsumer/HTTP.php
@@ -56,18 +56,16 @@ class DataSift_StreamConsumer_HTTP extends DataSift_StreamConsumer
56 56
 	 *
57 57
 	 * @param DataSift_User $user          The authenticated user
58 58
 	 * @param mixed         $definition    CSDL string, Definition object, or array of hashes
59  
-	 * @param mixed         $onInteraction A function name or array(class/object, method)
60  
-	 * @param mixed         $onStopped     A function name or array(class/object, method)
61  
-	 * @param mixed         $onDeleted     A function name or array(class/object, method)
  59
+	 * @param mixed         $eventHandler  An object that implements IStreamConsumerEventHandler
62 60
 	 *
63 61
 	 * @throws DataSift_Exception_InvalidData
64 62
 	 * @throws DataSift_Exceotion_CompileFailed
65 63
 	 * @throws DataSift_Exception_APIError
66 64
 	 * @see DataSift_StreamConsumer::__construct
67 65
 	 */
68  
-	public function __construct($user, $definition, $onInteraction = false, $onStopped = false, $onDeleted = false, $onError = false, $onWarning = false)
  66
+	public function __construct($user, $definition, $eventHandler)
69 67
 	{
70  
-		parent::__construct($user, $definition, $onInteraction, $onStopped, $onDeleted, $onError, $onWarning);
  68
+		parent::__construct($user, $definition, $eventHandler);
71 69
 	}
72 70
 
73 71
 	/**
@@ -138,8 +136,6 @@ protected function onStart()
138 136
 						break;
139 137
 					}
140 138
 
141  
-					echo 'RAW: '.trim($line).PHP_EOL;
142  
-
143 139
 					// Decode the JSON
144 140
 					$interaction = json_decode(trim($line), true);
145 141
 
@@ -157,7 +153,9 @@ protected function onStart()
157 153
 									$this->onWarning($interaction['message']);
158 154
 									break;
159 155
 								default:
160  
-									// Ticks
  156
+									$type = $interaction['status'];
  157
+									unset($interaction['status']);
  158
+									$this->onStatus($type, $interaction);
161 159
 									break;
162 160
 							}
163 161
 						} else {
@@ -210,10 +208,11 @@ private function connect()
210 208
 		$this->_state = parent::STATE_STARTING;
211 209
 
212 210
 		// Build the URL and parse it
  211
+		$protocol = 'http'.($this->_user->useSSL() ? 's' : '');
213 212
 		if ($this->_is_multi) {
214  
-			$url = 'http://'.DataSift_User::STREAM_BASE_URL.($this->_is_historic ? 'historics/' : '').'multi';
  213
+			$url = $protocol.'://'.DataSift_User::STREAM_BASE_URL.($this->_is_historic ? 'historics/' : '').'multi';
215 214
 		} else {
216  
-			$url = 'http://'.DataSift_User::STREAM_BASE_URL.($this->_is_historic ? 'historics/' : '').$this->_definition->getHash();
  215
+			$url = $protocol.'://'.DataSift_User::STREAM_BASE_URL.($this->_is_historic ? 'historics/' : '').$this->_definition->getHash();
217 216
 		}
218 217
 		echo 'URL: '.$url.PHP_EOL;
219 218
 		$url = parse_url($url);
@@ -224,9 +223,9 @@ private function connect()
224 223
 		}
225 224
 
226 225
 		// Build the request headers
227  
-		$request   = array();
  226
+		$request = array();
228 227
 		$params = array(
229  
-			'statuses'  => '1',
  228
+			'statuses'  => 'true',
230 229
 		);
231 230
 		if ($this->_is_multi) {
232 231
 			$params['hashes'] = implode(',', $this->_hashes);
@@ -269,7 +268,6 @@ private function connect()
269 268
 				$line = true;
270 269
 				while ($line) {
271 270
 					$line = trim(fgets($this->_conn, $this->_max_line_length));
272  
-					echo 'HEADER: '.trim($line).PHP_EOL;
273 271
 					$response[] = $line;
274 272
 				}
275 273
 			}
35  lib/DataSift/User.php
@@ -28,9 +28,9 @@
28 28
  */
29 29
 class DataSift_User
30 30
 {
31  
-	const USER_AGENT      = 'DataSiftPHP/1.3.0';
32  
-	const API_BASE_URL    = 'api.stagingdatasift.com/';
33  
-	const STREAM_BASE_URL = 'stream.stagingdatasift.com/';
  31
+	const USER_AGENT      = 'DataSiftPHP/2.0.0';
  32
+	const API_BASE_URL    = 'api.datasift.com/';
  33
+	const STREAM_BASE_URL = 'stream.datasift.com/';
34 34
 
35 35
 	/**
36 36
 	 * @var string
@@ -43,6 +43,11 @@ class DataSift_User
43 43
 	protected $_api_key = '';
44 44
 
45 45
 	/**
  46
+	 * @var boolean
  47
+	 */
  48
+	protected $_use_ssl = true;
  49
+
  50
+	/**
46 51
 	 * Stores the X-RateLimit-Limit value from the last API call.
47 52
 	 *
48 53
 	 * @var int
@@ -72,7 +77,7 @@ class DataSift_User
72 77
 	 *
73 78
 	 * @throws DataSift_Exception_InvalidData
74 79
 	 */
75  
-	public function __construct($username, $api_key)
  80
+	public function __construct($username, $api_key, $use_ssl = true)
76 81
 	{
77 82
 		if (strlen(trim($username)) == 0) {
78 83
 			throw new DataSift_Exception_InvalidData('Please supply valid credentials when creating a DataSift_User object.');
@@ -84,6 +89,7 @@ public function __construct($username, $api_key)
84 89
 
85 90
 		$this->_username = $username;
86 91
 		$this->_api_key  = $api_key;
  92
+		$this->_use_ssl  = $use_ssl;
87 93
 	}
88 94
 
89 95
 	/**
@@ -123,6 +129,27 @@ public function getAPIKey()
123 129
 	}
124 130
 
125 131
 	/**
  132
+	 * Set whether stream connections should use SSL.
  133
+	 *
  134
+	 * @param bool $enable_ssl Set to true to enable SSL.
  135
+	 *
  136
+	 * @return void
  137
+	 */
  138
+	public function enableSSL($use_ssl = true)
  139
+	{
  140
+		$this->_use_ssl = $use_ssl;
  141
+	}
  142
+
  143
+	/**
  144
+	 * Returns whether SSL should be used where supported.
  145
+	 * 
  146
+	 * @return bool True if SSL should be used.
  147
+	 */
  148
+	public function useSSL() {
  149
+		return $this->_use_ssl;
  150
+	}
  151
+
  152
+	/**
126 153
 	 * Returns the rate limit returned by the last API call.
127 154
 	 *
128 155
 	 * @return int The rate limit.

0 notes on commit 5b4e905

Please sign in to comment.
Something went wrong with that request. Please try again.