From 6a11078b8ab82e870394b2149d9a6bd5a41948ed Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:21:59 +0200
Subject: [PATCH 1/5] Prototype oEmbed-only provider support

---
 README.md                                |  2 +-
 data/stubs.php                           | 18 +++++++++++-
 docs/README.md                           | 35 ++++++++++++++++++++++--
 docs/supported.md                        | 23 ++++++++--------
 src/Docs/Generator.php                   |  8 +++++-
 src/MediaEmbed.php                       | 24 ++++++++++++++--
 src/Provider/ProviderCollection.php      |  7 +++++
 src/Provider/ProviderConfig.php          | 29 +++++++++++++++++---
 src/Provider/ProviderValidator.php       |  5 +++-
 tests/Fixture/provider_urls.php          |  6 ++++
 tests/MediaEmbedTest.php                 | 34 +++++++++++++++++++++--
 tests/Provider/ProviderConfigTest.php    | 32 ++++++++++++++++++++--
 tests/Provider/ProviderValidatorTest.php | 17 +++++++++++-
 tests/ProviderFixtureTest.php            |  7 ++++-
 14 files changed, 218 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index b04c1f4..54e4738 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
 A utility library that generates HTML embed tags for audio or video located on a given URL.
 It also parses and validates given media URLs.
 
-It currently works with [~42 services](docs/supported.md), including the most important ones like
+It currently works with [40+ services](docs/supported.md), including the most important ones like
 
 - YouTube
 - Vimeo
diff --git a/data/stubs.php b/data/stubs.php
index eb2d36e..eaa577a 100644
--- a/data/stubs.php
+++ b/data/stubs.php
@@ -20,7 +20,8 @@
 	 * - "embed-width" (string) Width of the embed (in pixels)
 	 * - "embed-height" (string) Height of the embed (in pixels)
 	 * - "image-src" (string) For preview thumbnail image
-	 * - "iframe-player" (string) If an <iframe> player is available
+	 * - "iframe-player" (string) If an <iframe> player is available (or use "oembed")
+	 * - "oembed" (string) oEmbed endpoint for provider-generated HTML (or use "iframe-player")
 	 * - "id" (string) The ID of the video, returned as $id
 	 */
 	[
@@ -61,6 +62,21 @@
 		'embed-height' => '295',
 		'iframe-player' => '//www.facebook.com/plugins/video.php?href=$1&show_text=0',
 	],
+	[
+		'name' => 'Tumblr',
+		'website' => 'https://www.tumblr.com',
+		'status' => 'active',
+		'category' => 'social',
+		'example-url' => 'https://staff.tumblr.com/post/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone',
+		'url-match' => [
+			'https?://[a-z0-9-]+\\.tumblr\\.com/post/([0-9]+)(?:/[^?#]+)?',
+			'https?://www\\.tumblr\\.com/[a-z0-9-]+/([0-9]+)(?:/[^?#]+)?',
+		],
+		'embed-width' => 540,
+		'embed-height' => 600,
+		'oembed' => 'https://www.tumblr.com/oembed/1.0',
+		'notes' => 'Uses oEmbed HTML because Tumblr post embeds require provider-generated markup.',
+	],
 	[
 		'name' => 'Dailymotion',
 		'website' => 'https://www.dailymotion.com',
diff --git a/docs/README.md b/docs/README.md
index 33c69a1..2bb20b3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -335,7 +335,8 @@ $config = new ProviderConfig(
     urlMatch: ['regex...'],       // Required: URL patterns (array or string)
     embedWidth: 640,              // Required: Default width
     embedHeight: 360,             // Required: Default height
-    iframePlayer: '//.../$2',     // Required: Iframe URL template
+    iframePlayer: '//.../$2',     // Iframe URL template (or use oEmbed)
+    oEmbed: 'https://.../oembed', // oEmbed endpoint (or use iframePlayer)
     status: 'active',             // Optional: active, legacy, deprecated
     category: 'video',            // Optional: video, audio, social, streaming, 3d
     exampleUrl: 'https://...',    // Optional: fixture/example URL
@@ -357,7 +358,8 @@ For array-based configs (legacy format):
 - **url-match** (required): Array of regex patterns to match URLs
 - **embed-width** (required): Default width in pixels or as percentage
 - **embed-height** (required): Default height in pixels or as percentage
-- **iframe-player** (required): URL template for iframe embedding
+- **iframe-player**: URL template for iframe embedding; either this or `oembed` is required
+- **oembed**: Provider oEmbed endpoint; either this or `iframe-player` is required
 - **status**: Optional provider lifecycle status (`active`, `legacy`, `deprecated`)
 - **category**: Optional content category (`video`, `audio`, `social`, `streaming`, `3d`)
 - **example-url**: Optional example URL covered by release fixture tests
@@ -536,6 +538,7 @@ $subset = $MediaEmbed->getProviders(['youtube', 'vimeo', 'dailymotion']);
 
 // Filter by capabilities
 $withIframe = $providers->withIframeSupport();
+$withOEmbed = $providers->withOEmbedSupport();
 $withThumbnails = $providers->withThumbnailSupport();
 $active = $providers->withStatus('active');
 $video = $providers->withCategory('video');
@@ -596,6 +599,34 @@ $thumb = $mediaEmbed->thumbnail($mediaObject); // string|null
 
 `oEmbed()` returns null when the provider has no registered endpoint or the object was created via `parseId()` (no source URL). These calls perform an HTTP request, so a PSR-16 cache (and the injected HTTP client) apply.
 
+For providers whose embed can only be generated dynamically, `iframe-player` may be omitted when an `oembed` endpoint is configured. Use `oEmbedHtml()` to fetch the provider-generated markup:
+
+```php
+$mediaObject = $mediaEmbed->parseUrl('https://social.example.com/posts/123');
+$html = $mediaEmbed->oEmbedHtml($mediaObject);
+
+// The HTML comes from the remote provider. Only render trusted provider output,
+// or sanitize it according to your application's policy.
+echo $html;
+```
+
+Custom oEmbed-only providers can be registered inline without modifying the bundled provider file:
+
+```php
+$mediaEmbed = new MediaEmbed([
+	'custom_providers' => [[
+		'name' => 'Example Social',
+		'website' => 'https://social.example.com',
+		'url-match' => 'https://social\\.example\\.com/posts/([0-9]+)',
+		'embed-width' => 540,
+		'embed-height' => 600,
+		'oembed' => 'https://social.example.com/oembed',
+	]],
+]);
+```
+
+The same provider array can be loaded from PHP or JSON through `providers_config`, `ArrayLoader`, `PhpFileLoader`, or `JsonFileLoader`. This keeps application-specific providers outside the package so they can be updated independently.
+
 ### oEmbed Discovery
 
 For URLs not covered by built-in providers, use oEmbed auto-discovery:
diff --git a/docs/supported.md b/docs/supported.md
index ec1cd9c..da86958 100644
--- a/docs/supported.md
+++ b/docs/supported.md
@@ -1,6 +1,6 @@
 # Supported Media Services
 
-42 services (41 active, 1 legacy)
+43 services (42 active, 1 legacy)
 
 Provider example URLs are covered by the release fixture matrix in `tests/Fixture/provider_urls.php`.
 
@@ -9,7 +9,7 @@ Provider example URLs are covered by the release fixture matrix in `tests/Fixtur
 | [Aparat](https://www.aparat.com) | active | video | iframe |  |
 | [Apple Music](https://music.apple.com) | active | audio | iframe |  |
 | [Apple Podcasts](https://podcasts.apple.com) | active | audio | iframe |  |
-| [Audiomack](https://audiomack.com) | active | audio | iframe |  |
+| [Audiomack](https://audiomack.com) | active | audio | iframe, oEmbed |  |
 | [Bandcamp](https://bandcamp.com) | active | audio | iframe |  |
 | [Bilibili](https://www.bilibili.com) | active | video | iframe |  |
 | [Bilibili (Legacy)](https://www.bilibili.com) | legacy | video | iframe | Legacy URL format kept for existing links. |
@@ -25,7 +25,7 @@ Provider example URLs are covered by the release fixture matrix in `tests/Fixtur
 | [Mastodon](https://joinmastodon.org) | active | social | iframe | Federated: matches any instance host serving the /@user/id status format. |
 | [Matterport](https://matterport.com) | active | 3d | iframe |  |
 | [Metatube](https://www.metatube.com) | active | video | iframe |  |
-| [Mixcloud](https://www.mixcloud.com) | active | audio | iframe |  |
+| [Mixcloud](https://www.mixcloud.com) | active | audio | iframe, oEmbed |  |
 | [Niconico](https://www.nicovideo.jp) | active | video | iframe |  |
 | [Odysee](https://odysee.com) | active | video | iframe |  |
 | [PeerTube](https://joinpeertube.org) | active | video | iframe |  |
@@ -34,17 +34,18 @@ Provider example URLs are covered by the release fixture matrix in `tests/Fixtur
 | [Rumble](https://rumble.com) | active | video | iframe |  |
 | [RuTube](https://www.rutube.ru) | active | video | iframe |  |
 | [Screencast](https://www.screencast.com) | active | video | iframe, fetch |  |
-| [Sketchfab](https://sketchfab.com) | active | 3d | iframe |  |
-| [SoundCloud](https://soundcloud.com) | active | audio | iframe |  |
-| [Spotify](https://open.spotify.com) | active | audio | iframe |  |
-| [Spreaker](https://www.spreaker.com) | active | audio | iframe | Episode URLs only; show pages expose no numeric ID in the URL. |
+| [Sketchfab](https://sketchfab.com) | active | 3d | iframe, oEmbed |  |
+| [SoundCloud](https://soundcloud.com) | active | audio | iframe, oEmbed |  |
+| [Spotify](https://open.spotify.com) | active | audio | iframe, oEmbed |  |
+| [Spreaker](https://www.spreaker.com) | active | audio | iframe, oEmbed | Episode URLs only; show pages expose no numeric ID in the URL. |
 | [Streamable](https://streamable.com) | active | video | iframe |  |
-| [TED](https://www.ted.com) | active | video | iframe |  |
-| [TikTok](https://www.tiktok.com) | active | social | iframe |  |
+| [TED](https://www.ted.com) | active | video | iframe, oEmbed |  |
+| [TikTok](https://www.tiktok.com) | active | social | iframe, oEmbed |  |
+| [Tumblr](https://www.tumblr.com) | active | social | oEmbed | Uses oEmbed HTML because Tumblr post embeds require provider-generated markup. |
 | [Twitch Clip](https://clips.twitch.tv) | active | streaming | iframe |  |
 | [Twitch Video](https://www.twitch.tv) | active | streaming | iframe |  |
 | [Twitter](https://twitter.com) | active | social | iframe |  |
-| [Vimeo](https://www.vimeo.com) | active | video | iframe |  |
+| [Vimeo](https://www.vimeo.com) | active | video | iframe, oEmbed |  |
 | [Vooplayer](https://vooplayer.com/) | active | video | iframe |  |
 | [Wistia](https://www.wistia.com) | active | video | iframe |  |
-| [YouTube](https://www.youtube.com) | active | video | iframe, thumbnail, timestamp |  |
+| [YouTube](https://www.youtube.com) | active | video | iframe, oEmbed, thumbnail, timestamp |  |
diff --git a/src/Docs/Generator.php b/src/Docs/Generator.php
index 4aeb6f5..07d84e1 100644
--- a/src/Docs/Generator.php
+++ b/src/Docs/Generator.php
@@ -120,7 +120,13 @@ protected function name(array $array): string {
 	 * @return string
 	 */
 	protected function capabilities(array $array): string {
-		$capabilities = ['iframe'];
+		$capabilities = [];
+		if (!empty($array['iframe-player'])) {
+			$capabilities[] = 'iframe';
+		}
+		if (!empty($array['oembed'])) {
+			$capabilities[] = 'oEmbed';
+		}
 
 		if (!empty($array['image-src'])) {
 			$capabilities[] = 'thumbnail';
diff --git a/src/MediaEmbed.php b/src/MediaEmbed.php
index e8b4e9b..6069e2f 100644
--- a/src/MediaEmbed.php
+++ b/src/MediaEmbed.php
@@ -476,6 +476,26 @@ public function oEmbed(MediaObject $object, ?int $maxWidth = null, ?int $maxHeig
 		return $this->oEmbedDiscovery()->fetch($endpoint, $maxWidth, $maxHeight);
 	}
 
+	/**
+	 * Fetch raw embed HTML from a provider's oEmbed response.
+	 *
+	 * The returned HTML is controlled by the remote provider. Consumers must only
+	 * render it for trusted providers, or sanitize it according to their policy.
+	 *
+	 * @param \MediaEmbed\Object\MediaObject $object Parsed media object.
+	 * @param int|null $maxWidth Maximum embed width.
+	 * @param int|null $maxHeight Maximum embed height.
+	 * @return string|null
+	 */
+	public function oEmbedHtml(MediaObject $object, ?int $maxWidth = null, ?int $maxHeight = null): ?string {
+		$response = $this->oEmbed($object, $maxWidth, $maxHeight);
+		if ($response === null || !$response->hasHtml()) {
+			return null;
+		}
+
+		return $response->html;
+	}
+
 	/**
 	 * Resolve a thumbnail URL for a parsed media object.
 	 *
@@ -572,8 +592,8 @@ public function getProviders(array $whitelist = []): ProviderCollection {
 	 */
 	public function addProviderConfig(ProviderConfig $config, bool $override = false) {
 		$slug = $config->slug ?? $this->slug($config->name);
-		if ($config->iframePlayer === null || $config->iframePlayer === '') {
-			throw ProviderConfigException::missingField('iframe-player', $config->toArray());
+		if (!$config->hasIframeSupport() && !$config->hasOEmbedSupport()) {
+			throw ProviderConfigException::missingField('iframe-player or oembed', $config->toArray());
 		}
 
 		if (!$override && isset($this->providers[$slug])) {
diff --git a/src/Provider/ProviderCollection.php b/src/Provider/ProviderCollection.php
index 8852e73..5c3d88b 100644
--- a/src/Provider/ProviderCollection.php
+++ b/src/Provider/ProviderCollection.php
@@ -187,6 +187,13 @@ public function withIframeSupport(): self {
 		return $this->filter(fn (ProviderConfig $config) => $config->hasIframeSupport());
 	}
 
+	/**
+	 * Get providers with oEmbed support.
+	 */
+	public function withOEmbedSupport(): self {
+		return $this->filter(fn (ProviderConfig $config) => $config->hasOEmbedSupport());
+	}
+
 	/**
 	 * Get providers with thumbnail support.
 	 */
diff --git a/src/Provider/ProviderConfig.php b/src/Provider/ProviderConfig.php
index a6e6af4..13b5f22 100644
--- a/src/Provider/ProviderConfig.php
+++ b/src/Provider/ProviderConfig.php
@@ -35,6 +35,7 @@ final class ProviderConfig {
 	 * @param \MediaEmbed\Provider\Enum\Category $category Provider content category.
 	 * @param string|null $exampleUrl Example URL covered by provider tests.
 	 * @param string|null $notes Provider notes for generated docs.
+	 * @param string|null $oEmbed oEmbed endpoint URL.
 	 */
 	public function __construct(
 		public readonly string $name,
@@ -55,6 +56,7 @@ public function __construct(
 		public readonly Category $category = Category::Video,
 		public readonly ?string $exampleUrl = null,
 		public readonly ?string $notes = null,
+		public readonly ?string $oEmbed = null,
 	) {
 	}
 
@@ -82,12 +84,17 @@ public static function fromArray(array $data): self {
 		if (!isset($data['embed-height'])) {
 			throw ProviderConfigException::missingField('embed-height', $data);
 		}
-		if (!array_key_exists('iframe-player', $data) || $data['iframe-player'] === null || $data['iframe-player'] === '') {
-			throw ProviderConfigException::missingField('iframe-player', $data);
+		$iframePlayer = $data['iframe-player'] ?? null;
+		$oEmbed = $data['oembed'] ?? null;
+		if (($iframePlayer === null || $iframePlayer === '') && ($oEmbed === null || $oEmbed === '')) {
+			throw ProviderConfigException::missingField('iframe-player or oembed', $data);
 		}
-		if (!is_string($data['iframe-player'])) {
+		if ($iframePlayer !== null && !is_string($iframePlayer)) {
 			throw ProviderConfigException::invalidField('iframe-player', $data['iframe-player'], 'string', $data);
 		}
+		if ($oEmbed !== null && !is_string($oEmbed)) {
+			throw ProviderConfigException::invalidField('oembed', $data['oembed'], 'string', $data);
+		}
 
 		$embedWidth = self::dimensionFromArray($data, 'embed-width');
 		$embedHeight = self::dimensionFromArray($data, 'embed-height');
@@ -104,6 +111,7 @@ public static function fromArray(array $data): self {
 			'notes',
 			'slug',
 			'iframe-player',
+			'oembed',
 			'image-src',
 			'id',
 			'fetch-match',
@@ -126,7 +134,8 @@ public static function fromArray(array $data): self {
 			exampleUrl: isset($data['example-url']) && is_string($data['example-url']) ? $data['example-url'] : null,
 			notes: isset($data['notes']) && is_string($data['notes']) ? $data['notes'] : null,
 			slug: $data['slug'] ?? null,
-			iframePlayer: $data['iframe-player'],
+			iframePlayer: $iframePlayer,
+			oEmbed: $oEmbed,
 			imageSrc: $data['image-src'] ?? null,
 			id: $data['id'] ?? null,
 			fetchMatch: $data['fetch-match'] ?? null,
@@ -181,6 +190,9 @@ public function toArray(): array {
 		if ($this->iframePlayer !== null) {
 			$array['iframe-player'] = $this->iframePlayer;
 		}
+		if ($this->oEmbed !== null) {
+			$array['oembed'] = $this->oEmbed;
+		}
 		if ($this->imageSrc !== null) {
 			$array['image-src'] = $this->imageSrc;
 		}
@@ -225,6 +237,15 @@ public function hasIframeSupport(): bool {
 		return $this->iframePlayer !== null;
 	}
 
+	/**
+	 * Check if this provider has oEmbed support.
+	 *
+	 * @return bool
+	 */
+	public function hasOEmbedSupport(): bool {
+		return $this->oEmbed !== null;
+	}
+
 	/**
 	 * Check if this provider has thumbnail support.
 	 *
diff --git a/src/Provider/ProviderValidator.php b/src/Provider/ProviderValidator.php
index 75c8fc5..45f1613 100644
--- a/src/Provider/ProviderValidator.php
+++ b/src/Provider/ProviderValidator.php
@@ -35,7 +35,6 @@ public function __construct(?SluggerInterface $slugger = null) {
 		'url-match',
 		'embed-width',
 		'embed-height',
-		'iframe-player',
 	];
 
 	/**
@@ -88,6 +87,10 @@ private function validateRequiredFields(array $provider, string $label, array &$
 				$errors[] = $label . ': missing required field "' . $field . '"';
 			}
 		}
+
+		if (empty($provider['iframe-player']) && empty($provider['oembed'])) {
+			$errors[] = $label . ': missing required field "iframe-player" or "oembed"';
+		}
 	}
 
 	/**
diff --git a/tests/Fixture/provider_urls.php b/tests/Fixture/provider_urls.php
index f525b6c..25c5edd 100644
--- a/tests/Fixture/provider_urls.php
+++ b/tests/Fixture/provider_urls.php
@@ -256,4 +256,10 @@
 		'id' => '99360735500167749',
 		'embedSrc' => 'https://assets.pinterest.com/ext/embed.html?id=99360735500167749&wmode=transparent',
 	],
+	[
+		'slug' => 'tumblr',
+		'url' => 'https://staff.tumblr.com/post/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone',
+		'id' => '822057428507049984',
+		'oembedEndpoint' => 'https://www.tumblr.com/oembed/1.0?url=https%3A%2F%2Fstaff.tumblr.com%2Fpost%2F822057428507049984%2Fin-case-youre-looking-for-a-blog-thats-gone',
+	],
 ];
diff --git a/tests/MediaEmbedTest.php b/tests/MediaEmbedTest.php
index 329e6e2..dde6f59 100644
--- a/tests/MediaEmbedTest.php
+++ b/tests/MediaEmbedTest.php
@@ -33,6 +33,8 @@ class MediaEmbedTest extends TestCase {
 		'https://www.facebook.com/diginights.HN/videos/1231155290281511/' => '1231155290281511',
 		'https://www.facebook.com/SkySports/videos/vb.10911153761/10153310275743762/?type=2&theater' => '10153310275743762',
 		'https://www.facebook.com/demotivateurFood/videos/vl.184872862011827/1034411179983244/?type=1' => '1034411179983244',
+		'https://staff.tumblr.com/post/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone' => '822057428507049984',
+		'https://www.tumblr.com/staff/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone' => '822057428507049984',
 		'http://vimeo.com/19570639' => '19570639',
 		'http://vimeo.com/245928033/572c32a20d' => '245928033/572c32a20d',
 		'http://vimeo.com/channels/staffpicks/99585787' => '99585787',
@@ -576,6 +578,32 @@ public function get(string $url, array $options = []): ?string {
 		$this->assertSame('https://i.vimeocdn.com/video/thumb.jpg', $MediaEmbed->thumbnail($Object));
 	}
 
+	public function testOEmbedHtmlSupportsCustomOEmbedOnlyProvider(): void {
+		$html = '<div class="provider-post">Embedded post</div><script src="https://rich.example.com/embed.js"></script>';
+		$httpClient = $this->createStub(HttpClientInterface::class);
+		$httpClient->method('get')->willReturn(json_encode([
+			'type' => 'rich',
+			'version' => '1.0',
+			'html' => $html,
+		]));
+		$MediaEmbed = new MediaEmbed([
+			'custom_providers' => [
+				[
+					'name' => 'RichProvider',
+					'website' => 'https://rich.example.com',
+					'url-match' => 'https://rich\\.example\\.com/posts/([0-9]+)',
+					'embed-width' => 540,
+					'embed-height' => 600,
+					'oembed' => 'https://rich.example.com/oembed',
+				],
+			],
+		], httpClient: $httpClient);
+
+		$Object = $MediaEmbed->parseUrl('https://rich.example.com/posts/123');
+		$this->assertInstanceOf(MediaObject::class, $Object);
+		$this->assertSame($html, $MediaEmbed->oEmbedHtml($Object));
+	}
+
 	public function testOEmbedReturnsNullWithoutRegisteredEndpoint(): void {
 		$MediaEmbed = new MediaEmbed();
 		$Object = $MediaEmbed->parseUrl('https://my.matterport.com/show/?m=Zh14WDtkjdC');
@@ -1114,7 +1142,7 @@ public function testGetHosts(): void {
 		$MediaEmbed = new MediaEmbed();
 
 		$hosts = $MediaEmbed->getHosts();
-		$this->assertCount(42, $hosts);
+		$this->assertCount(43, $hosts);
 
 		$hosts = $MediaEmbed->getHosts(['vimeo', 'youtube']);
 		$this->assertTrue(count($hosts) === 2);
@@ -1339,7 +1367,7 @@ public function testGetProviders(): void {
 		$MediaEmbed = new MediaEmbed();
 
 		$providers = $MediaEmbed->getProviders();
-		$this->assertCount(42, $providers);
+		$this->assertCount(43, $providers);
 		$this->assertTrue($providers->has('youtube'));
 		$this->assertTrue($providers->has('vimeo'));
 
@@ -1353,6 +1381,8 @@ public function testGetProviders(): void {
 		// Test collection methods
 		$withIframe = $providers->withIframeSupport();
 		$this->assertGreaterThan(0, count($withIframe));
+		$withOEmbed = $providers->withOEmbedSupport();
+		$this->assertTrue($withOEmbed->has('tumblr'));
 
 		$withThumbnail = $providers->withThumbnailSupport();
 		$this->assertGreaterThan(0, count($withThumbnail));
diff --git a/tests/Provider/ProviderConfigTest.php b/tests/Provider/ProviderConfigTest.php
index 4b6a6b0..d9d26b6 100644
--- a/tests/Provider/ProviderConfigTest.php
+++ b/tests/Provider/ProviderConfigTest.php
@@ -118,9 +118,9 @@ public function testFromArrayRejectsInvalidDimensionType(): void {
 		]);
 	}
 
-	public function testFromArrayRequiresIframePlayer(): void {
+	public function testFromArrayRequiresIframePlayerOrOEmbed(): void {
 		$this->expectException(ProviderConfigException::class);
-		$this->expectExceptionMessage('Provider configuration is missing required field: iframe-player');
+		$this->expectExceptionMessage('Provider configuration is missing required field: iframe-player or oembed');
 
 		ProviderConfig::fromArray([
 			'name' => 'NoIframeProvider',
@@ -131,6 +131,21 @@ public function testFromArrayRequiresIframePlayer(): void {
 		]);
 	}
 
+	public function testFromArrayAllowsOEmbedOnlyProvider(): void {
+		$config = ProviderConfig::fromArray([
+			'name' => 'RichProvider',
+			'website' => 'https://rich.example.com',
+			'url-match' => 'rich\\.example\\.com/posts/([0-9]+)',
+			'embed-width' => 540,
+			'embed-height' => 600,
+			'oembed' => 'https://rich.example.com/oembed',
+		]);
+
+		$this->assertFalse($config->hasIframeSupport());
+		$this->assertTrue($config->hasOEmbedSupport());
+		$this->assertSame('https://rich.example.com/oembed', $config->toArray()['oembed']);
+	}
+
 	public function testFromArrayPreservesExtraProviderMetadata(): void {
 		$data = [
 			'name' => 'ExtraProvider',
@@ -321,6 +336,19 @@ public function testHasIframeSupport(): void {
 		$this->assertFalse($withoutIframe->hasIframeSupport());
 	}
 
+	public function testHasOEmbedSupport(): void {
+		$config = new ProviderConfig(
+			name: 'Test',
+			website: 'https://test.com',
+			urlMatch: 'pattern',
+			embedWidth: 640,
+			embedHeight: 360,
+			oEmbed: 'https://test.com/oembed',
+		);
+
+		$this->assertTrue($config->hasOEmbedSupport());
+	}
+
 	public function testHasThumbnailSupport(): void {
 		$withThumb = new ProviderConfig(
 			name: 'Test',
diff --git a/tests/Provider/ProviderValidatorTest.php b/tests/Provider/ProviderValidatorTest.php
index f432101..0ff46ae 100644
--- a/tests/Provider/ProviderValidatorTest.php
+++ b/tests/Provider/ProviderValidatorTest.php
@@ -91,7 +91,22 @@ public function testValidateReportsNullRequiredField(): void {
 		$validator = new ProviderValidator();
 		$errors = $validator->validate($providers);
 
-		$this->assertContains('Broken: missing required field "iframe-player"', $errors);
+		$this->assertContains('Broken: missing required field "iframe-player" or "oembed"', $errors);
+	}
+
+	public function testValidateAcceptsOEmbedOnlyProvider(): void {
+		$providers = [
+			[
+				'name' => 'Rich',
+				'website' => 'https://rich.example.com',
+				'url-match' => 'rich\\.example\\.com/posts/([0-9]+)',
+				'embed-width' => 540,
+				'embed-height' => 600,
+				'oembed' => 'https://rich.example.com/oembed',
+			],
+		];
+
+		$this->assertSame([], (new ProviderValidator())->validate($providers));
 	}
 
 }
diff --git a/tests/ProviderFixtureTest.php b/tests/ProviderFixtureTest.php
index 5f59bb9..4540771 100644
--- a/tests/ProviderFixtureTest.php
+++ b/tests/ProviderFixtureTest.php
@@ -44,7 +44,12 @@ public function get(string $url, array $options = []): ?string {
 		$this->assertInstanceOf(MediaObject::class, $object);
 		$this->assertSame($fixture['slug'], $object->slug());
 		$this->assertSame($fixture['id'], $object->id());
-		$this->assertSame($fixture['embedSrc'], $object->getEmbedSrc());
+		if (isset($fixture['embedSrc'])) {
+			$this->assertSame($fixture['embedSrc'], $object->getEmbedSrc());
+		}
+		if (isset($fixture['oembedEndpoint'])) {
+			$this->assertSame($fixture['oembedEndpoint'], $object->oEmbedEndpoint());
+		}
 	}
 
 	public function testEveryBundledProviderHasReleaseFixture(): void {

From e6a9dee5688f0c6e30cf2a2fecce259301a2c075 Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:28:25 +0200
Subject: [PATCH 2/5] Harden empty oEmbed provider configuration

---
 src/Provider/ProviderConfig.php       | 10 ++++---
 tests/MediaEmbedTest.php              | 10 +++++++
 tests/Provider/ProviderConfigTest.php | 43 +++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/src/Provider/ProviderConfig.php b/src/Provider/ProviderConfig.php
index 13b5f22..5e2fe3e 100644
--- a/src/Provider/ProviderConfig.php
+++ b/src/Provider/ProviderConfig.php
@@ -89,6 +89,8 @@ public static function fromArray(array $data): self {
 		if (($iframePlayer === null || $iframePlayer === '') && ($oEmbed === null || $oEmbed === '')) {
 			throw ProviderConfigException::missingField('iframe-player or oembed', $data);
 		}
+		$iframePlayer = $iframePlayer === '' ? null : $iframePlayer;
+		$oEmbed = $oEmbed === '' ? null : $oEmbed;
 		if ($iframePlayer !== null && !is_string($iframePlayer)) {
 			throw ProviderConfigException::invalidField('iframe-player', $data['iframe-player'], 'string', $data);
 		}
@@ -187,10 +189,10 @@ public function toArray(): array {
 		if ($this->slug !== null) {
 			$array['slug'] = $this->slug;
 		}
-		if ($this->iframePlayer !== null) {
+		if ($this->hasIframeSupport()) {
 			$array['iframe-player'] = $this->iframePlayer;
 		}
-		if ($this->oEmbed !== null) {
+		if ($this->hasOEmbedSupport()) {
 			$array['oembed'] = $this->oEmbed;
 		}
 		if ($this->imageSrc !== null) {
@@ -234,7 +236,7 @@ public function getUrlMatchPatterns(): array {
 	 * @return bool
 	 */
 	public function hasIframeSupport(): bool {
-		return $this->iframePlayer !== null;
+		return $this->iframePlayer !== null && $this->iframePlayer !== '';
 	}
 
 	/**
@@ -243,7 +245,7 @@ public function hasIframeSupport(): bool {
 	 * @return bool
 	 */
 	public function hasOEmbedSupport(): bool {
-		return $this->oEmbed !== null;
+		return $this->oEmbed !== null && $this->oEmbed !== '';
 	}
 
 	/**
diff --git a/tests/MediaEmbedTest.php b/tests/MediaEmbedTest.php
index dde6f59..f6165c4 100644
--- a/tests/MediaEmbedTest.php
+++ b/tests/MediaEmbedTest.php
@@ -604,6 +604,16 @@ public function testOEmbedHtmlSupportsCustomOEmbedOnlyProvider(): void {
 		$this->assertSame($html, $MediaEmbed->oEmbedHtml($Object));
 	}
 
+	public function testOEmbedHtmlReturnsNullWithoutHtml(): void {
+		$httpClient = $this->createStub(HttpClientInterface::class);
+		$httpClient->method('get')->willReturn('{"type":"link","version":"1.0"}');
+		$MediaEmbed = new MediaEmbed(httpClient: $httpClient);
+		$Object = $MediaEmbed->parseUrl('https://vimeo.com/99585787');
+		$this->assertInstanceOf(MediaObject::class, $Object);
+
+		$this->assertNull($MediaEmbed->oEmbedHtml($Object));
+	}
+
 	public function testOEmbedReturnsNullWithoutRegisteredEndpoint(): void {
 		$MediaEmbed = new MediaEmbed();
 		$Object = $MediaEmbed->parseUrl('https://my.matterport.com/show/?m=Zh14WDtkjdC');
diff --git a/tests/Provider/ProviderConfigTest.php b/tests/Provider/ProviderConfigTest.php
index d9d26b6..e84348d 100644
--- a/tests/Provider/ProviderConfigTest.php
+++ b/tests/Provider/ProviderConfigTest.php
@@ -146,6 +146,35 @@ public function testFromArrayAllowsOEmbedOnlyProvider(): void {
 		$this->assertSame('https://rich.example.com/oembed', $config->toArray()['oembed']);
 	}
 
+	public function testFromArrayNormalizesUnusedEmptyRendererToNull(): void {
+		$config = ProviderConfig::fromArray([
+			'name' => 'IframeProvider',
+			'website' => 'https://iframe.example.com',
+			'url-match' => 'iframe\\.example\\.com/([0-9]+)',
+			'embed-width' => 640,
+			'embed-height' => 360,
+			'iframe-player' => 'https://iframe.example.com/embed/$2',
+			'oembed' => '',
+		]);
+
+		$this->assertNull($config->oEmbed);
+		$this->assertArrayNotHasKey('oembed', $config->toArray());
+	}
+
+	public function testFromArrayRejectsNonStringOEmbedEndpoint(): void {
+		$this->expectException(ProviderConfigException::class);
+		$this->expectExceptionMessage('Provider configuration field "oembed" has invalid value. Expected string.');
+
+		ProviderConfig::fromArray([
+			'name' => 'InvalidProvider',
+			'website' => 'https://invalid.example.com',
+			'url-match' => 'invalid\\.example\\.com/([0-9]+)',
+			'embed-width' => 640,
+			'embed-height' => 360,
+			'oembed' => [],
+		]);
+	}
+
 	public function testFromArrayPreservesExtraProviderMetadata(): void {
 		$data = [
 			'name' => 'ExtraProvider',
@@ -347,6 +376,20 @@ public function testHasOEmbedSupport(): void {
 		);
 
 		$this->assertTrue($config->hasOEmbedSupport());
+
+		$empty = new ProviderConfig(
+			name: 'Empty',
+			website: 'https://empty.example.com',
+			urlMatch: 'pattern',
+			embedWidth: 640,
+			embedHeight: 360,
+			iframePlayer: '',
+			oEmbed: '',
+		);
+		$this->assertFalse($empty->hasIframeSupport());
+		$this->assertFalse($empty->hasOEmbedSupport());
+		$this->assertArrayNotHasKey('iframe-player', $empty->toArray());
+		$this->assertArrayNotHasKey('oembed', $empty->toArray());
 	}
 
 	public function testHasThumbnailSupport(): void {

From cc60a237a6d122be5c8a2a4c356b630be522fe35 Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:32:10 +0200
Subject: [PATCH 3/5] Add oEmbed providers for rich media

---
 data/stubs.php                  | 39 +++++++++++++++++++++++++++++++++
 docs/supported.md               |  5 ++++-
 tests/Fixture/provider_urls.php | 18 +++++++++++++++
 tests/MediaEmbedTest.php        |  7 ++++--
 4 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/data/stubs.php b/data/stubs.php
index eaa577a..cd4cc3e 100644
--- a/data/stubs.php
+++ b/data/stubs.php
@@ -77,6 +77,45 @@
 		'oembed' => 'https://www.tumblr.com/oembed/1.0',
 		'notes' => 'Uses oEmbed HTML because Tumblr post embeds require provider-generated markup.',
 	],
+	[
+		'name' => 'Bluesky',
+		'website' => 'https://bsky.app',
+		'status' => 'active',
+		'category' => 'social',
+		'example-url' => 'https://bsky.app/profile/bsky.app/post/3mbhel6ij7s2y',
+		'url-match' => 'https://bsky\\.app/profile/([^/?#]+)/post/([^/?#]+)',
+		'embed-width' => 600,
+		'embed-height' => 600,
+		'oembed' => 'https://embed.bsky.app/oembed',
+		'id' => '$2/$3',
+		'notes' => 'Uses provider-generated oEmbed HTML for social posts.',
+	],
+	[
+		'name' => 'Flickr',
+		'website' => 'https://www.flickr.com',
+		'status' => 'active',
+		'category' => 'social',
+		'example-url' => 'https://www.flickr.com/photos/bees/2341623661/',
+		'url-match' => 'https?://(?:www\\.)?flickr\\.com/photos/([^/?#]+)/([0-9]+)(?:/[^?#]*)?',
+		'embed-width' => 1024,
+		'embed-height' => 768,
+		'oembed' => 'https://www.flickr.com/services/oembed/',
+		'id' => '$2/$3',
+		'notes' => 'Supports provider-generated oEmbed markup for photos and videos.',
+	],
+	[
+		'name' => 'Speaker Deck',
+		'website' => 'https://speakerdeck.com',
+		'status' => 'active',
+		'category' => 'social',
+		'example-url' => 'https://speakerdeck.com/speakerdeck/introduction-to-speakerdeck',
+		'url-match' => 'https?://speakerdeck\\.com/([^/?#]+)/([^/?#]+)',
+		'embed-width' => 710,
+		'embed-height' => 399,
+		'oembed' => 'https://speakerdeck.com/oembed.json',
+		'id' => '$2/$3',
+		'notes' => 'Uses provider-generated oEmbed HTML for presentations.',
+	],
 	[
 		'name' => 'Dailymotion',
 		'website' => 'https://www.dailymotion.com',
diff --git a/docs/supported.md b/docs/supported.md
index da86958..e2d4f77 100644
--- a/docs/supported.md
+++ b/docs/supported.md
@@ -1,6 +1,6 @@
 # Supported Media Services
 
-43 services (42 active, 1 legacy)
+46 services (45 active, 1 legacy)
 
 Provider example URLs are covered by the release fixture matrix in `tests/Fixture/provider_urls.php`.
 
@@ -14,10 +14,12 @@ Provider example URLs are covered by the release fixture matrix in `tests/Fixtur
 | [Bilibili](https://www.bilibili.com) | active | video | iframe |  |
 | [Bilibili (Legacy)](https://www.bilibili.com) | legacy | video | iframe | Legacy URL format kept for existing links. |
 | [BitChute](https://www.bitchute.com) | active | video | iframe |  |
+| [Bluesky](https://bsky.app) | active | social | oEmbed | Uses provider-generated oEmbed HTML for social posts. |
 | [Coub](https://coub.com) | active | video | iframe |  |
 | [Dailymotion](https://www.dailymotion.com) | active | video | iframe, thumbnail |  |
 | [Deezer](https://www.deezer.com) | active | audio | iframe | Music content only (track, album, playlist, artist); podcasts are not supported. |
 | [Facebook](https://www.facebook.com) | active | social | iframe |  |
+| [Flickr](https://www.flickr.com) | active | social | oEmbed | Supports provider-generated oEmbed markup for photos and videos. |
 | [Giphy](https://giphy.com) | active | video | iframe, thumbnail |  |
 | [Instagram](https://www.instagram.com) | active | social | iframe |  |
 | [Kick](https://kick.com) | active | streaming | iframe |  |
@@ -36,6 +38,7 @@ Provider example URLs are covered by the release fixture matrix in `tests/Fixtur
 | [Screencast](https://www.screencast.com) | active | video | iframe, fetch |  |
 | [Sketchfab](https://sketchfab.com) | active | 3d | iframe, oEmbed |  |
 | [SoundCloud](https://soundcloud.com) | active | audio | iframe, oEmbed |  |
+| [Speaker Deck](https://speakerdeck.com) | active | social | oEmbed | Uses provider-generated oEmbed HTML for presentations. |
 | [Spotify](https://open.spotify.com) | active | audio | iframe, oEmbed |  |
 | [Spreaker](https://www.spreaker.com) | active | audio | iframe, oEmbed | Episode URLs only; show pages expose no numeric ID in the URL. |
 | [Streamable](https://streamable.com) | active | video | iframe |  |
diff --git a/tests/Fixture/provider_urls.php b/tests/Fixture/provider_urls.php
index 25c5edd..d155017 100644
--- a/tests/Fixture/provider_urls.php
+++ b/tests/Fixture/provider_urls.php
@@ -262,4 +262,22 @@
 		'id' => '822057428507049984',
 		'oembedEndpoint' => 'https://www.tumblr.com/oembed/1.0?url=https%3A%2F%2Fstaff.tumblr.com%2Fpost%2F822057428507049984%2Fin-case-youre-looking-for-a-blog-thats-gone',
 	],
+	[
+		'slug' => 'bluesky',
+		'url' => 'https://bsky.app/profile/bsky.app/post/3mbhel6ij7s2y',
+		'id' => 'bsky.app/3mbhel6ij7s2y',
+		'oembedEndpoint' => 'https://embed.bsky.app/oembed?url=https%3A%2F%2Fbsky.app%2Fprofile%2Fbsky.app%2Fpost%2F3mbhel6ij7s2y',
+	],
+	[
+		'slug' => 'flickr',
+		'url' => 'https://www.flickr.com/photos/bees/2341623661/',
+		'id' => 'bees/2341623661',
+		'oembedEndpoint' => 'https://www.flickr.com/services/oembed/?url=https%3A%2F%2Fwww.flickr.com%2Fphotos%2Fbees%2F2341623661%2F',
+	],
+	[
+		'slug' => 'speaker-deck',
+		'url' => 'https://speakerdeck.com/speakerdeck/introduction-to-speakerdeck',
+		'id' => 'speakerdeck/introduction-to-speakerdeck',
+		'oembedEndpoint' => 'https://speakerdeck.com/oembed.json?url=https%3A%2F%2Fspeakerdeck.com%2Fspeakerdeck%2Fintroduction-to-speakerdeck',
+	],
 ];
diff --git a/tests/MediaEmbedTest.php b/tests/MediaEmbedTest.php
index f6165c4..3a1f4aa 100644
--- a/tests/MediaEmbedTest.php
+++ b/tests/MediaEmbedTest.php
@@ -35,6 +35,9 @@ class MediaEmbedTest extends TestCase {
 		'https://www.facebook.com/demotivateurFood/videos/vl.184872862011827/1034411179983244/?type=1' => '1034411179983244',
 		'https://staff.tumblr.com/post/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone' => '822057428507049984',
 		'https://www.tumblr.com/staff/822057428507049984/in-case-youre-looking-for-a-blog-thats-gone' => '822057428507049984',
+		'https://bsky.app/profile/bsky.app/post/3mbhel6ij7s2y' => 'bsky.app/3mbhel6ij7s2y',
+		'https://www.flickr.com/photos/bees/2341623661/' => 'bees/2341623661',
+		'https://speakerdeck.com/speakerdeck/introduction-to-speakerdeck' => 'speakerdeck/introduction-to-speakerdeck',
 		'http://vimeo.com/19570639' => '19570639',
 		'http://vimeo.com/245928033/572c32a20d' => '245928033/572c32a20d',
 		'http://vimeo.com/channels/staffpicks/99585787' => '99585787',
@@ -1152,7 +1155,7 @@ public function testGetHosts(): void {
 		$MediaEmbed = new MediaEmbed();
 
 		$hosts = $MediaEmbed->getHosts();
-		$this->assertCount(43, $hosts);
+		$this->assertCount(46, $hosts);
 
 		$hosts = $MediaEmbed->getHosts(['vimeo', 'youtube']);
 		$this->assertTrue(count($hosts) === 2);
@@ -1377,7 +1380,7 @@ public function testGetProviders(): void {
 		$MediaEmbed = new MediaEmbed();
 
 		$providers = $MediaEmbed->getProviders();
-		$this->assertCount(43, $providers);
+		$this->assertCount(46, $providers);
 		$this->assertTrue($providers->has('youtube'));
 		$this->assertTrue($providers->has('vimeo'));
 

From 125bb7f05bfd5c0c6ffdfd9df62fc35c1d206ad3 Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:38:44 +0200
Subject: [PATCH 4/5] Guard iframe rendering for oEmbed-only providers

---
 docs/README.md                                |  2 ++
 .../EmbedCodeUnavailableException.php         | 22 +++++++++++++++++++
 src/Object/MediaObject.php                    |  4 ++++
 tests/MediaEmbedTest.php                      | 11 ++++++++++
 tests/ProviderFixtureTest.php                 |  4 ++++
 5 files changed, 43 insertions(+)
 create mode 100644 src/Exception/EmbedCodeUnavailableException.php

diff --git a/docs/README.md b/docs/README.md
index 2bb20b3..f67ddbe 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -610,6 +610,8 @@ $html = $mediaEmbed->oEmbedHtml($mediaObject);
 echo $html;
 ```
 
+Calling the iframe-specific `MediaObject::getEmbedCode()` or `getEmbedSrc()` methods for an oEmbed-only provider throws `EmbedCodeUnavailableException` with this alternative. This avoids silently returning unusable markup.
+
 Custom oEmbed-only providers can be registered inline without modifying the bundled provider file:
 
 ```php
diff --git a/src/Exception/EmbedCodeUnavailableException.php b/src/Exception/EmbedCodeUnavailableException.php
new file mode 100644
index 0000000..7c4ad97
--- /dev/null
+++ b/src/Exception/EmbedCodeUnavailableException.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MediaEmbed\Exception;
+
+/**
+ * Exception thrown when a provider has no static iframe renderer.
+ */
+class EmbedCodeUnavailableException extends MediaEmbedException {
+
+	/**
+	 * @param string $providerSlug Provider slug.
+	 */
+	public function __construct(string $providerSlug) {
+		parent::__construct(sprintf(
+			'Provider "%s" has no iframe embed. Use MediaEmbed::oEmbedHtml() for oEmbed-only providers.',
+			$providerSlug,
+		));
+	}
+
+}
diff --git a/src/Object/MediaObject.php b/src/Object/MediaObject.php
index d858d03..42b2690 100644
--- a/src/Object/MediaObject.php
+++ b/src/Object/MediaObject.php
@@ -5,6 +5,7 @@
 namespace MediaEmbed\Object;
 
 use InvalidArgumentException;
+use MediaEmbed\Exception\EmbedCodeUnavailableException;
 use MediaEmbed\Template\TemplateResolver;
 
 /**
@@ -549,6 +550,9 @@ public function isSourceResolved(): bool {
 	 * @return string The unescaped src URL
 	 */
 	public function getEmbedSrc(): string {
+		if (empty($this->stub['iframe-player'])) {
+			throw new EmbedCodeUnavailableException($this->slug());
+		}
 		$source = $this->templateResolver->resolve($this->stub['iframe-player'], $this->match);
 
 		return $this->appendQueryParams($source);
diff --git a/tests/MediaEmbedTest.php b/tests/MediaEmbedTest.php
index 3a1f4aa..a4a8d91 100644
--- a/tests/MediaEmbedTest.php
+++ b/tests/MediaEmbedTest.php
@@ -3,6 +3,7 @@
 namespace MediaEmbed\Test;
 
 use InvalidArgumentException;
+use MediaEmbed\Exception\EmbedCodeUnavailableException;
 use MediaEmbed\Exception\InvalidUrlException;
 use MediaEmbed\Exception\ProviderConfigException;
 use MediaEmbed\Http\HttpClientInterface;
@@ -617,6 +618,16 @@ public function testOEmbedHtmlReturnsNullWithoutHtml(): void {
 		$this->assertNull($MediaEmbed->oEmbedHtml($Object));
 	}
 
+	public function testOEmbedOnlyProviderRejectsIframeRenderingWithActionableException(): void {
+		$MediaEmbed = new MediaEmbed();
+		$Object = $MediaEmbed->parseUrl('https://bsky.app/profile/bsky.app/post/3mbhel6ij7s2y');
+		$this->assertInstanceOf(MediaObject::class, $Object);
+
+		$this->expectException(EmbedCodeUnavailableException::class);
+		$this->expectExceptionMessage('Use MediaEmbed::oEmbedHtml()');
+		$Object->getEmbedCode();
+	}
+
 	public function testOEmbedReturnsNullWithoutRegisteredEndpoint(): void {
 		$MediaEmbed = new MediaEmbed();
 		$Object = $MediaEmbed->parseUrl('https://my.matterport.com/show/?m=Zh14WDtkjdC');
diff --git a/tests/ProviderFixtureTest.php b/tests/ProviderFixtureTest.php
index 4540771..f389c79 100644
--- a/tests/ProviderFixtureTest.php
+++ b/tests/ProviderFixtureTest.php
@@ -44,6 +44,10 @@ public function get(string $url, array $options = []): ?string {
 		$this->assertInstanceOf(MediaObject::class, $object);
 		$this->assertSame($fixture['slug'], $object->slug());
 		$this->assertSame($fixture['id'], $object->id());
+		$this->assertTrue(
+			isset($fixture['embedSrc']) || isset($fixture['oembedEndpoint']),
+			'Provider fixtures must verify an iframe source or oEmbed endpoint.',
+		);
 		if (isset($fixture['embedSrc'])) {
 			$this->assertSame($fixture['embedSrc'], $object->getEmbedSrc());
 		}

From fa891e36166e053505ff09f66672aa31b9d27440 Mon Sep 17 00:00:00 2001
From: Mark Scherer <dereuromark@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:41:02 +0200
Subject: [PATCH 5/5] Document oEmbed provider rendering

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 54e4738..728e4a5 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ It currently works with [40+ services](docs/supported.md), including the most im
 
 etc. With community driven updates this aims to be a complete and up-to-date service wrapper lib.
 
-All providers use modern iframe embeds (Flash support was removed as Flash was discontinued in 2020).
+Providers use modern iframe embeds or provider-generated oEmbed HTML (Flash support was removed as Flash was discontinued in 2020).
 
 ## Demo
 https://sandbox.dereuromark.de/sandbox/media-embed