Lee Willis

Simple embedding for non oEmbed services


I recently posted about my GitHub embed plugin for WordPress. The plugin performs a neat trick of hooking into WordPress’ oEmbed infrastructure to allow you just to paste in a URL and retrieve an embed for a service that doesn’t natively support oEmbed.

This post is just a quick walk through explaining the approach. In general the plugin:

  • Registers an oEmbed handler for the selected URLs (http://github.com/{something} in our example)
  • Registers an internal oEmbed handler for that URL
  • Handles the oEmbed call itself, retrieving the details it needs via the 3rd party’s API and then passing WordPress back an oEmbed response

Effectively you make your own site an oEmbed provider for the service you want to embed. Here’s the key bits of code:

First – we register an oEmbed handler, and point it to an internal URL:

function register_oembed_handler() {
    $oembed_url = home_url ();
    $key = get_key();
    $oembed_url = add_query_arg ( array ( 'github_oembed' => $key ), $oembed_url);
    wp_oembed_add_provider ( '#https?://github.com/.*#i', $oembed_url, true );
add_action ( 'init', 'register_oembed_handler' );

Note: get_key() just generates a site-specific key to stop other people using your oEmbed service.

Next, we tell WordPress to look out for an inbound oEmbed request:

function handle_oembed() {

    if ( ! isset ( $_GET['github_oembed'] ) ) {
    // Check this request is valid
    if ( $_GET['github_oembed'] != $this->get_key() ) {
        header ( 'HTTP/1.0 403 Forbidden' );
	die ( 'Sad Octocat is sad.' );

    // Check we have the required information
    $url = isset ( $_REQUEST['url'] ) ? $_REQUEST['url'] : null;
    $format = isset ( $_REQUEST['format'] ) ? $_REQUEST['format'] : null;

    // Call the 3rd party service, and create an oEmbed response here

add_action ( 'init', 'handle_oembed' );

All we need to do now, is retrieve the details we need using whatever API tools are available, then create an oEmbed response, e.g.

    $response = new stdClass();
    $response->type = 'rich';
    $response->width = '10';
    $response->height = '10';
    $response->version = '1.0';
    $response->title = $repo->description;
    $response->html = 'Your info here';
    header ( 'Content-Type: application/json' );
    echo json_encode ( $response );

And that’s it in theory, simple as pie. If you want to see working example, checkout out the github embed plugin on github:

Leave a Reply

Required fields are marked *.