Skip to content
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

## [4.7.0] - 2026-11-20
### Added
- YouTube: `$info->image` is `maxresdefault.jpg` when the video page links it in `og:image`, instead of the oEmbed `hqdefault.jpg` with black bars [#535]
- YouTube: the start (`t=` or `start=`) and end (`end=`) times of the URL are kept in the player URL, in seconds or in the `1m30s` format [#268]
- Vimeo adapter: `$info->image` is the full size thumbnail instead of the one resized to the player width (like `_295x166`) [#391]
- Google Drive adapter: shared files (`drive.google.com/file/d/<id>/view` and `drive.google.com/open?id=<id>`) get the `/preview` iframe of Drive's "Embed item" option. Files that need a login get no code [#408]
- Tencent Video adapter: `v.qq.com/x/cover/<cid>/<vid>.html`, `v.qq.com/x/page/<vid>.html` and `v.qq.com/x/cover/<cid>.html?vid=<vid>` URLs get a `v.qq.com/txp/iframe/player.html` iframe built from the URL [#243]
- README section about the results that are specific to some sites, and how to get `null` instead of the provider name fallback [#462]

### Changed
- The provider name is also read from the `application-name` and `apple-mobile-web-app-title` metas before falling back to the domain name, and the fallback skips `www` (`www.gov.pt` was "Www") [#462]

## [4.6.3] - 2026-11-20
### Fixed
- A `Referer` header set by the caller (for example with `addDefaultHeaders()`) is kept when a request follows redirects, instead of being replaced by the previous URL. Vimeo videos with domain-level privacy need it to return their title, thumbnail and other metadata [#377] [#567]
Expand Down Expand Up @@ -385,7 +397,13 @@ Full library refactoring.
[#567]: https://github.com/php-embed/Embed/issues/567
[#574]: https://github.com/oscarotero/Embed/issues/574
[#577]: https://github.com/oscarotero/Embed/issues/577
[#268]: https://github.com/php-embed/Embed/issues/268
[#391]: https://github.com/php-embed/Embed/issues/391
[#408]: https://github.com/php-embed/Embed/issues/408
[#462]: https://github.com/php-embed/Embed/issues/462
[#535]: https://github.com/php-embed/Embed/issues/535

[4.7.0]: https://github.com/php-embed/Embed/compare/v4.6.3...v4.7.0
[4.6.3]: https://github.com/php-embed/Embed/compare/v4.6.2...v4.6.3
[4.6.2]: https://github.com/php-embed/Embed/compare/v4.6.1...v4.6.2
[4.6.1]: https://github.com/php-embed/Embed/compare/v4.6.0...v4.6.1
Expand Down
30 changes: 30 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,36 @@ foreach ($infos as $info) {
}
```

## Site-specific results

Some sites get extra handling from their adapters:

- **YouTube**: `$info->image` is `maxresdefault.jpg` when the video page links it in `og:image` (YouTube only does it for videos that have it), and the oEmbed `hqdefault.jpg` otherwise. The start (`t=` or `start=`) and end (`end=`) times of the URL are kept in the player URL, in seconds or in the `1m30s` format, for example `https://www.youtube.com/watch?v=ID&t=10&end=20`.
- **Vimeo**: `$info->image` is the thumbnail at its full size, without the size suffix that the oEmbed `thumbnail_url` has (like `_295x166`). The resized one is still available with `$info->getOEmbed()->url('thumbnail_url')`.
- **Google Drive**: shared files (`drive.google.com/file/d/<id>/view` or `drive.google.com/open?id=<id>`) get the same `/preview` iframe as Drive's "Embed item" option. Files that need a login return no code.
- **Bilibili, Youku and Tencent Video**: the player iframe is built from the video URL (`bilibili.com/video/BV...`, `v.youku.com/v_show/id_<ID>.html`, `v.qq.com/x/cover/<cid>/<vid>.html` or `v.qq.com/x/page/<vid>.html`). Tencent Video pages are rendered with JavaScript, so their title and image are often missing.
- **NetEase Music**: songs, albums and playlists get the `music.163.com/outchain/player` iframe.

`$info->providerName` is read from the oEmbed `provider_name`, the `og:site_name`, `publisher` and similar metas, and then `application-name` or `apple-mobile-web-app-title`. When none of them is found, it falls back to the capitalized domain name (`Example` for `www.example.com`). To get `null` instead of that fallback, replace the detector:

```php
use Embed\Detectors\Detector;

class StrictProviderName extends Detector
{
public function detect(): ?string
{
$oembed = $this->extractor->getOEmbed();
$metas = $this->extractor->getMetas();

return $oembed->str('provider_name')
?? $metas->str('og:site_name', 'publisher', 'application-name', 'apple-mobile-web-app-title');
}
}

$embed->getExtractorFactory()->addDetector('providerName', StrictProviderName::class);
```

## Document

The document is the object that store the html code of the page. You can use it to extract extra info from the html code:
Expand Down
47 changes: 47 additions & 0 deletions src/Adapters/GoogleDrive/Detectors/Code.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\GoogleDrive\Detectors;

use Embed\Adapters\GoogleDrive\Extractor;
use Embed\Detectors\Code as Detector;
use Embed\EmbedCode;
use function Embed\html;

/**
* @extends Detector<\Embed\Adapters\GoogleDrive\Extractor>
*/
class Code extends Detector
{
public function detect(): ?EmbedCode
{
$result = parent::detect();

if ($result !== null) {
return $result;
}

// Private or deleted files answer with an error status,
// there is nothing to embed for them.
if ($this->extractor->getResponse()->getStatusCode() >= 400) {
return null;
}

$id = Extractor::parseFileId($this->extractor->getUri())
?? Extractor::parseFileId($this->extractor->getRequest()->getUri());

if ($id === null) {
return null;
}

// Same iframe as Drive's "Embed item" option.
return new EmbedCode(html('iframe', [
'src' => 'https://drive.google.com/file/d/'.rawurlencode($id).'/preview',
'width' => 640,
'height' => 480,
'allow' => 'autoplay',
'frameborder' => 0,
'allowfullscreen' => 'true',
]), 640, 480);
}
}
44 changes: 44 additions & 0 deletions src/Adapters/GoogleDrive/Extractor.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\GoogleDrive;

use Embed\Extractor as Base;
use Psr\Http\Message\UriInterface;

/**
* @template-extends Base<\Embed\Detectors\Detector<self>>
*/
class Extractor extends Base
{
public function createCustomDetectors(): array
{
return [
'code' => new Detectors\Code($this),
];
}

/**
* Returns the file id of drive.google.com/file/d/<id>/view (also /edit,
* /preview and /u/<n>/ variants) and drive.google.com/open?id=<id> URLs.
*/
public static function parseFileId(UriInterface $uri): ?string
{
if (preg_match('#^/file(?:/u/\d+)?/d/([A-Za-z0-9_-]{10,})(?:/|$)#', $uri->getPath(), $matches) === 1) {
return $matches[1];
}

if ($uri->getPath() !== '/open') {
return null;
}

parse_str($uri->getQuery(), $query);
$id = $query['id'] ?? null;

if (is_string($id) && preg_match('/^[A-Za-z0-9_-]{10,}$/', $id) === 1) {
return $id;
}

return null;
}
}
34 changes: 34 additions & 0 deletions src/Adapters/TencentVideo/Detectors/Code.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\TencentVideo\Detectors;

use Embed\Adapters\TencentVideo\Extractor;
use Embed\Detectors\Code as Detector;
use Embed\EmbedCode;
use function Embed\html;

/**
* @extends Detector<\Embed\Adapters\TencentVideo\Extractor>
*/
class Code extends Detector
{
public function detect(): ?EmbedCode
{
$vid = Extractor::parseVideoId($this->extractor->getUri());

if ($vid === null) {
return parent::detect();
}

// Same player as Tencent Video's share code.
return new EmbedCode(html('iframe', [
'src' => 'https://v.qq.com/txp/iframe/player.html?vid='.rawurlencode($vid),
'frameborder' => 0,
'allowfullscreen' => 'true',
'scrolling' => 'no',
'width' => 640,
'height' => 360,
]), 640, 360);
}
}
45 changes: 45 additions & 0 deletions src/Adapters/TencentVideo/Extractor.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\TencentVideo;

use Embed\Extractor as Base;
use Psr\Http\Message\UriInterface;

/**
* @template-extends Base<\Embed\Detectors\Detector<self>>
*/
class Extractor extends Base
{
public function createCustomDetectors(): array
{
return [
'code' => new Detectors\Code($this),
];
}

/**
* Returns the video id (vid) of v.qq.com/x/cover/<cid>/<vid>.html,
* v.qq.com/x/page/<vid>.html and v.qq.com/x/cover/<cid>.html?vid=<vid> URLs.
* Cover URLs without a vid point to a series, not to one video.
*/
public static function parseVideoId(UriInterface $uri): ?string
{
if (preg_match('#^/x/(?:cover/[0-9a-z]+|page)/([0-9a-z]{11})\.html$#i', $uri->getPath(), $matches) === 1) {
return $matches[1];
}

if (preg_match('#^/x/cover/[0-9a-z]+\.html$#i', $uri->getPath()) !== 1) {
return null;
}

parse_str($uri->getQuery(), $query);
$vid = $query['vid'] ?? null;

if (is_string($vid) && preg_match('/^[0-9a-z]{11}$/i', $vid) === 1) {
return $vid;
}

return null;
}
}
38 changes: 38 additions & 0 deletions src/Adapters/Vimeo/Detectors/Image.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\Vimeo\Detectors;

use Embed\Detectors\Image as Detector;
use Psr\Http\Message\UriInterface;

/**
* @extends Detector<\Embed\Adapters\Vimeo\Extractor>
*/
class Image extends Detector
{
public function detect(): ?UriInterface
{
$image = parent::detect();

if ($image === null || $image->getHost() !== 'i.vimeocdn.com') {
return $image;
}

return self::fullSize($image);
}

/**
* Vimeo's oEmbed thumbnail is resized to the player width
* (like .../video/123-abc-d_295x166). Without the size suffix,
* Vimeo's CDN serves the image at its full size.
*/
public static function fullSize(UriInterface $image): UriInterface
{
if (preg_match('#^(/video/[^/_]+)_\d+(?:x\d+)?(\.[a-z]+)?$#i', $image->getPath(), $matches) !== 1) {
return $image;
}

return $image->withPath($matches[1].($matches[2] ?? ''));
}
}
19 changes: 19 additions & 0 deletions src/Adapters/Vimeo/Extractor.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php
declare(strict_types = 1);

namespace Embed\Adapters\Vimeo;

use Embed\Extractor as Base;

/**
* @template-extends Base<\Embed\Detectors\Detector<self>>
*/
class Extractor extends Base
{
public function createCustomDetectors(): array
{
return [
'image' => new Detectors\Image($this),
];
}
}
Loading