{"id":13545559,"url":"https://github.com/essence/essence","last_synced_at":"2025-12-18T02:51:43.791Z","repository":{"id":4172808,"uuid":"5288828","full_name":"essence/essence","owner":"essence","description":"Extracts information about web pages, like youtube videos, twitter statuses or blog articles.","archived":false,"fork":false,"pushed_at":"2023-03-29T11:04:23.000Z","size":1360,"stargazers_count":767,"open_issues_count":24,"forks_count":81,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-05-22T15:10:39.860Z","etag":null,"topics":["embed","oembed","opengraph","php","twitter-cards"],"latest_commit_sha":null,"homepage":"http://essence.github.io/essence","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/essence.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-08-03T18:26:52.000Z","updated_at":"2024-05-18T05:47:56.000Z","dependencies_parsed_at":"2023-07-05T17:15:34.509Z","dependency_job_id":null,"html_url":"https://github.com/essence/essence","commit_stats":{"total_commits":656,"total_committers":25,"mean_commits":26.24,"dds":0.07317073170731703,"last_synced_commit":"81e889a87603840dadd04b317a51487df1d45933"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/essence%2Fessence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/essence%2Fessence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/essence%2Fessence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/essence%2Fessence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/essence","download_url":"https://codeload.github.com/essence/essence/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246841728,"owners_count":20842638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embed","oembed","opengraph","php","twitter-cards"],"created_at":"2024-08-01T11:01:05.635Z","updated_at":"2025-12-18T02:51:38.765Z","avatar_url":"https://github.com/essence.png","language":"PHP","readme":"![Essence](http://www.felix-girault.fr/wp-content/uploads/2015/10/essence31.png)\n\n[![Build status](http://img.shields.io/travis/essence/essence.svg?style=flat-square)](http://travis-ci.org/essence/essence)\n[![Scrutinizer Code Quality](http://img.shields.io/scrutinizer/g/essence/essence.svg?style=flat-square)](https://scrutinizer-ci.com/g/essence/essence)\n[![Code Coverage](http://img.shields.io/scrutinizer/coverage/g/essence/essence.svg?style=flat-square)](https://scrutinizer-ci.com/g/essence/essence)\n[![Total downloads](http://img.shields.io/packagist/dt/essence/essence.svg?style=flat-square)](https://packagist.org/packages/essence/essence)\n\nEssence is a simple PHP library to extract media information from websites, like youtube videos, twitter statuses or blog articles.\n\nIf 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).\n\nInstallation\n------------\n\n```\ncomposer require essence/essence\n```\n\nExample\n-------\n\nEssence is designed to be really easy to use.\nUsing the main class of the library, you can retrieve information in just those few lines:\n\n```php\n$Essence = new Essence\\Essence();\n$Media = $Essence-\u003eextract('http://www.youtube.com/watch?v=39e3KYAmXK4');\n\nif ($Media) {\n\t// That's all, you're good to go !\n}\n```\n\nThen, just do anything you want with the data:\n\n```html+php\n\u003carticle\u003e\n\t\u003cheader\u003e\n\t\t\u003ch1\u003e\u003c?php echo $Media-\u003etitle; ?\u003e\u003c/h1\u003e\n\t\t\u003cp\u003eBy \u003c?php echo $Media-\u003eauthorName; ?\u003e\u003c/p\u003e\n\t\u003c/header\u003e\n\n\t\u003cdiv class=\"player\"\u003e\n\t\t\u003c?php echo $Media-\u003ehtml; ?\u003e\n\t\u003c/div\u003e\n\u003c/article\u003e\n```\n\nWhat you get\n------------\n\nUsing Essence, you will mainly interact with Media objects.\nMedia is a simple container for all the information that are fetched from an URL.\n\nHere are the default properties it provides:\n\n* type\n* version\n* url\n* title\n* description\n* authorName\n* authorUrl\n* providerName\n* providerUrl\n* cacheAge\n* thumbnailUrl\n* thumbnailWidth\n* thumbnailHeight\n* html\n* width\n* height\n\nThese properties were gathered from the OEmbed and OpenGraph specifications, and merged together in a united interface.\nBased on such standards, these properties should be a solid starting point.\n\nHowever, \"non-standard\" properties can and will also be setted.\n\nHere is how you can manipulate the Media properties:\n\n```php\n// through dedicated methods\nif (!$Media-\u003ehas('foo')) {\n\t$Media-\u003eset('foo', 'bar');\n}\n\n$value = $Media-\u003eget('foo');\n\n// or directly like a class attribute\n$Media-\u003ecustomValue = 12;\n```\n\nNote that Essence will always try to fill the `html` property when it is not available.\n\nAdvanced usage\n--------------\n\nThe Essence class provides some useful utility functions to ensure you will get some information.\n\n### Extracting URLs\n\nThe `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).\n\nFor example, here is how you could get the URL of all videos in a blog post:\n\n```php\n$urls = $Essence-\u003ecrawlUrl('http://www.blog.com/article');\n```\n```\narray(2) {\n\t[0] =\u003e 'http://www.youtube.com/watch?v=123456',\n\t[1] =\u003e 'http://www.dailymotion.com/video/a1b2c_lolcat-fun'\n}\n```\n\nYou can then get information from all the extracted URLs:\n\n```php\n$medias = $Essence-\u003eextractAll($urls);\n```\n```\narray(2) {\n\t['http://www.youtube.com/watch?v=123456'] =\u003e object(Media) {}\n\t['http://www.dailymotion.com/video/a1b2c_lolcat-fun'] =\u003e object(Media) {}\n}\n```\n\n### Replacing URLs in text\n\nEssence can replace any extractable URL in a text by information about it.\nBy default, any URL will be replaced by the `html` property of the found Media.\n\n```php\necho $Essence-\u003ereplace('Look at this: http://www.youtube.com/watch?v=123456');\n```\n```html\nLook at this: \u003ciframe src=\"http://www.youtube.com/embed/123456\"\u003e\u003c/iframe\u003e\n```\n\nBut you can do more by passing a callback to control which information will replace the URL:\n\n```php\necho $Essence-\u003ereplace($text, function($Media) {\n\treturn \u003c\u003c\u003cHTML\n\t\t\u003cp class=\"title\"\u003e$Media-\u003etitle\u003c/p\u003e\n\t\t\u003cdiv class=\"player\"\u003e$Media-\u003ehtml\u003c/div\u003e\nHTML;\n});\n```\n```html\nLook at this:\n\u003cp class=\"title\"\u003eVideo title\u003c/p\u003e\n\u003cdiv class=\"player\"\u003e\n\t\u003ciframe src=\"http://www.youtube.com/embed/123456\"\u003e\u003c/iframe\u003e\n\u003cdiv\u003e\n```\n\nThis makes it easy to build rich templates or even to integrate a templating engine:\n\n```php\necho $Essence-\u003ereplace($text, function($Media) use ($TwigTemplate) {\n\treturn $TwigTemplate-\u003erender($Media-\u003eproperties());\n});\n```\n\n### Configuring providers\n\nIt is possible to pass some options to the providers.\n\nFor example, OEmbed providers accepts the `maxwidth` and `maxheight` parameters, as specified in the OEmbed spec.\n\n```php\n$options = [\n\t'maxwidth' =\u003e 800,\n\t'maxheight' =\u003e 600\n];\n\n$Media = $Essence-\u003eextract($url, $options);\n$medias = $Essence-\u003eextractAll($urls, $options);\n$text = $Essence-\u003ereplace($text, null, $options);\n```\n\nOther providers will just ignore the options they don't handle.\n\nConfiguration\n-------------\n\nEssence currently supports 68 specialized providers:\n\n```html\n23hq                Deviantart          Kickstarter         Sketchfab\nAnimoto             Dipity              Meetup              SlideShare\nAol                 Dotsub              Mixcloud            SoundCloud\nApp.net             Edocr               Mobypicture         SpeakerDeck\nBambuser            Flickr              Nfb                 Spotify\nBandcamp            FunnyOrDie          Official.fm         Ted\nBlip.tv             Gist                Polldaddy           Twitter\nCacoo               Gmep                PollEverywhere      Ustream\nCanalPlus           HowCast             Prezi               Vhx\nChirb.it            Huffduffer          Qik                 Viddler\nCircuitLab          Hulu                Rdio                Videojug\nClikthrough         Ifixit              Revision3           Vimeo\nCollegeHumor        Ifttt               Roomshare           Vine\nCoub                Imgur               Sapo                Wistia\nCrowdRanking        Instagram           Screenr             WordPress\nDailyMile           Jest                Scribd              Yfrog\nDailymotion         Justin.tv           Shoudio             Youtube\n```\n\nPlus the `OEmbed` and `OpenGraph` providers, which can be used to extract any URL.\n\nYou can configure these providers on instanciation:\n\n```php\n$Essence = new Essence\\Essence([\n\t// the SoundCloud provider is an OEmbed provider with a specific endpoint\n\t'SoundCloud' =\u003e Essence\\Di\\Container::unique(function($C) {\n\t\treturn $C-\u003eget('OEmbedProvider')-\u003esetEndpoint(\n\t\t\t'http://soundcloud.com/oembed?format=json\u0026url=:url'\n\t\t);\n\t}),\n\n\t'filters' =\u003e [\n\t\t// the SoundCloud provider will be used for URLs that matches this pattern\n\t\t'SoundCloud' =\u003e '~soundcloud\\.com/[a-zA-Z0-9-_]+/[a-zA-Z0-9-]+~i'\n\t]\n]);\n```\n\nYou can also disable the default ones:\n\n```php\n$Essence = new Essence\\Essence([\n\t'filters' =\u003e [\n\t\t'SoundCloud' =\u003e false\n\t]\n]);\n```\n\nYou will find the default configuration in the standard DI container of Essence\n(see the following part).\n\nCustomization\n-------------\n\nAlmost everything in Essence can be configured through dependency injection.\nUnder the hoods, the constructor uses a dependency injection container to return a fully configured instance of Essence.\n\nTo customize the Essence behavior, the easiest way is to configure injection settings when building Essence:\n\n```php\n$Essence = new Essence\\Essence([\n\t// the container will return a unique instance of CustomHttpClient\n\t// each time an HTTP client is needed\n\t'Http' =\u003e Essence\\Di\\Container::unique(function() {\n\t\treturn new CustomHttpClient();\n\t})\n]);\n```\n\nThe default injection settings are defined in the [Standard](https://github.com/essence/essence/blob/master/lib/Essence/Di/Container/Standard.php) container class.\n\nTry it out\n----------\n\nOnce you've installed essence, you should try to run `./cli/essence.php` in a terminal.\nThis script allows you to test Essence quickly:\n\n```\n# will fetch and print information about the video\n./cli/essence.php extract http://www.youtube.com/watch?v=4S_NHY9c8uM\n\n# will fetch and print all extractable URLs found at the given HTML page\n./cli/essence.php crawl http://www.youtube.com/watch?v=4S_NHY9c8uM\n```\n\nThird-party libraries\n---------------------\n\nIf you're interested in embedding videos, you should take a look at the [Multiplayer](https://github.com/felixgirault/multiplayer) lib.\nIt allows you to build customizable embed codes painlessly:\n\n```php\n$Multiplayer = new Multiplayer\\Multiplayer();\n\nif ($Media-\u003etype === 'video') {\n\techo $Multiplayer-\u003ehtml($Media-\u003eurl, [\n\t\t'autoPlay' =\u003e true,\n\t\t'highlightColor' =\u003e 'BADA55'\n\t]);\n}\n```\n","funding_links":[],"categories":["PHP","Table of Contents","杂项 Miscellaneous","目录","Configuration"],"sub_categories":["Markup and CSS","标记和CSS Markup and CSS","Miscellaneous"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessence%2Fessence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fessence%2Fessence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessence%2Fessence/lists"}