README

Small and easy-to-use library for the X (formerly Twitter) API v2.

Installation

Install via Composer:

composer require dg/twitter-php

Requirements: PHP 8.2 or higher.

Getting API Keys

Go to X Developer Portal
Sign in and create a Developer account (Free tier is sufficient)
Create a new Project and App
Set up permissions (important!):
- App Settings → User authentication settings → Edit
- App permissions: Read and Write
- Type of App: Web App
- Callback URI: https://localhost/callback (placeholder, not used)
- Website URL: any valid URL
Generate keys:
- Keys and tokens → API Key and Secret → Generate
- Keys and tokens → Access Token and Secret → Generate
⚠️ Note: After changing permissions, you must regenerate the Access Token!

Use case description (required by X, min. 250 characters):

I am building a personal tool for publishing my own content to X. The
application will only be used to post text updates and images from my own
account. It will not read, collect, or analyze any data from other users.
There is no automation of likes, retweets, follows, or any other
interactions. This is strictly a single-user tool for my personal use to
streamline my social media posting workflow.

Usage

Create the client using your API credentials:

use DG\X\Client;

$x = new Client($consumerKey, $consumerSecret, $accessToken, $accessTokenSecret);

Note: The Free tier of the X API only allows sending and deleting tweets and reading your own profile (authenticate()). Reading timelines, searching, user info, followers and other read endpoints require the Basic tier or higher.

Sending Tweets

$x->sendTweet('I am fine today.');

With an image:

$x->sendTweet('Check this out!', '/path/to/image.jpg');

With multiple images:

$x->sendTweet('Photos!', ['/path/to/img1.jpg', '/path/to/img2.jpg']);

Timelines

Get your own tweets:

$tweets = $x->getMyTweets();

Get your home timeline (you and people you follow):

$tweets = $x->getTimeline();

Get your mentions:

$tweets = $x->getMentions();

Displaying Tweets

The static method Client::clickable() makes links, mentions and hashtags in tweets clickable:

foreach ($tweets as $tweet) {
	echo Client::clickable($tweet);
}

Searching

$results = $x->search('#php');

Users

$user = $x->getUser('elonmusk');
$user = $x->getUserById('44196397');
$followers = $x->getFollowers('44196397');

Social Actions

$x->follow('44196397');
$x->sendDirectMessage('44196397', 'Hello!');

Authentication

Test if user credentials are valid:

if (!$x->authenticate()) {
	die('Invalid credentials');
}

Custom API Requests

You can call any X API v2 endpoint directly:

$result = $x->request('tweets', 'POST', ['text' => 'Hello from raw API!']);
$result = $x->request('users/me', 'GET', ['user.fields' => 'description,profile_image_url']);

Error Handling

All methods throw DG\X\Exception on error:

try {
	$x->sendTweet('Hello!');
} catch (DG\X\Exception $e) {
	echo 'Error: ', $e->getMessage();
}

Backward Compatibility

The old class names DG\Twitter\Twitter, DG\Twitter\Exception, Twitter and TwitterException are available as aliases for DG\X\Client and DG\X\Exception.

Support Me

Thank you!

Changelog

v5.0 (2/2026)

new namespace DG\X with Client class
uses X API v2 endpoints
uses Guzzle HTTP client (replaces raw CURL)
simplified inline OAuth 1.0a
clean API: sendTweet(), deleteTweet(), getTweet(), getMyTweets(), getTimeline(), getMentions(), search(), getUser(), getUserById(), getFollowers(), follow(), sendDirectMessage()
PHPStan level 8
Nette Tester tests
requires PHP 8.2+

v4.1 (11/2019)

added Delete Method (#68)
token is optional throughout + supply get() method

v4.0 (2/2019)

requires PHP 7.1 and uses its advantages like typehints, strict types etc.
class Twitter is now DG\Twitter\Twitter
class TwitterException is now DG\Twitter\Exception

v3.8 (2/2019)

Twitter::sendDirectMessage() uses new API
Twitter::clickable: added support for $status->full_text (#60)

v3.7 (3/2018)

minimal required PHP version changed to 5.4
Twitter::send() added $options
Twitter::clickable() now works only with statuses and entites
fixed coding style

v3.6 (8/2016)

added loadUserFollowersList() and sendDirectMessage()
Twitter::send() allows to upload multiple images
changed http:// to https://

v3.5 (12/2014)

allows to send message starting with @ and upload file at the same time in PHP >= 5.5

v3.4 (11/2014)

cache expiration can be specified as string
fixed some bugs

v3.3 (3/2014)

Twitter::send($status, $image) can upload image
added Twitter::follow()

v3.2 (1/2014)

Twitter API uses SSL OAuth
Twitter::clickable() supports media
added Twitter::loadUserInfoById() and loadUserFollowers()
fixed Twitter::destroy()

v3.1 (3/2013)

Twitter::load() - added third argument $data
Twitter::clickable() uses entities; pass as parameter status object, not just text
added Twitter::$httpOptions for custom cURL configuration

v3.0 (12/2012)

updated to Twitter API 1.1

v2.0 (8/2012)

added support for OAuth authentication protocol
added Twitter::clickable() which makes links, @usernames and #hashtags clickable
installable via composer require dg/twitter-php

v1.0 (7/2008)

initial release

dg / twitter-php

Maintainers

Details