README

Tweet Entity Linker is a very simple package and requires minimal setup. It's designed to simply only convert a tweets text, along with it's entities, to a HTML rich string enabling linking of URLs, User Mentions and Hashtags.

Installation

This package can be installed via Composer:

$ composer require jedkirby/tweet-entity-linker

It requires PHP >= 5.6.4.

Usage

The following guide assumes that you've imported the class Jedkirby\TweetEntityLinker\Tweet into your namespace.

The Tweet class requires that you pass it parameters so it's able to create the linkified text. Generally these parameters will be the responses from Twitter API endpoints, like statuses/show/:id, however, it's not required.

The following pseudo code should help explain what's needed when using the response from the API (Please see the example response):

$request = Api::get('https://api.twitter.com/1.1/statuses/show/123456');

$tweet = Tweet::make(
  $request['text'],
  $request['entities']['urls'],
  $request['entities']['user_mentions'],
  $request['entities']['hashtags'],
  $request['entities']['cashtags']
);

Now the Tweet class has been populated with the parameters it needs, you can call the linkify() method to return the text with URLs, User Mentions and Hashtags converted to their HTML entities:

$text = $tweet->linkify();

Manually Creating Parameters

You're able to create the parametes manually, however, they require some specific properties in order for the linkify() method to function correctly, these are as follows:

Parameter 1: Text

This field is always required, and if containing either a URL, User Mention or Hashtag, the corresponding parameter array's should be populated. The following example assumes we have all of those:

$text = 'This notifies @jedkirby, with the hashtag #Awesome, and the URL https://t.co/Ed4omjYz.';

Parameter 2: URLs

The URLs parameter is an array of array's, of which it must contain the url and display_url fields:

$urls = [
  [
    'url'         => 'https://t.co/Ed4omjYz',
    'display_url' => 'https://jedkirby.com'
  ]
];

Parameter 3: User Mentions

The User Mentions parameter is an array of array's, of which it must contain only a screen_name field:

$mentions = [
  [
    'screen_name' => 'jedkirby'
  ]
];

Parameter 4: Hashtags

The Hashtags parameter is an array of array's, of which it must contain only a text field:

$hashtags = [
  [
    'text' => 'Awesome'
  ]
];

Parameter 5: Cashtags

The Hashtags parameter is an array of array's, of which it must contain only a text field:

$cashtags = [
  [
    'text' => 'AAPL'  
  ]
];

Result

When putting all the above parameters together, you'd get the following:

$tweet = Tweet::make(
  $text,
  $urls,
  $mentions,
  $hashtags,
  $cashtags
);

var_dump($tweet->linkify());

With the response being:

string(262) "This notifies @<a href="https://twitter.com/jedkirby" target="_blank">jedkirby</a>, with the hashtag #<a href="https://twitter.com/hashtag/Awesome" target="_blank">Awesome</a>, and the URL <a href="https://t.co/Ed4omjYz" target="_blank">https://jedkirby.com</a>."

Testing

Unit tests can be run inside the package:

$ ./vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

License

jedkirby/tweet-entity-linker is licensed under the MIT license. See the LICENSE file for more details.