Guard iframe rendering for oEmbed-only providers

Author: dereuromark

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

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,
+		));
+	}
+
+}

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);

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');

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());
 		}