Skip to content

Commit b1e0569

Browse files
hannesvdvrekenhannesvdvreken
authored
Merge pull request #47 from GetStream/fix/readme
Readme clean-up
2 parents f95e6a7 + 4c32bf1 commit b1e0569

1 file changed

Lines changed: 123 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 123 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,193 @@
11
stream-php
22
==========
33

4-
[![Build Status](https://travis-ci.org/GetStream/stream-php.svg?branch=master)](https://travis-ci.org/GetStream/stream-php) [![Coverage Status](https://coveralls.io/repos/github/GetStream/stream-php/badge.svg?branch=master)](https://coveralls.io/github/GetStream/stream-php?branch=master) [![PHP version](https://badge.fury.io/ph/get-stream%2Fstream.svg)](http://badge.fury.io/ph/get-stream%2Fstream)
4+
[![Build Status](https://travis-ci.org/GetStream/stream-php.svg?branch=master)](https://travis-ci.org/GetStream/stream-php)
5+
[![Coverage Status](https://coveralls.io/repos/github/GetStream/stream-php/badge.svg?branch=master)](https://coveralls.io/github/GetStream/stream-php?branch=master)
6+
[![Latest Stable Version](https://poser.pugx.org/get-stream/stream/v/stable)](https://packagist.org/packages/get-stream/stream)
57

68
[stream-php](https://github.com/GetStream/stream-php) is the official PHP client for [Stream](https://getstream.io/), a web service for building scalable newsfeeds and activity streams.
79

8-
Note that there is also a [higher level Laravel - Stream integration](https://github.com/getstream/stream-laravel) which hooks into the Laravel ORM.
10+
Note that there is also a higher level [Laravel](https://github.com/getstream/stream-laravel) integration which hooks into the Eloquent ORM.
911

1012
You can sign up for a Stream account at https://getstream.io/get_started.
1113

1214
### Installation
1315

14-
#### PHP version requirements
16+
#### Composer
1517

16-
This API Client project requires PHP 5.5 at a minimum.
18+
```
19+
composer require get-stream/stream
20+
```
1721

18-
See the [Travis configuration](.travis.yml) for details of how it is built, tested and packaged.
22+
Composer will install our latest version automatically.
1923

20-
#### Install with Composer
24+
#### PHP compatibility
2125

22-
If you're using [Composer](https://getcomposer.org/) to manage
23-
dependencies, you can add Stream with it.
26+
Current releases require PHP `5.5` or higher, and depends on Guzzle version 6.
2427

25-
```javascript
26-
{
27-
"require": {
28-
"get-stream/stream": "$VERSION"
29-
}
30-
}
31-
```
28+
If you need to use the client with PHP 5.4 or earlier versions of Guzzle, you can grab an earlier version of this package:
3229

33-
(replace `$VERSION` with one of the available versions on
34-
[Packagist](https://packagist.org/packages/get-stream/stream))
30+
```
31+
composer require get-stream/stream:"~2.1.0"
32+
```
3533

36-
Composer will take care of the autoloading for you, so if you require
37-
the `vendor/autoload.php`, you're good to go.
34+
See the [Travis configuration](.travis.yml) for details of how it is built and tested against different PHP versions.
3835

39-
### Full documentatation
36+
### Documentatation
4037

41-
Documentation for this PHP client are available at the [Stream website](https://getstream.io/docs/?language=php).
38+
Our full documentation for this package is available at [https://getstream.io/docs/php/](https://getstream.io/docs/php/).
4239

43-
### Usage
40+
#### Quick start
4441

45-
```php
46-
<?php
42+
First, [signup here](https://getstream.io/dashboard/) for a free account and grab your API key and secret.
4743

48-
require_once __DIR__ . '/vendor/autoload.php';
44+
Initiating a Client and a Feed object:
4945

50-
// Instantiate a new client, find your API keys here https://getstream.io/dashboard/
51-
$client = new GetStream\Stream\Client('YOUR_API_KEY', 'API_KEY_SECRET');
52-
53-
// Set API endpoint location
54-
$client->setLocation('us-east');
46+
```php
47+
// Instantiate a new client, find your API keys in the dashboard.
48+
$client = new GetStream\Stream\Client('YOUR_API_KEY', 'YOUR_API_SECRET');
5549

5650
// Instantiate a feed object
57-
$user_feed_1 = $client->feed('user', '1');
51+
$userFeed = $client->feed('user', '1');
5852

59-
// Get 20 activities starting from activity with id $last_id (fast id offset pagination)
60-
$results = $user_feed_1->getActivities(0, 20, $last_id);
53+
```
6154

62-
// Get 10 activities starting from the 5th (slow offset pagination)
63-
$results = $user_feed_1->getActivities(5, 10);
55+
Activities in a feed:
6456

57+
```php
6558
// Create a new activity
6659
$data = [
67-
"actor"=>"1",
68-
"verb"=>"like",
69-
"object"=>"3",
70-
"foreign_id"=>"post:42"
71-
];
72-
$user_feed_1->addActivity($data);
73-
// Create a bit more complex activity
74-
$now = new \DateTime("now", new \DateTimeZone('Pacific/Nauru'));
75-
$data = ['actor' => 1, 'verb' => 'run', 'object' => 1, 'foreign_id' => 'run:1',
76-
'course' => ['name'=> 'Golden Gate park', 'distance'=> 10],
77-
'participants' => ['Thierry', 'Tommaso'],
78-
'started_at' => $now
60+
'actor' => '1',
61+
'verb' => 'like',
62+
'object' => '3',
63+
'foreign_id' => 'like:42',
7964
];
80-
$user_feed_1->addActivity($data);
8165

82-
// Remove an activity by its id
83-
$user_feed_1->removeActivity("e561de8f-00f1-11e4-b400-0cc47a024be0");
66+
$response = $userFeed->addActivity($data);
8467

85-
// Remove activities by their foreign_id
86-
$user_feed_1->removeActivity('post:42', true);
68+
// The response will include Stream's internal ID:
69+
// {"id": "e561...", "actor": "1", ...}
8770

88-
// Let user 1 start following user 42's flat feed
89-
$user_feed_1->followFeed('flat', '42');
71+
// Get the latest activities for this user's personal feed, based on who they are following.
72+
$response = $userFeed->getActivities();
9073

91-
// Let user 1 start following user 42's flat feed but only copy 10 activities to target feed
92-
$user_feed_1->followFeed('flat', '42', 10);
74+
// The response will be the json decoded API response.
75+
// {"duration": 45ms, "next": "/api/v1.0/feed/...", "results": [...]}
9376

94-
// Let user 1 stop following user 42's flat feed
95-
$user_feed_1->unfollowFeed('flat', '42');
77+
// Remove an activity by its ID
78+
$userFeed->removeActivity('e561de8f-00f1-11e4-b400-0cc47a024be0');
9679

97-
// Let user 1 stop following user 42's flat feed but keep the history in its feed
98-
$user_feed_1->unfollowFeed('flat', '42', true);
80+
// To remove activities by their foreign_id, set the "foreign id" flag to true.
81+
$userFeed->removeActivity('like:42', true);
82+
```
9983

100-
// Batch adding activities
101-
$activities = array(
102-
array('actor' => '1', 'verb' => 'tweet', 'object' => '1'),
103-
array('actor' => '2', 'verb' => 'like', 'object' => '3')
104-
);
105-
$user_feed_1->addActivities($activities);
84+
Following/follower relations of a feed:
10685

107-
// Add an activity and push it to other feeds too using the `to` field
108-
$data = [
109-
"actor"=>"1",
110-
"verb"=>"like",
111-
"object"=>"3",
112-
"to"=>["user:44", "user:45"]
113-
];
114-
$user_feed_1->addActivity($data);
86+
```php
87+
// When user 1 starts following user 37's activities
88+
$userFeed->followFeed('user', '37');
11589

116-
// Delete a feed (and its content)
117-
$user_feed_1->delete();
90+
// When user 1 stops following user 37's activities
91+
$userFeed->unfollowFeed('user', '37');
11892

119-
// Generating tokens for client side usage
120-
$token = $user_feed_1->getToken();
93+
// Retrieve followers of a feed
94+
$userFeed->followers();
12195

122-
// Javascript client side feed initialization
123-
// user1 = client.feed('user', '1', "$token");
96+
// Retrieve feeds followed by $userFeed
97+
$userFeed->following();
98+
```
12499

125-
// Generating read-only tokens for client side usage
126-
$readonlyToken = $user_feed_1->getReadonlyToken();
100+
Advanced activity operations:
127101

128-
// Javascript client side feed initialization (readonly)
129-
// user1 = client.feed('user', '1', "$readonlyToken");
102+
```php
103+
// Create a bit more complex activity with custom fields
104+
$data = [
105+
'actor' => 1,
106+
'verb' => 'run',
107+
'object' => 1,
108+
'foreign_id' => 'run:42',
109+
110+
// Custom fields:
111+
'course' => [
112+
'name'=> 'Golden Gate park',
113+
'distance'=> 10,
114+
],
115+
'participants' => ['Thierry', 'Tommaso'],
116+
'started_at' => new DateTime('now', new DateTimeZone('Pacific/Nauru'),
117+
];
130118

131-
// Retrieve first 10 followers of a feed
132-
$user_feed_1->followers(0, 10);
119+
// Add an activity and push it to other feeds too using the `to` field
120+
$data = [
121+
'actor' => '1',
122+
'verb' => 'like',
123+
'object' => '3',
124+
'to' => [
125+
'user:44',
126+
'user:45',
127+
],
128+
];
133129

134-
// Retrieve 2 to 10 followers
135-
$user_feed_1->followers(2, 10);
130+
$userFeed->addActivity($data);
131+
132+
// Batch adding activities
133+
$activities = [
134+
['actor' => '1', 'verb' => 'tweet', 'object' => '1'],
135+
['actor' => '2', 'verb' => 'like', 'object' => '3'],
136+
];
136137

137-
// Retrieve 10 feeds followed by $user_feed_1
138-
$user_feed_1->following(0, 10);
138+
$userFeed->addActivities($activities);
139139

140-
// Retrieve 10 feeds followed by $user_feed_1 starting from the 10th (2nd page)
141-
$user_feed_1->following(10, 20);
140+
// Delete an entire feed and its content
141+
$userFeed->delete();
142+
```
142143

143-
// Check if $user_feed_1 follows specific feeds
144-
$user_feed_1->following(0, 2, ['user:42', 'user:43']);
144+
Advanced batching:
145145

146+
```php
146147
// Batch operations (batch activity add, batch follow)
147148
$batcher = $client->batcher();
148149

149150
// Add one activity to many feeds
150-
$activity = array('actor' => '1', 'verb' => 'tweet', 'object' => '1');
151-
$feeds = ['flat:user1', 'flat:user2'];
151+
$activity = ['actor' => '1', 'verb' => 'tweet', 'object' => '1'];
152+
$feeds = ['user:1', 'user:2'];
153+
152154
$batcher->addToMany($activity, $feeds);
153155

154-
// Create many follow
156+
// Create many follow relations
155157
$follows = [
156-
['source' => 'flat:b1', 'target' => 'user:b1'],
157-
['source' => 'flat:b1', 'target' => 'user:b3']
158+
['source' => 'user:b1', 'target' => 'user:b2'],
159+
['source' => 'user:b1', 'target' => 'user:b3'],
158160
];
161+
159162
$batcher->followMany($follows);
163+
```
164+
165+
Generating tokens for client-side usage:
160166

161-
// Create many follows without copying activities
162-
$batcher->followMany($follows, 0);
167+
```php
168+
// Generating a client side token
169+
$token = $userFeed->getToken();
170+
171+
// Generating a read-only client side token
172+
$readonlyToken = $userFeed->getReadonlyToken();
163173
```
164174

165-
### Contributing
175+
Again, our full documentation with all options and methods, is available at [https://getstream.io/docs/php/](https://getstream.io/docs/php/).
166176

167-
First, make sure you can run the test suite. Install development
168-
dependencies :
177+
### Framework integration
169178

170-
$ composer install
179+
#### Laravel
171180

172-
You may now use phpunit :
181+
There's a higher level integration with [Laravel](https://laravel.com) called [`get-stream/stream-laravel`](https://github.com/getstream/stream-laravel).
182+
The `stream-laravel` integration helps you to hook into the Laravel's Eloquent ORM to sync data to Stream.
173183

174-
$ vendor/bin/phpunit
184+
### Contributing
185+
186+
We love contributions. We love contributions with tests even more! To run the test-suite to ensure everything still works, run phpunit:
187+
188+
```
189+
vendor/bin/phpunit --testsuite "Unit Test Suite"
190+
```
175191

176192
### Copyright and License Information
177193

0 commit comments

Comments
 (0)