PHPackages fg/essence - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. fg/essence Abandoned → [essence/essence](/?search=essence%2Fessence)Library[Image & Media](/categories/media) fg/essence ========== Extracts information about medias on the web, like youtube videos, twitter statuses or blog articles. 3.5.4(5y ago)77053.6k81[17 issues](https://github.com/essence/essence/issues)[7 PRs](https://github.com/essence/essence/pulls)1BSD-2-ClausePHPPHP >=5.5.0 Since Mar 2Pushed 3y ago34 watchersCompare [ Source](https://github.com/essence/essence)[ Packagist](https://packagist.org/packages/fg/essence)[ Docs](http://github.com/essence/essence)[ RSS](/packages/fg-essence/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (10)Dependencies (3)Versions (34)Used By (1) [![Essence](https://camo.githubusercontent.com/7406e0a689ea07b2beb4bd6e4a095660469a1dde381f6cdc0e261810f1b28f7c/687474703a2f2f7777772e66656c69782d67697261756c742e66722f77702d636f6e74656e742f75706c6f6164732f323031352f31302f657373656e636533312e706e67)](https://camo.githubusercontent.com/7406e0a689ea07b2beb4bd6e4a095660469a1dde381f6cdc0e261810f1b28f7c/687474703a2f2f7777772e66656c69782d67697261756c742e66722f77702d636f6e74656e742f75706c6f6164732f323031352f31302f657373656e636533312e706e67) [![Build status](https://camo.githubusercontent.com/58c3652b1d0191249efc680c24aeab08991ff2366e8918695e448522a76da9f5/687474703a2f2f696d672e736869656c64732e696f2f7472617669732f657373656e63652f657373656e63652e7376673f7374796c653d666c61742d737175617265)](http://travis-ci.org/essence/essence)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/f5bf9e4a25048a60bf964e144d48e0e09a1736816229cfbe0979b2e714034d8e/687474703a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f657373656e63652f657373656e63652e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/essence/essence)[![Code Coverage](https://camo.githubusercontent.com/56749765b1e91366dfce3ebcfa4fbd378156351c20c9b5079988af70e6e34942/687474703a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f657373656e63652f657373656e63652e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/essence/essence)[![Total downloads](https://camo.githubusercontent.com/11b3f7fb2f872388d997dcd37ed9256552b6e4a9cfefec7f35f41d250998d52d/687474703a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f657373656e63652f657373656e63652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/essence/essence) Essence is a simple PHP library to extract media information from websites, like youtube videos, twitter statuses or blog articles. If you were already using Essence 2.x.x, you should take a look at [the migration guide](https://github.com/essence/essence/wiki/Migrating-from-2.x.x-to-3.x.x). Installation ------------ [](#installation) ``` composer require essence/essence ``` Example ------- [](#example) Essence is designed to be really easy to use. Using the main class of the library, you can retrieve information in just those few lines: ``` $Essence = new Essence\Essence(); $Media = $Essence->extract('http://www.youtube.com/watch?v=39e3KYAmXK4'); if ($Media) { // That's all, you're good to go ! } ``` Then, just do anything you want with the data: ``` By ``` What you get ------------ [](#what-you-get) Using Essence, you will mainly interact with Media objects. Media is a simple container for all the information that are fetched from an URL. Here are the default properties it provides: - type - version - url - title - description - authorName - authorUrl - providerName - providerUrl - cacheAge - thumbnailUrl - thumbnailWidth - thumbnailHeight - html - width - height These properties were gathered from the OEmbed and OpenGraph specifications, and merged together in a united interface. Based on such standards, these properties should be a solid starting point. However, "non-standard" properties can and will also be setted. Here is how you can manipulate the Media properties: ``` // through dedicated methods if (!$Media->has('foo')) { $Media->set('foo', 'bar'); } $value = $Media->get('foo'); // or directly like a class attribute $Media->customValue = 12; ``` Note that Essence will always try to fill the `html` property when it is not available. Advanced usage -------------- [](#advanced-usage) The Essence class provides some useful utility functions to ensure you will get some information. ### Extracting URLs [](#extracting-urls) The `crawl()` and `crawlUrl()` methods let you crawl extractable URLs from a web page, either directly from its source, or from its URL (in which case Essence will take care of fetching the source). For example, here is how you could get the URL of all videos in a blog post: ``` $urls = $Essence->crawlUrl('http://www.blog.com/article'); ``` ``` array(2) { [0] => 'http://www.youtube.com/watch?v=123456', [1] => 'http://www.dailymotion.com/video/a1b2c_lolcat-fun' } ``` You can then get information from all the extracted URLs: ``` $medias = $Essence->extractAll($urls); ``` ``` array(2) { ['http://www.youtube.com/watch?v=123456'] => object(Media) {} ['http://www.dailymotion.com/video/a1b2c_lolcat-fun'] => object(Media) {} } ``` ### Replacing URLs in text [](#replacing-urls-in-text) Essence can replace any extractable URL in a text by information about it. By default, any URL will be replaced by the `html` property of the found Media. ``` echo $Essence->replace('Look at this: http://www.youtube.com/watch?v=123456'); ``` ``` Look at this: ``` But you can do more by passing a callback to control which information will replace the URL: ``` echo $Essence->replace($text, function($Media) { return Video title ``` This makes it easy to build rich templates or even to integrate a templating engine: ``` echo $Essence->replace($text, function($Media) use ($TwigTemplate) { return $TwigTemplate->render($Media->properties()); }); ``` ### Configuring providers [](#configuring-providers) It is possible to pass some options to the providers. For example, OEmbed providers accepts the `maxwidth` and `maxheight` parameters, as specified in the OEmbed spec. ``` $options = [ 'maxwidth' => 800, 'maxheight' => 600 ]; $Media = $Essence->extract($url, $options); $medias = $Essence->extractAll($urls, $options); $text = $Essence->replace($text, null, $options); ``` Other providers will just ignore the options they don't handle. Configuration ------------- [](#configuration) Essence currently supports 68 specialized providers: ``` 23hq Deviantart Kickstarter Sketchfab Animoto Dipity Meetup SlideShare Aol Dotsub Mixcloud SoundCloud App.net Edocr Mobypicture SpeakerDeck Bambuser Flickr Nfb Spotify Bandcamp FunnyOrDie Official.fm Ted Blip.tv Gist Polldaddy Twitter Cacoo Gmep PollEverywhere Ustream CanalPlus HowCast Prezi Vhx Chirb.it Huffduffer Qik Viddler CircuitLab Hulu Rdio Videojug Clikthrough Ifixit Revision3 Vimeo CollegeHumor Ifttt Roomshare Vine Coub Imgur Sapo Wistia CrowdRanking Instagram Screenr WordPress DailyMile Jest Scribd Yfrog Dailymotion Justin.tv Shoudio Youtube ``` Plus the `OEmbed` and `OpenGraph` providers, which can be used to extract any URL. You can configure these providers on instanciation: ``` $Essence = new Essence\Essence([ // the SoundCloud provider is an OEmbed provider with a specific endpoint 'SoundCloud' => Essence\Di\Container::unique(function($C) { return $C->get('OEmbedProvider')->setEndpoint( 'http://soundcloud.com/oembed?format=json&url=:url' ); }), 'filters' => [ // the SoundCloud provider will be used for URLs that matches this pattern 'SoundCloud' => '~soundcloud\.com/[a-zA-Z0-9-_]+/[a-zA-Z0-9-]+~i' ] ]); ``` You can also disable the default ones: ``` $Essence = new Essence\Essence([ 'filters' => [ 'SoundCloud' => false ] ]); ``` You will find the default configuration in the standard DI container of Essence (see the following part). Customization ------------- [](#customization) Almost everything in Essence can be configured through dependency injection. Under the hoods, the constructor uses a dependency injection container to return a fully configured instance of Essence. To customize the Essence behavior, the easiest way is to configure injection settings when building Essence: ``` $Essence = new Essence\Essence([ // the container will return a unique instance of CustomHttpClient // each time an HTTP client is needed 'Http' => Essence\Di\Container::unique(function() { return new CustomHttpClient(); }) ]); ``` The default injection settings are defined in the [Standard](https://github.com/essence/essence/blob/master/lib/Essence/Di/Container/Standard.php) container class. Try it out ---------- [](#try-it-out) Once you've installed essence, you should try to run `./cli/essence.php` in a terminal. This script allows you to test Essence quickly: ``` # will fetch and print information about the video ./cli/essence.php extract http://www.youtube.com/watch?v=4S_NHY9c8uM # will fetch and print all extractable URLs found at the given HTML page ./cli/essence.php crawl http://www.youtube.com/watch?v=4S_NHY9c8uM ``` Third-party libraries --------------------- [](#third-party-libraries) If you're interested in embedding videos, you should take a look at the [Multiplayer](https://github.com/felixgirault/multiplayer) lib. It allows you to build customizable embed codes painlessly: ``` $Multiplayer = new Multiplayer\Multiplayer(); if ($Media->type === 'video') { echo $Multiplayer->html($Media->url, [ 'autoPlay' => true, 'highlightColor' => 'BADA55' ]); } ``` ### Health Score 44 — FairBetter than 92% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity46 Moderate usage in the ecosystem Community33 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 94.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~93 days Recently: every ~303 days Total 32 Last Release 1940d ago Major Versions 1.4.1 → 2.0.02013-08-03 2.5.2 → 3.0.02015-08-09 2.6.1 → 3.3.02016-09-20 PHP version history (4 changes)1.0.0PHP >=5.3.0 2.0.0PHP >=5.4.0 3.0.0PHP >=5.6.0 3.1.0PHP >=5.5.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/26f691693475a607d34041944521103f6bfb1ca8f6e92606168354f84e1356ac?d=identicon)[fg](/maintainers/fg) --- Top Contributors [![felixgirault](https://avatars.githubusercontent.com/u/1544510?v=4)](https://github.com/felixgirault "felixgirault (664 commits)")[![laughingwithu](https://avatars.githubusercontent.com/u/1298811?v=4)](https://github.com/laughingwithu "laughingwithu (17 commits)")[![zyuhel](https://avatars.githubusercontent.com/u/4603624?v=4)](https://github.com/zyuhel "zyuhel (4 commits)")[![maartendekeizer](https://avatars.githubusercontent.com/u/1061334?v=4)](https://github.com/maartendekeizer "maartendekeizer (2 commits)")[![Gargron](https://avatars.githubusercontent.com/u/184731?v=4)](https://github.com/Gargron "Gargron (2 commits)")[![manuhabitela](https://avatars.githubusercontent.com/u/221253?v=4)](https://github.com/manuhabitela "manuhabitela (2 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (2 commits)")[![hhirsch](https://avatars.githubusercontent.com/u/2451426?v=4)](https://github.com/hhirsch "hhirsch (1 commits)")[![gargamol](https://avatars.githubusercontent.com/u/7671384?v=4)](https://github.com/gargamol "gargamol (1 commits)")[![bes](https://avatars.githubusercontent.com/u/85731?v=4)](https://github.com/bes "bes (1 commits)")[![TheLuckyOne](https://avatars.githubusercontent.com/u/2169244?v=4)](https://github.com/TheLuckyOne "TheLuckyOne (1 commits)")[![nightmora](https://avatars.githubusercontent.com/u/7690485?v=4)](https://github.com/nightmora "nightmora (1 commits)")[![norikt](https://avatars.githubusercontent.com/u/933867?v=4)](https://github.com/norikt "norikt (1 commits)")[![phordijk](https://avatars.githubusercontent.com/u/4834249?v=4)](https://github.com/phordijk "phordijk (1 commits)")[![fastnloud](https://avatars.githubusercontent.com/u/4117844?v=4)](https://github.com/fastnloud "fastnloud (1 commits)")[![shevabam](https://avatars.githubusercontent.com/u/1798289?v=4)](https://github.com/shevabam "shevabam (1 commits)")[![Somethingideally](https://avatars.githubusercontent.com/u/10738476?v=4)](https://github.com/Somethingideally "Somethingideally (1 commits)")[![h4cc](https://avatars.githubusercontent.com/u/2981491?v=4)](https://github.com/h4cc "h4cc (1 commits)")[![herewithme](https://avatars.githubusercontent.com/u/898608?v=4)](https://github.com/herewithme "herewithme (1 commits)") --- Tags embedoembedopengraphphptwitter-cardsmediaembedopengraphoembed ### Embed Badge ![Health badge](/badges/fg-essence/health.svg) ``` [![Health](https://phpackages.com/badges/fg-essence/health.svg)](https://phpackages.com/packages/fg-essence) ``` ### Alternatives [essence/essence Extracts information about medias on the web, like youtube videos, twitter statuses or blog articles. 770562.9k3](/packages/essence-essence)[embed/embed PHP library to retrieve page info using oembed, opengraph, etc 2.1k11.0M97](/packages/embed-embed)[s9e/text-formatter Multi-purpose text formatting and markup library. Plugins offer support for BBCodes, Markdown, emoticons, HTML, embedding third-party media (YouTube, etc...), enhanced typography and more. 2413.1M29](/packages/s9e-text-formatter)[dereuromark/media-embed A PHP library to deal with all those media services around, parsing their URLs and embedding their audio/video content in websites. 182530.3k11](/packages/dereuromark-media-embed)[cohensive/embed Media Embed (for Laravel or as a standalone). 120370.4k](/packages/cohensive-embed)[cohensive/oembed Media embed generation using OEmbed protocol. 3567.1k](/packages/cohensive-oembed) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)