PHPackages                             wrav/oembed - 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. [API Development](/categories/api)
4. /
5. wrav/oembed

ActiveCraft-plugin[API Development](/categories/api)

wrav/oembed
===========

A simple plugin to extract media information from websites, like youtube videos, twitter statuses or blog articles.

3.2.1(2mo ago)36205.0k—3.6%37[9 issues](https://github.com/wrav/oembed/issues)[1 PRs](https://github.com/wrav/oembed/pulls)3MITPHP

Since Nov 18Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/wrav/oembed)[ Packagist](https://packagist.org/packages/wrav/oembed)[ RSS](/packages/wrav-oembed/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (94)Used By (3)

oEmbed plugin for Craft CMS 3.x
===============================

[](#oembed-plugin-for-craft-cms-3x)

 [![oEmbed](resources/img/plugin-logo.png)](resources/img/plugin-logo.png)

 [![](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e) [ ![](https://camo.githubusercontent.com/23f47b2dc6069c3bf373e39e13c543da299660fd0ae979091efa961ac793cfc7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f777261762f6f656d626564)](https://github.com/wrav/oembed/releases) [ ![](https://camo.githubusercontent.com/73b4d9d3343328221be5331915b93fd399d843fce76d7cac6f2e15fd0905620e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d61696e7461696e65722d726567616e6c6177746f6e2d626c7565)](https://github.com/reganlawton) [ ![](https://camo.githubusercontent.com/f9def539eaa1d01f6eda9088ecaf470200097cac062bc2e6ddb3d5748e3bc852/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f777261762f6f656d626564)](https://github.com/badges/shields/graphs/contributors) [ ![](https://camo.githubusercontent.com/48040883574461b9e7c66aea4e0b145525e832428279f9b66a0315d847cf3fcd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6d6d69742d61637469766974792f792f777261762f6f656d626564)](https://github.com/wrav/oembed/pulse) [ ![](https://camo.githubusercontent.com/0db61507eb46c8e2442ef1472733b2cffca39d88a315fd880d9363a8355ba040/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732d7261772f777261762f6f656d626564)](https://github.com/wrav/oembed/issues) [ ![](https://camo.githubusercontent.com/b7194f0d2d4962353242484f6290cf960f23891ca2bb2908d66a6d6b6e8fcfd7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f777261762f6f656d626564)](https://packagist.org/packages/wrav/oembed)

A simple plugin to extract media information from websites, like youtube videos, twitter statuses or blog articles.

Seeking a New Maintainer
------------------------

[](#seeking-a-new-maintainer)

It's been nearly nine years since I released the first version of Oembed. While it's been an incredible journey, I no longer have the time or energy to actively maintain the project. Since 2019, I've been deeply involved in building a data and analytics startup, which has grown significantly and now demands most of my focus.

To keep this library alive and thriving, I'm looking for someone passionate about its future to take over its maintenance and development. If you're interested, please reach out by opening an issue or contacting me directly.

In the meantime, I’ll continue merging pull requests from the community to ensure the project doesn’t stagnate, though I won’t be actively contributing new features or updates. Thank you for your support over the years!

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 3.0.0-beta.23 or later.

Versions
--------

[](#versions)

VersionCraftCMS VersionEmbed VersionPHP VersionBranchStatusv1^3.0.0-beta.23^3.3>=7.2.5[v1](https://github.com/wrav/oembed/tree/v1)Discontinuedv2^4.0^3.3^8.0.2[v2](https://github.com/wrav/oembed/tree/v2)Discontinuedv3^3.0 | ^4.0 | ^5.0^v4.4^8.2[v3](https://github.com/wrav/oembed/tree/v3)Activedev-v3-php74-support^3.0 | ^4.0 | ^5.0^v4.4^7.4[dev-v3-php74-support](https://github.com/wrav/oembed/tree/dev-v3-php74-support)Active (PHP 7.4 Support)Quick FYI on URL issues
-----------------------

[](#quick-fyi-on-url-issues)

Many websites, such as Vimeo, are restricting access to standard URLs (e.g. [www.vimeo.com](http://www.vimeo.com)) and sometimes require using the embed URL (e.g., player.vimeo.com) to retrieve oEmbed data.

You can typically find the embed URL through the "share" options on video and oEmbed-supported sites. While the plugin provides general rich content as a fallback, its true potential comes from utilizing the oEmbed protocol and the associated metadata from the content provider.

If you're experiencing issues, check whether the provider or page offers an embed version, and use that URL to ensure you're accessing the most accurate data.

Installing
----------

[](#installing)

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    ```
     cd /path/to/project

    ```
2. Then tell Composer to load the plugin:

    ```
     composer require wrav/oembed

    ```
3. In the Control Panel, go to Settings → Plugins and click the “Install” button for oEmbed.

Using oEmbed
------------

[](#using-oembed)

To use simply call one of the following methods on your field type

```
{{ entry.field.valid }} # Get the embed object
{{ entry.field.render }} # Renders HTML
{{ entry.field.embed }} # Get the embed object
{{ entry.field.media }} # Get the embed object

```

We also provide option to use as a Twig variable

```
{{ craft.oembed.valid(url, options, cacheFields) }}
{{ craft.oembed.render(url, options, cacheFields) }}
{% set embed = craft.oembed.embed(url, options, cacheFields) %}
{% set media = craft.oembed.media(url, options, cacheFields) %}

```

Updating the embed URL, such as autoplay, rel, mute paramaters. This allows for you to support features the provider might not yet support

```
{{
    entry.oembed_field.render({
        params: {
            autoplay: 1,
            rel: 0,
            mute: 0,
            loop: 1,
            autopause: 1,
        },
        attributes: {
            title: 'Main title',
            'data-title': 'Some other title',
        }
    })
}}

```

We still support hte old legacy method, however this might be deprecated in future versions.

```
{{
    entry.oembed_field.render({
         autoplay: 1,
         rel: 0,
         mute: 0,
         loop: 1,
         autopause: 1,
    })
}}

```

Updating the width & height attributes on the iframe can be done using the following method, however is CSS is still recommended view for sizing your iframe.

```
{{
    entry.oembed_field.render({
        width: 640,
        height: 480,
    })
}}

```

or

```
{{
    entry.oembed_field.render({
        attributes: {
            width: 640,
            height: 480,
        }
    })
}}

```

You can access additional media details using the examples below, these are the default keys.

```
entry.field.media.title
entry.field.media.description
entry.field.media.url
entry.field.media.type
entry.field.media.tags
entry.field.media.images
entry.field.media.image
entry.field.media.imageWidth
entry.field.media.imageHeight
entry.field.media.code
entry.field.media.width
entry.field.media.height
entry.field.media.aspectRatio
entry.field.media.authorName
entry.field.media.authorUrl
entry.field.media.providerName
entry.field.media.providerUrl
entry.field.media.providerIcons
entry.field.media.providerIcon
entry.field.media.publishedDate
entry.field.media.license
entry.field.media.linkedData
entry.field.media.feeds

```

You can access additional media details from the data array. These will be snake\_case so be aware.

{{ dump(entry.field.media.data) }}

Additional Embed information can be found [here](https://github.com/oscarotero/Embed)

Cache
-----

[](#cache)

By default, the plugin will cache the following keys on the oembed object. The plugin can cache additional missing fields using the cache prop parameter which will take an array of strings.

{{ entry.oembed\_field.render( { width: 640, height: 480, }, \[ 'cacheable\_key' \] ) }}

### Default Keys

[](#default-keys)

- title
- description
- url
- type
- tags
- images
- image
- imageWidth
- imageHeight
- code
- width
- height
- aspectRatio
- authorName
- authorUrl
- providerName
- providerUrl
- providerIcons
- providerIcon
- publishedDate
- license
- linkedData
- feeds

Cookie Management
-----------------

[](#cookie-management)

The plugin includes automatic cookie file cleanup to prevent server storage issues from accumulating embed-cookie files created by the underlying `embed/embed` library.

### Settings

[](#settings)

Cookie cleanup can be configured in the plugin settings:

- **Enable Cookie Cleanup** (default: `true`) - Enable/disable automatic cookie file cleanup
- **Cookie Max Age** (default: `86400` seconds / 24 hours) - Maximum age of cookie files before cleanup (minimum: 300 seconds)
- **Cookies Path** (optional) - Custom directory path for cookie files (uses system temp directory if empty)

### Manual Cleanup Commands

[](#manual-cleanup-commands)

You can manually manage cookie files using the console commands:

```
# Clean up old cookie files
php craft oembed/cookie/cleanup

# Get information about cookie files
php craft oembed/cookie/info
```

### Automatic Cleanup

[](#automatic-cleanup)

Cookie cleanup runs automatically on plugin initialization with built-in throttling to prevent performance impact:

- Cleanup runs at most once per hour
- Only processes files older than the configured `cookieMaxAge`
- Only removes files matching the pattern `embed-cookies-*`
- Preserves non-cookie files and recently created files

GraphQL
-------

[](#graphql)

I recommend enabling caching in the plugin settings menu to speed up the API resolve timing.

Below is an example of a Oembed field called "foobar" add accessing properties from the embed object.

```
{
  entries {
    id,
    ... on page_page_Entry {
      foobar {
        code,
        providerUrl,
        aspectRatio
      }
    }
  }
}

```

Testing
-------

[](#testing)

This project uses Codeception and Docker Compose (Locally) and I would strongly ask for unit tests, however I understand sometimes this may not be needed.

***NOTE:*** If your wanting to run the all project tests you'll need to set up the required Meta, Twitter, etc API tokens in the `.env` file.

```
# Setting ENV for testing and edit
cp tests/.env.example tests/.env

# Spin up docker
docker compose up -d

# Access shell
docker exec -it app sh

# Run tests via Codeception
vendor/bin/codecept run {your_file}

# Run with Coverage
XDEBUG_MODE=coverage vendor/bin/codecept run --coverage
```

Credits
-------

[](#credits)

Original built while working at [HutSix](https://hutsix.com.au/) I've since been granted permission to continue development here.

Change Log
----------

[](#change-log)

Changes can be viewed [here](https://github.com/wrav/oembed/blob/master/CHANGELOG.md)

Support
-------

[](#support)

Get in touch via email, Discord, or by [creating a Github issue](/wrav/oembed/issues)

###  Health Score

61

—

FairBetter than 99% of packages

Maintenance80

Actively maintained with recent releases

Popularity47

Moderate usage in the ecosystem

Community28

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 88.1% 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 ~41 days

Recently: every ~82 days

Total

65

Last Release

75d ago

Major Versions

1.3.17 → 2.1.02022-06-29

1.3.18 → 2.2.02022-06-30

v1.x-dev → 2.3.02023-02-02

2.3.0 → 3.0.02023-11-08

v2.x-dev → 3.0.52023-12-08

### Community

Maintainers

![](https://www.gravatar.com/avatar/d5f309c706fe603aca960d88d4a88e5fdcc14cacc89556757b1897c8d7decbe8?d=identicon)[reganlawton](/maintainers/reganlawton)

---

Top Contributors

[![reganlawton](https://avatars.githubusercontent.com/u/2705875?v=4)](https://github.com/reganlawton "reganlawton (171 commits)")[![JeroenJRP](https://avatars.githubusercontent.com/u/15321825?v=4)](https://github.com/JeroenJRP "JeroenJRP (5 commits)")[![joshuabaker](https://avatars.githubusercontent.com/u/160484?v=4)](https://github.com/joshuabaker "joshuabaker (4 commits)")[![juban](https://avatars.githubusercontent.com/u/1687683?v=4)](https://github.com/juban "juban (3 commits)")[![davidwebca](https://avatars.githubusercontent.com/u/412352?v=4)](https://github.com/davidwebca "davidwebca (2 commits)")[![jeffreyzant](https://avatars.githubusercontent.com/u/913317?v=4)](https://github.com/jeffreyzant "jeffreyzant (1 commits)")[![jaapfaes](https://avatars.githubusercontent.com/u/930512?v=4)](https://github.com/jaapfaes "jaapfaes (1 commits)")[![gglnx](https://avatars.githubusercontent.com/u/23519?v=4)](https://github.com/gglnx "gglnx (1 commits)")[![mijewe](https://avatars.githubusercontent.com/u/1457786?v=4)](https://github.com/mijewe "mijewe (1 commits)")[![mofman](https://avatars.githubusercontent.com/u/3038169?v=4)](https://github.com/mofman "mofman (1 commits)")[![raymondelooff](https://avatars.githubusercontent.com/u/9716806?v=4)](https://github.com/raymondelooff "raymondelooff (1 commits)")[![FlorisDerks](https://avatars.githubusercontent.com/u/1500538?v=4)](https://github.com/FlorisDerks "FlorisDerks (1 commits)")[![samuelbirch](https://avatars.githubusercontent.com/u/13586?v=4)](https://github.com/samuelbirch "samuelbirch (1 commits)")[![sgtpenguin](https://avatars.githubusercontent.com/u/16600959?v=4)](https://github.com/sgtpenguin "sgtpenguin (1 commits)")

---

Tags

craftcraft-plugincraftcmsgraphqliframeinstagramoembedtwittervimeoyoutubefacebookinstagramgraphqlyoutubecmstwittervimeoCraftcraftcmscraft-plugingdproembediframe

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wrav-oembed/health.svg)

```
[![Health](https://phpackages.com/badges/wrav-oembed/health.svg)](https://phpackages.com/packages/wrav-oembed)
```

###  Alternatives

[hut6/oembed

A simple plugin to extract media information from websites, like youtube videos, twitter statuses or blog articles.

102.3k](/packages/hut6-oembed)[nystudio107/craft-seomatic

SEOmatic facilitates modern SEO best practices & implementation for Craft CMS 5. It is a turnkey SEO system that is comprehensive, powerful, and flexible.

1741.4M46](/packages/nystudio107-craft-seomatic)[verbb/hyper

A user-friendly links field for Craft.

24130.9k9](/packages/verbb-hyper)[craftpulse/craft-typesense

Craft Plugin that synchronises with Typesense

122.7k](/packages/craftpulse-craft-typesense)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)