Lib
9 years ago
Tests
9 years ago
LICENSE
9 years ago
PROVIDERS.md
9 years ago
README.md
9 years ago
composer.json
9 years ago
phpdoc.xml
9 years ago
phpunit.full-urls.xml
9 years ago
phpunit.xml
9 years ago
README.md
364 lines
| 1 | Embera |
| 2 | ====== |
| 3 | [](http://travis-ci.org/mpratt/Embera](http://travis-ci.org/mpratt/Embera](http://travis-ci.org/mpratt/Embera) [](https://scrutinizer-ci.com/g/mpratt/Embera/](https://scrutinizer-ci.com/g/mpratt/Embera/](https://scrutinizer-ci.com/g/mpratt/Embera/) [](https://scrutinizer-ci.com/g/mpratt/Embera/](https://scrutinizer-ci.com/g/mpratt/Embera/](https://scrutinizer-ci.com/g/mpratt/Embera/) [](https://packagist.org/packages/mpratt/embera](https://packagist.org/packages/mpratt/embera](https://packagist.org/packages/mpratt/embera) [](https://packagist.org/packages/mpratt/embera](https://packagist.org/packages/mpratt/embera](https://packagist.org/packages/mpratt/embera) |
| 4 | |
| 5 | Embera is a [](http://oembed.com/Oembed](http://oembed.com/](http://oembed.com/) consumer library written in PHP. Basically what it does is take urls from a text and queries the matching |
| 6 | service for information about the media. |
| 7 | |
| 8 | If you are like me, in most cases all you want is to convert a simple Url to a valid html embed code. Now, the sweet thing about Embera, is that |
| 9 | some providers allow you to skip the part about making the request to a Oembed Provider and still get a valid html embed code! Read the `Offline Support` |
| 10 | section for more information. |
| 11 | |
| 12 | On the other hand, there are some oembed providers that dont return html embedable code - Embera detects this and most of the time, it tries to generate |
| 13 | a valid html code for you to use. |
| 14 | |
| 15 | Check out the `Basic Usage` instructions for more information. |
| 16 | |
| 17 | Supported Sites |
| 18 | =============== |
| 19 | Embera supports **60+** sites. Sites marked with an `*` allow offline html embedding |
| 20 | |
| 21 | - * [](http://www.youtube.com/Youtube](http://www.youtube.com/](http://www.youtube.com/) |
| 22 | - * [](http://vimeo.com/Vimeo](http://vimeo.com/](http://vimeo.com/) |
| 23 | - * [](http://www.dailymotion.com/DailyMotion](http://www.dailymotion.com/](http://www.dailymotion.com/) |
| 24 | - [](http://instagram.comInstagram](http://instagram.com](http://instagram.com) |
| 25 | - [](http://soundcloud.comSoundCloud](http://soundcloud.com](http://soundcloud.com) |
| 26 | - [](https://twitter.comTwitter](https://twitter.com](https://twitter.com) |
| 27 | - * [](http://ted.comTed](http://ted.com](http://ted.com) |
| 28 | - [](http://flickr.comFlickr](http://flickr.com](http://flickr.com) |
| 29 | - [](http://revision3.comRevision3](http://revision3.com](http://revision3.com) |
| 30 | - [](http://www.hulu.comHulu](http://www.hulu.com](http://www.hulu.com) |
| 31 | - * [](http://www.kickstarter.comKickstarter](http://www.kickstarter.com](http://www.kickstarter.com) |
| 32 | - [](http://deviantart.comDeviantart](http://deviantart.com](http://deviantart.com) |
| 33 | - [](https://facebook.comFacebook](https://facebook.com](https://facebook.com) (Public Posts/Videos) |
| 34 | - * [](http://www.scribd.comScribd](http://www.scribd.com](http://www.scribd.com) |
| 35 | |
| 36 | **And many many more!** for the full list checkout the [](https://github.com/mpratt/Embera/blob/master/PROVIDERS.mdPROVIDERS.md](https://github.com/mpratt/Embera/blob/master/PROVIDERS.md](https://github.com/mpratt/Embera/blob/master/PROVIDERS.md) file. |
| 37 | |
| 38 | Requirements |
| 39 | ============ |
| 40 | - PHP >= 5.3 |
| 41 | - Curl or `allow_url_fopen` must be enabled |
| 42 | |
| 43 | Installation |
| 44 | ============ |
| 45 | |
| 46 | ### Install with Composer |
| 47 | If you're using [](https://github.com/composer/composerComposer](https://github.com/composer/composer](https://github.com/composer/composer) to manage |
| 48 | dependencies, you can use this library by creating a composer.json and adding this: |
| 49 | |
| 50 | { |
| 51 | "require": { |
| 52 | "mpratt/embera": "~1.0" |
| 53 | } |
| 54 | } |
| 55 | |
| 56 | Save it and run `composer.phar install` |
| 57 | |
| 58 | ### Standalone Installation (without Composer) |
| 59 | Download the latest release or clone this repository, place the `Lib/Embera` directory on your project. Afterwards, you only need to include |
| 60 | the Autoload.php file. |
| 61 | |
| 62 | ```php |
| 63 | require '/path/to/Embera/Autoload.php'; |
| 64 | $embera = new \Embera\Embera(); |
| 65 | ``` |
| 66 | |
| 67 | Or if you already have PSR-0 complaint autoloader, you just need to register Embera |
| 68 | ```php |
| 69 | $loader->registerNamespace('Embera', 'path/to/Embera'); |
| 70 | ``` |
| 71 | |
| 72 | Basic Usage |
| 73 | =========== |
| 74 | |
| 75 | For autoconverting urls into html embedable code, use the `autoEmbed()` method: |
| 76 | ```php |
| 77 | $text = 'Hi, I just saw this video http://www.dailymotion.com/video/xxwxe1_harlem-shake-de-los-simpsons_fun'; |
| 78 | $embera = new \Embera\Embera(); |
| 79 | echo $embera->autoEmbed($text); |
| 80 | /* Hi, I just saw this video <iframe src="http://www.dailymotion.com/embed/video/xxwxe1" ..... */ |
| 81 | ``` |
| 82 | |
| 83 | The Embera object accepts an array with configuration options, so lets say you want to specify width or height: |
| 84 | ```php |
| 85 | $config = array( |
| 86 | 'params' => array( |
| 87 | 'width' => 300, |
| 88 | 'height' => 500 |
| 89 | ) |
| 90 | ); |
| 91 | |
| 92 | $text = 'Check this video out http://vimeo.com/groups/shortfilms/videos/66185763'; |
| 93 | |
| 94 | $embera = new \Embera\Embera($config); |
| 95 | echo $embera->autoEmbed($text); |
| 96 | |
| 97 | /*Check this video out <iframe src="http://player.vimeo.com/video/66185763" width="300" height="480" ....*/ |
| 98 | ``` |
| 99 | |
| 100 | Do you want to allow embedding only from a few Sites? |
| 101 | ```php |
| 102 | $config = array( |
| 103 | 'allow' => array('Youtube', 'Vimeo') |
| 104 | ); |
| 105 | |
| 106 | $text = 'http://vimeo.com/groups/shortfilms/videos/66185763 |
| 107 | http://www.flickr.com/photos/bees/8597283706/in/photostream |
| 108 | http://youtube.com/watch?v=J---aiyznGQ'; |
| 109 | |
| 110 | $embera = new \Embera\Embera($config); |
| 111 | |
| 112 | echo $embera->autoEmbed($text); |
| 113 | // The flickr url remains the same |
| 114 | ``` |
| 115 | |
| 116 | Or perhaps you want to deny embedding from sites? |
| 117 | ```php |
| 118 | $config = array( |
| 119 | 'deny' => array('Youtube', 'Vimeo') |
| 120 | ); |
| 121 | |
| 122 | $text = 'http://dailymotion.com/video/xp30q9_bmw-serie3-2012-en-mexico_auto |
| 123 | http://vimeo.com/groups/shortfilms/videos/66185763 |
| 124 | http://youtube.com/watch?v=J---aiyznGQ'; |
| 125 | |
| 126 | $embera = new \Embera\Embera($config); |
| 127 | |
| 128 | echo $embera->autoEmbed($text); |
| 129 | // Only the dailymotion link will be autoconverted |
| 130 | ``` |
| 131 | |
| 132 | As an alternative you can embed urls only if they start with the embed:// prefix. |
| 133 | ```php |
| 134 | $config = array( |
| 135 | 'use_embed_prefix' => true |
| 136 | ); |
| 137 | |
| 138 | $text = 'embed://dailymotion.com/video/xp30q9_bmw-serie3-2012-en-mexico_auto |
| 139 | http://youtube.com/watch?v=J---aiyznGQ'; |
| 140 | |
| 141 | $embera = new \Embera\Embera($config); |
| 142 | |
| 143 | echo $embera->autoEmbed($text); |
| 144 | // Only the dailymotion link will be autoconverted |
| 145 | ``` |
| 146 | |
| 147 | Maybe you are interested on seeing the full oembed response from the urls. |
| 148 | Use the `getUrlInfo()` method that returns an array with the complete information about |
| 149 | the media located in the url |
| 150 | ```php |
| 151 | $embera = new \Embera\Embera(); |
| 152 | print_r($embera->getUrlInfo('http://dailymotion.com/video/xp30q9_bmw-serie3-2012-en-mexico_auto')); |
| 153 | ``` |
| 154 | |
| 155 | You can even feed an array full with urls and inspect the oembed response for |
| 156 | each one them. |
| 157 | ```php |
| 158 | $urls = array('http://vimeo.com/groups/shortfilms/videos/66185763', |
| 159 | 'http://vimeo.com/47360546', |
| 160 | 'http://www.flickr.com/photos/bees/8597283706/in/photostream', |
| 161 | 'http://youtube.com/watch?v=J---aiyznGQ'); |
| 162 | |
| 163 | $embera = new \Embera\Embera(); |
| 164 | print_r($embera->getUrlInfo($urls)); |
| 165 | ``` |
| 166 | |
| 167 | Remember that some Oembed Providers append more/different information (and others less) this depends heavily from each provider and |
| 168 | the type of media you are requesting. |
| 169 | |
| 170 | Advanced Usage |
| 171 | ============== |
| 172 | |
| 173 | ### Offline Support |
| 174 | One of the key features of Embera is offline support. This feature allows you to get at least the html embed code for some services, |
| 175 | without having to make a real http request to the oembed provider. What Offline support really means, is that the html embed code is constructed |
| 176 | from the original url given, this also means that most of the other information such as the title or the author's name, is probably going to be missing. |
| 177 | Lets call that a fake response. |
| 178 | |
| 179 | Take a look at the [](https://github.com/mpratt/Embera/blob/master/PROVIDERS.mdPROVIDERS.md](https://github.com/mpratt/Embera/blob/master/PROVIDERS.md](https://github.com/mpratt/Embera/blob/master/PROVIDERS.md) to see which providers allow offline support. |
| 180 | |
| 181 | There is a configuration setting called `oembed` that should be used in order to change the way the library communicates with the oembed endpoint. |
| 182 | By default the value equals null, which means that Embera will first try to get the data from the oembed endpoint and if that fails it tries to return a |
| 183 | fake response. This behaviour is useful when there are problems connecting with the oembed provider! This means that you get at least an html embedable code. |
| 184 | |
| 185 | When the `oembed` setting equals `true` the library gets the data directly from the oembed provider. If something goes wrong with the request, Embera skips |
| 186 | the usage of fake responses. |
| 187 | |
| 188 | On the other hand you can set the `oembed` setting to `false` and by doing that, you will always get fake responses. By doing this you can skip the request |
| 189 | to the oembed provider. This library has offline support for a bunch of providers. |
| 190 | |
| 191 | ```php |
| 192 | $config = array( |
| 193 | 'oembed' => false |
| 194 | ); |
| 195 | |
| 196 | $text = 'http://vimeo.com/groups/shortfilms/videos/66185763 |
| 197 | http://www.flickr.com/photos/bees/8597283706/in/photostream'; |
| 198 | |
| 199 | $embera = new \Embera\Embera($config); |
| 200 | echo $embera->autoEmbed($text); |
| 201 | |
| 202 | /* <iframe src="http://player.vimeo.com/66185763" width="420" height="315" ... |
| 203 | http://www.flickr.com/photos/bees/8597283706/in/photostream */ |
| 204 | |
| 205 | /* Since Embera doesnt have Flickr offline support, the url stays the same. */ |
| 206 | ``` |
| 207 | |
| 208 | |
| 209 | When using the `getUrlInfo()` method, it is possible to see if the information from the provider came |
| 210 | directly from the oembed endpoint or if it was generated by the offline feature. If you see in the response, |
| 211 | the key `embera_using_fake` equal `0`, means that the library got the results from the Oembed provider. |
| 212 | When it equals `1`, the html embed code was generated by the library. |
| 213 | |
| 214 | ### Error Checking |
| 215 | There are 3 methods for error checking `bool hasErrors()`, `array getErrors()` and `string getLastError()` |
| 216 | ```php |
| 217 | $embera = new \Embera\Embera(); |
| 218 | $result = $embera->autoEmbed($text); |
| 219 | |
| 220 | if ($embera->hasErrors()) |
| 221 | echo $embera->getLastError(); |
| 222 | |
| 223 | // Or you can inspect all the errors |
| 224 | print_r($embera->getErrors()); |
| 225 | ``` |
| 226 | |
| 227 | ### Output Formatting |
| 228 | Using the `\Embera\Formatter` object and the decorator pattern you are able to create templates with placeholders and |
| 229 | Embera will fill them with the relevant information from the oembed response. |
| 230 | |
| 231 | A placeholder, in this case, is a word enclosed by `{}`, for example `{title}` which should give |
| 232 | you the title of the media. You can use any word from the oembed response ({provider_name}, {thumbnail_url}, {html}, {type}, etc). |
| 233 | |
| 234 | The `Formatter` object has 2 more methods - `setTemplate()` and `transform()` |
| 235 | ```php |
| 236 | $embera = new \Embera\Embera(); |
| 237 | $embera = new \Embera\Formatter($embera); |
| 238 | |
| 239 | $embera->setTemplate('<div class="myclass">{provider_name}: {title} <p>{html}</p></div>'); |
| 240 | |
| 241 | echo $embera->transform(array('url1', 'url2', 'url3')); |
| 242 | // <div class="myclass">provider for url1: the title of url1 <p>embed code for url 1</p></div> |
| 243 | // <div class="myclass">provider for url2: the title of url2 <p>embed code for url 2</p></div> |
| 244 | // <div class="myclass">provider for url3: the title of url3 <p>embed code for url 3</p></div> |
| 245 | ``` |
| 246 | |
| 247 | You can also give a string with urls and they will be replaced by the given template |
| 248 | ```php |
| 249 | $embera = new \Embera\Embera(); |
| 250 | $embera = new \Embera\Formatter($embera); |
| 251 | |
| 252 | $embera->setTemplate('<div class="oembed">{html}</div>'); |
| 253 | |
| 254 | echo $embera->transform('Hey checkout this video http://url.com/video/id'); |
| 255 | // hey checkout this video <div class="oembed">embed code for url.com/video/id</div> |
| 256 | ``` |
| 257 | |
| 258 | If you like you can use a shorter syntax, just by passing a string or array as a second parameter to the |
| 259 | `setTemplate` method |
| 260 | ```php |
| 261 | $embera = new \Embera\Formatter(new \Embera\Embera()); |
| 262 | echo $embera->setTemplate('<div class="oembed">{html}</div>', array('url1.com', 'url2.com', 'url3.com')); |
| 263 | ``` |
| 264 | |
| 265 | ### Adding Custom Providers |
| 266 | Lets say you have a **private** Oembed Provider and you want to manage it with `Embera`. Well you can do it, first you have to create |
| 267 | a new class that extends the `\Embera\Adapters\Service` class. You can use one of the included providers in the /Embera/Providers |
| 268 | directory to get an idea of what it needs to have. |
| 269 | |
| 270 | After that you need to use the `addProvider()` method. This method requires that you specify the host of your service, |
| 271 | the class you created and __optionally__ you can pass a third parameter, an array with data that should be used on the query string |
| 272 | to your Oembed Provider, for example an API key. |
| 273 | ```php |
| 274 | /** |
| 275 | * A very basic custom Service |
| 276 | */ |
| 277 | class CustomService extends \Embera\Adapters\Service |
| 278 | { |
| 279 | protected $apiUrl = 'http://custom-service.com/oembed.json'; |
| 280 | public function validateUrl(){ return preg_match('~customservice\.com/([0-9]+)~i', $this->url); } |
| 281 | } |
| 282 | |
| 283 | $urls = array( |
| 284 | 'http://customservice.com/9879837498', |
| 285 | 'http://www.customservice.com/98756478', |
| 286 | 'http://customservice.com/9879837498/' |
| 287 | ); |
| 288 | |
| 289 | $embera = new \Embera\Embera(); |
| 290 | $embera->addProvider('customservice.com', 'CustomService', array('api_key' => '********')); |
| 291 | $response = $embera->getUrlInfo($urls); |
| 292 | |
| 293 | print_r($response); |
| 294 | ``` |
| 295 | |
| 296 | However, If the provider is public, the best way to deal with it is to open a bug report right here on github so |
| 297 | I can create a class for the service and everyone benefits from it. |
| 298 | |
| 299 | **Important**: __xml__ responses are **not** supported by `Embera` at the moment! Use JSON instead. |
| 300 | |
| 301 | ### Adding custom query string parameters to a service |
| 302 | Some Oembed providers support custom parameters. For example Twitter allows the `align` parameter, which |
| 303 | applies alignment styles to the html embed code. Most of the providers have documentation available |
| 304 | where you can search for possible parameters. |
| 305 | |
| 306 | Use the config array: |
| 307 | ```php |
| 308 | $config = array( |
| 309 | 'custom_params' => array( |
| 310 | 'Twitter' => array('align' => 'center', 'hide_media' => 1) |
| 311 | ) |
| 312 | ); |
| 313 | |
| 314 | $embera = new \Embera\Embera($config); |
| 315 | ``` |
| 316 | |
| 317 | In this case Im passing the align and hide_media parameters to the twitter service. |
| 318 | As a general rule, you just have to specify the Name of the service as a key and an |
| 319 | associative array with the parameters. |
| 320 | |
| 321 | ### Modifying attributes of fake/offline responses |
| 322 | By default services with offline support have a width of 420px and height of 315px. |
| 323 | You can modify this attributes via the config array: |
| 324 | ```php |
| 325 | $config = array( |
| 326 | 'fake' => array( |
| 327 | 'width' => 800, |
| 328 | 'height' => 300 |
| 329 | ) |
| 330 | ); |
| 331 | |
| 332 | $embera = new \Embera\Embera($config); |
| 333 | ``` |
| 334 | |
| 335 | ### Passing Options to the HttpRequest Class |
| 336 | The \Embera\HttpRequest class is a simple wrapper for `curl` and `file_get_contents` (when the `allow_url_fopen` directive is |
| 337 | enabled). |
| 338 | |
| 339 | You can pass options for each one of them when needed |
| 340 | ```php |
| 341 | $config = array( |
| 342 | 'http' => array( |
| 343 | 'curl' => array( |
| 344 | CURLOPT_CONNECTTIMEOUT => 1000 // Connect timeout for curl |
| 345 | ), |
| 346 | 'fopen' => array( |
| 347 | 'header' => "Content-Type: plain/text", // Send a header with file_get_contents/fopen |
| 348 | ) |
| 349 | ) |
| 350 | ); |
| 351 | |
| 352 | $embera = new \Embera\Embera($config); |
| 353 | ``` |
| 354 | |
| 355 | License |
| 356 | ======= |
| 357 | **MIT** |
| 358 | For the full copyright and license information, please view the LICENSE file. |
| 359 | |
| 360 | Author |
| 361 | ===== |
| 362 | Hi! I'm Michael Pratt and I'm from Colombia! |
| 363 | My [](http://www.michael-pratt.comPersonal Website](http://www.michael-pratt.com](http://www.michael-pratt.com) is in spanish. |
| 364 |