library tweet-entity-linker

jedkirby/tweet-entity-linker

Convert Twitter API Tweet entities such as URLs, Hashtags and User Mentions into their respective HTML entities.

Tweet Entity Linker

, _(*1)

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., _(*2)

Installation

This package can be installed via Composer:, _(*3)

``` bash $ composer require jedkirby/tweet-entity-linker, <sub>(*4)</sub>

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](https://dev.twitter.com/rest/reference/get/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](https://dev.twitter.com/rest/reference/get/statuses/show/id#example-response)):

``` php
$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:, <sub>(*5)</sub>

``` php $text = $tweet->linkify();, <sub>(*6)</sub>

### 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:

``` php
$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:, <sub>(*7)</sub>

``` php $urls = [ [ 'url' => 'https://t.co/Ed4omjYz', 'display_url' => 'https://jedkirby.com' ] ];, <sub>(*8)</sub>

#### Parameter 3: User Mentions

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

``` php
$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:, <sub>(*9)</sub>

``` php $hashtags = [ [ 'text' => 'Awesome' ] ];, <sub>(*10)</sub>

#### Parameter 5: Cashtags

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

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

Result

When putting all the above parameters together, you'd get the following:, <sub>(*11)</sub>

``` php $tweet = Tweet::make( $text, $urls, $mentions, $hashtags, $cashtags );, <sub>(*12)</sub>

var_dump($tweet->linkify());, <sub>(*13)</sub>

With the response being:

``` none
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:, <sub>(*14)</sub>

bash $ ./vendor/bin/phpunit, <sub>(*15)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*16)</sub>

License

jedkirby/tweet-entity-linker is licensed under the MIT license. See the LICENSE file for more details., <sub>(*17)</sub>