Skip to content

Commit bc5bba5

Browse files
dgdg
committed
readme: rewrite for X for PHP v5.0
- X branding, API v2 examples, new method names - getting API keys guide - backward compatibility section
1 parent d028769 commit bc5bba5

1 file changed

Lines changed: 154 additions & 69 deletions

File tree

‎readme.md‎

Lines changed: 154 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,222 @@
1-
[Twitter for PHP](https://phpfashion.com/twitter-for-php) [![Buy me a coffee](https://files.nette.org/images/coffee1s.png)](https://nette.org/make-donation?to=twitter-php)
2-
================================
1+
X for PHP
2+
=========
33

44
[![Downloads this Month](https://img.shields.io/packagist/dm/dg/twitter-php.svg)](https://packagist.org/packages/dg/twitter-php)
5+
[![Tests](https://github.com/dg/twitter-php/workflows/Tests/badge.svg?branch=master)](https://github.com/dg/twitter-php/actions)
6+
[![Latest Stable Version](https://poser.pugx.org/dg/twitter-php/v/stable)](https://github.com/dg/twitter-php/releases)
7+
[![License](https://img.shields.io/badge/license-New%20BSD-blue.svg)](https://github.com/dg/twitter-php/blob/master/license.md)
58

6-
Twitter for PHP is a very small and easy-to-use library for sending
7-
messages to Twitter and receiving status updates.
9+
Small and easy-to-use library for the [X](https://x.com) (formerly Twitter) API v2.
810

9-
It requires PHP 5.4 or newer with CURL extension and is licensed under the New BSD License.
10-
You can obtain the latest version from our [GitHub repository](https://github.com/dg/twitter-php)
11-
or install it via Composer:
11+
<!---->
1212

13-
composer require dg/twitter-php
1413

14+
Installation
15+
============
1516

16-
[Support Me](https://github.com/sponsors/dg)
17-
--------------------------------------------
17+
Install via Composer:
1818

19-
Do you like Nette DI? Are you looking forward to the new features?
19+
```shell
20+
composer require dg/twitter-php
21+
```
2022

21-
[![Buy me a coffee](https://files.nette.org/icons/donation-3.svg)](https://github.com/sponsors/dg)
23+
Requirements: PHP 8.2 or higher.
2224

23-
Thank you!
25+
<!---->
26+
27+
28+
Getting API Keys
29+
================
30+
31+
1. Go to [X Developer Portal](https://developer.x.com)
32+
2. Sign in and create a Developer account (Free tier is sufficient)
33+
3. Create a new Project and App
34+
35+
4. **Set up permissions** (important!):
36+
- App Settings → User authentication settings → Edit
37+
- App permissions: **Read and Write**
38+
- Type of App: Web App
39+
- Callback URI: `https://localhost/callback` (placeholder, not used)
40+
- Website URL: any valid URL
41+
42+
5. **Generate keys**:
43+
- Keys and tokens → API Key and Secret → Generate
44+
- Keys and tokens → Access Token and Secret → Generate
45+
46+
⚠️ **Note**: After changing permissions, you must regenerate the Access Token!
47+
48+
6. **Use case description** (required by X, min. 250 characters):
49+
```
50+
I am building a personal tool for publishing my own content to X. The
51+
application will only be used to post text updates and images from my own
52+
account. It will not read, collect, or analyze any data from other users.
53+
There is no automation of likes, retweets, follows, or any other
54+
interactions. This is strictly a single-user tool for my personal use to
55+
streamline my social media posting workflow.
56+
```
57+
58+
<!---->
2459

2560

2661
Usage
27-
-----
28-
Sign in to the https://twitter.com and register an application from the https://apps.twitter.com page. Remember
29-
to never reveal your consumer secrets. Click on My Access Token link from the sidebar and retrieve your own access
30-
token. Now you have consumer key, consumer secret, access token and access token secret.
62+
=====
3163

32-
Create object using application and request/access keys
64+
Create the client using your API credentials:
3365

3466
```php
35-
use DG\Twitter\Twitter;
67+
use DG\X\Client;
3668

37-
$twitter = new Twitter($consumerKey, $consumerSecret, $accessToken, $accessTokenSecret);
69+
$x = new Client($consumerKey, $consumerSecret, $accessToken, $accessTokenSecret);
3870
```
3971

40-
The send() method updates your status. The message must be encoded in UTF-8:
72+
73+
**Note:** The Free tier of the X API only allows sending and deleting tweets and reading your own profile (`authenticate()`).
74+
Reading timelines, searching, user info, followers and other read endpoints require the [Basic tier](https://developer.x.com/en/docs/x-api/getting-started/about-x-api) or higher.
75+
76+
77+
### Sending Tweets
4178

4279
```php
43-
$twitter->send('I am fine today.');
80+
$x->sendTweet('I am fine today.');
4481
```
4582

46-
The load() method returns the 20 most recent status updates
47-
posted by you:
83+
With an image:
4884

4985
```php
50-
$statuses = $twitter->load(Twitter::ME);
86+
$x->sendTweet('Check this out!', '/path/to/image.jpg');
5187
```
5288

53-
or posted by you and your friends:
89+
With multiple images:
5490

5591
```php
56-
$statuses = $twitter->load(Twitter::ME_AND_FRIENDS);
92+
$x->sendTweet('Photos!', ['/path/to/img1.jpg', '/path/to/img2.jpg']);
5793
```
58-
or most recent mentions for you:
94+
95+
96+
### Timelines
97+
98+
Get your own tweets:
5999

60100
```php
61-
$statuses = $twitter->load(Twitter::REPLIES);
101+
$tweets = $x->getMyTweets();
62102
```
63-
Extracting the information from the channel is easy:
103+
104+
Get your home timeline (you and people you follow):
64105

65106
```php
66-
foreach ($statuses as $status) {
67-
echo "message: ", Twitter::clickable($status);
68-
echo "posted at " , $status->created_at;
69-
echo "posted by " , $status->user->name;
70-
}
107+
$tweets = $x->getTimeline();
108+
```
109+
110+
Get your mentions:
111+
112+
```php
113+
$tweets = $x->getMentions();
71114
```
72115

73-
The static method `Twitter::clickable()` makes links, mentions and hash tags in status clickable.
74116

75-
The authenticate() method tests if user credentials are valid:
117+
### Displaying Tweets
118+
119+
The static method `Client::clickable()` makes links, mentions and hashtags in tweets clickable:
76120

77121
```php
78-
if (!$twitter->authenticate()) {
79-
die('Invalid name or password');
122+
foreach ($tweets->data as $tweet) {
123+
echo Client::clickable($tweet);
80124
}
81125
```
82126

83-
The search() method provides searching in twitter statuses:
127+
128+
### Searching
129+
130+
```php
131+
$results = $x->search('#php');
132+
```
133+
134+
135+
### Users
84136

85137
```php
86-
$results = $twitter->search('#nette');
138+
$user = $x->getUser('elonmusk');
139+
$user = $x->getUserById('44196397');
140+
$followers = $x->getFollowers('44196397');
87141
```
88142

89-
The returned result is a again array of statuses.
90143

144+
### Social Actions
145+
146+
```php
147+
$x->follow('44196397');
148+
$x->sendDirectMessage('44196397', 'Hello!');
149+
```
91150

92-
Error handling
93-
--------------
94151

95-
All methods throw a `DG\Twitter\Exception` on error:
152+
### Authentication
153+
154+
Test if user credentials are valid:
96155

97156
```php
98-
try {
99-
$statuses = $twitter->load(Twitter::ME);
100-
} catch (DG\Twitter\Exception $e) {
101-
echo "Error: ", $e->getMessage();
157+
if (!$x->authenticate()) {
158+
die('Invalid credentials');
102159
}
103160
```
104161

105-
Additional features
106-
-------------------
107162

108-
The `authenticate()` method tests if user credentials are valid:
163+
### Custom API Requests
164+
165+
You can call any [X API v2](https://developer.x.com/en/docs/x-api) endpoint directly:
109166

110167
```php
111-
if (!$twitter->authenticate()) {
112-
die('Invalid name or password');
113-
}
168+
$result = $x->request('tweets', 'POST', ['text' => 'Hello from raw API!']);
169+
$result = $x->request('users/me', 'GET', ['user.fields' => 'description,profile_image_url']);
114170
```
115171

116-
Other commands
117-
--------------
118172

119-
You can use all commands defined by [Twitter API 1.1](https://dev.twitter.com/rest/public).
120-
For example [GET statuses/retweets_of_me](https://dev.twitter.com/rest/reference/get/statuses/retweets_of_me)
121-
returns the array of most recent tweets authored by the authenticating user:
173+
### Error Handling
174+
175+
All methods throw `DG\X\Exception` on error:
122176

123177
```php
124-
$statuses = $twitter->request('statuses/retweets_of_me', 'GET', ['count' => 20]);
178+
try {
179+
$x->sendTweet('Hello!');
180+
} catch (DG\X\Exception $e) {
181+
echo 'Error: ', $e->getMessage();
182+
}
125183
```
126184

185+
<!---->
186+
187+
188+
Backward Compatibility
189+
======================
190+
191+
The old class names `DG\Twitter\Twitter`, `DG\Twitter\Exception`, `Twitter` and `TwitterException`
192+
are available as aliases for `DG\X\Client` and `DG\X\Exception`.
193+
194+
<!---->
195+
196+
197+
[Support Me](https://github.com/sponsors/dg)
198+
---------------------------------------------
199+
200+
[![Buy me a coffee](https://files.nette.org/icons/donation-3.svg)](https://github.com/sponsors/dg)
201+
202+
Thank you!
203+
204+
<!---->
205+
206+
127207
Changelog
128208
---------
209+
210+
v5.0 (2/2026)
211+
- new namespace `DG\X` with `Client` class
212+
- uses X API v2 endpoints
213+
- uses Guzzle HTTP client (replaces raw CURL)
214+
- simplified inline OAuth 1.0a
215+
- clean API: `sendTweet()`, `deleteTweet()`, `getTweet()`, `getMyTweets()`, `getTimeline()`, `getMentions()`, `search()`, `getUser()`, `getUserById()`, `getFollowers()`, `follow()`, `sendDirectMessage()`
216+
- PHPStan level 8
217+
- Nette Tester tests
218+
- requires PHP 8.2+
219+
129220
v4.1 (11/2019)
130221
- added Delete Method (#68)
131222
- token is optional throughout + supply get() method
@@ -173,13 +264,7 @@ v3.1 (3/2013)
173264
- added Twitter::$httpOptions for custom cURL configuration
174265

175266
v3.0 (12/2012)
176-
- updated to Twitter API 1.1. Some stuff deprecated by Twitter was removed:
177-
- removed RSS, ATOM and XML support
178-
- removed Twitter::ALL
179-
- Twitter::load() - removed third argument $page
180-
- Twitter::search() requires authentication and returns different structure
181-
- removed shortening URL using http://is.gd
182-
- changed order of Twitter::request() arguments to $resource, $method, $data
267+
- updated to Twitter API 1.1
183268

184269
v2.0 (8/2012)
185270
- added support for OAuth authentication protocol
@@ -191,4 +276,4 @@ v1.0 (7/2008)
191276

192277

193278
-----
194-
(c) David Grudl, 2008, 2016 (https://davidgrudl.com)
279+
(c) David Grudl, 2008, 2026 (https://davidgrudl.com)

0 commit comments

Comments
 (0)