Feature Plugin Merge Proposal: oEmbed

For the past 6 years, users have been able to embed YouTube videos, tweets and many other resources on their sites through a nifty feature called oEmbed.

Today, we (mainly me, @pento and @melchoyce) ask to consider extending this feature by merging the oEmbed API plugin into WordPress core. This plugin allows anyone to embed posts from your site by just pasting its URL. We’ve been working hard on it for months and are now eager to hear your feedback.

Purpose & Goals

While I initially built an early version of the plugin about a year ago, it was @melchoyce who kicked things off with #32522. Her idea was simple: When you can embed almost anything in a WordPress post, why aren’t we able to embed WordPress posts themselves in another WordPress post?

That’s exactly what we’re aiming for. Our goal is to allow a big portion of the web to easily and securely embed such post previews.

Have a look at this post to see the user flow for this feature (and a live demo!):


Security Considerations

Embedding content from a random source on your site depends on lots of trust. We take precautions to make the whole process as easy as possible. It’s worth noting that:

  • We use iframes with the sandbox attribute to enable extra restrictions on the content that can appear in the inline frame.
  • The host and the embedded site communicate via postMessage to allow resizing and clicking on links safely

Browser Compatibility

We successfully tested the feature with all major browsers on mobile and desktop. Since IE < 10 doesn’t support the sandbox attribute, we use the proprietary security attribute there to have similar security restrictions. This means no JavaScript inside the iframe is run, e.g. for the resizing. The most important thing, clicking, still works there though.

Long story short, the feature works with all major browsers and degrades gracefully on older IE versions.

Core Changes & Merge Implementation Details

The plugin was developed in such a way that merging it into core eventually is as straightforward as possible. We are working actively on a patch that can be added to core within the merge window.

There are two things that we need to change in core together with the merge:

  • When doing a redirect because of a changed post slug the rewrite endpoints need to be respected as well. See #33920
  • Attachment rewrite endpoints need to be fixed in core. See #19918
  • This feature only works with oEmbed discovery turned for every user, even those lacking the unfiltered_html capability. That capability check needs to be removed.

Developer Notes

This plugin adds a new /embed/ rewrite endpoint for posts, pages and attachments. We haven’t found any plugin in the directory using this endpoint, but if you already use that endpoint, you should consider renaming it or changing the oEmbed rewrite endpoint using the filters we provide.

Note: There’d be a separate post for this after the merge.

What about the REST API?

The plugin works well on WordPress 3.9+ and uses a simple class to return the oEmbed API responses. However, with the REST API officially proposed for a core merge, we built a controller class for it. This class does exactly the same and follows the REST API best practices.

We could definitely profit from the REST API and built upon it when merging into core. Not needing a fallback means no duplicated code and easier maintenance.

In case you missed it, here’s the REST API merge proposal:


Remaining Issues

There is currently one issue with Slack not displaying the oEmbed output correctly. It simply displays the JavaScript as plain-text instead of removing it. We’ve reached out to them to see if they could fix that and at least white-list WordPress.org in the meantime to properly display the embeds in Slack channels.

Besides that, there are also some small layout quirks we still need to work out. Meanwhile we’re continuing to improve the codebase and inline documentation.

Future Plans

We’re looking into improving support for different response types in addition to regular post content, depending on the feedback we receive from users.


While I’ve been the lead developer of the plugin, a ton of valuable input and contributions have come from others in the community.

#4-4, #feature-plugins, #feature-oembed, #merge, #proposal