Resource.php
Same filename in other branches
Namespace
Drupal\media\OEmbedFile
-
core/
modules/ media/ src/ OEmbed/ Resource.php
View source
<?php
namespace Drupal\media\OEmbed;
use Drupal\Core\Cache\Cache;
use Drupal\Core\Cache\CacheableDependencyInterface;
use Drupal\Core\Cache\CacheableDependencyTrait;
use Drupal\Core\Url;
/**
* Value object representing an oEmbed resource.
*
* Data received from an oEmbed provider could be insecure. For example,
* resources of the 'rich' type provide an HTML representation which is not
* sanitized by this object in any way. Any values you retrieve from this object
* should be treated as potentially dangerous user input and carefully validated
* and sanitized before being displayed or otherwise manipulated by your code.
*
* Valid resource types are defined in the oEmbed specification and represented
* by the TYPE_* constants in this class.
*
* @see https://oembed.com/#section2
*
* @internal
* This class is an internal part of the oEmbed system and should only be
* instantiated by
* \Drupal\media\OEmbed\ResourceFetcherInterface::fetchResource().
*/
class Resource implements CacheableDependencyInterface {
use CacheableDependencyTrait;
/**
* The resource type for link resources.
*/
const TYPE_LINK = 'link';
/**
* The resource type for photo resources.
*/
const TYPE_PHOTO = 'photo';
/**
* The resource type for rich resources.
*/
const TYPE_RICH = 'rich';
/**
* The resource type for video resources.
*/
const TYPE_VIDEO = 'video';
/**
* The resource type. Can be one of the static::TYPE_* constants.
*
* @var string
*/
protected $type;
/**
* The resource provider.
*
* @var \Drupal\media\OEmbed\Provider
*/
protected $provider;
/**
* A text title, describing the resource.
*
* @var string
*/
protected $title;
/**
* The name of the author/owner of the resource.
*
* @var string
*/
protected $authorName;
/**
* A URL for the author/owner of the resource.
*
* @var string
*/
protected $authorUrl;
/**
* A URL to a thumbnail image representing the resource.
*
* The thumbnail must respect any maxwidth and maxheight parameters passed
* to the oEmbed endpoint. If this parameter is present, thumbnail_width and
* thumbnail_height must also be present.
*
* @var string
*
* @see \Drupal\media\OEmbed\UrlResolverInterface::getResourceUrl()
* @see https://oembed.com/#section2
*/
protected $thumbnailUrl;
/**
* The width of the thumbnail, in pixels.
*
* If this parameter is present, thumbnail_url and thumbnail_height must also
* be present.
*
* @var int
*/
protected $thumbnailWidth;
/**
* The height of the thumbnail, in pixels.
*
* If this parameter is present, thumbnail_url and thumbnail_width must also
* be present.
*
* @var int
*/
protected $thumbnailHeight;
/**
* The width of the resource, in pixels.
*
* @var int
*/
protected $width;
/**
* The height of the resource, in pixels.
*
* @var int
*/
protected $height;
/**
* The resource URL. Only applies to 'photo' and 'link' resources.
*
* @var string
*/
protected $url;
/**
* The HTML representation of the resource.
*
* Only applies to 'rich' and 'video' resources.
*
* @var string
*/
protected $html;
/**
* Resource constructor.
*
* @param \Drupal\media\OEmbed\Provider $provider
* (optional) The resource provider.
* @param string $title
* (optional) A text title, describing the resource.
* @param string $author_name
* (optional) The name of the author/owner of the resource.
* @param string $author_url
* (optional) A URL for the author/owner of the resource.
* @param int $cache_age
* (optional) The suggested cache lifetime for this resource, in seconds.
* @param string $thumbnail_url
* (optional) A URL to a thumbnail image representing the resource. If this
* parameter is present, $thumbnail_width and $thumbnail_height must also be
* present.
* @param int $thumbnail_width
* (optional) The width of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_height must also be present.
* @param int $thumbnail_height
* (optional) The height of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_width must also be present.
*/
protected function __construct(Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
$this->provider = $provider;
$this->title = $title;
$this->authorName = $author_name;
$this->authorUrl = $author_url;
if (isset($cache_age) && is_numeric($cache_age)) {
// If the cache age is too big, it can overflow the 'expire' column of
// database cache backends, causing SQL exceptions. To prevent that,
// arbitrarily limit the cache age to 5 years. That should be enough.
$this->cacheMaxAge = Cache::mergeMaxAges((int) $cache_age, 157680000);
}
if ($thumbnail_url) {
$this->thumbnailUrl = $thumbnail_url;
$this->setThumbnailDimensions($thumbnail_width, $thumbnail_height);
}
}
/**
* Creates a link resource.
*
* @param string $url
* (optional) The URL of the resource.
* @param \Drupal\media\OEmbed\Provider $provider
* (optional) The resource provider.
* @param string $title
* (optional) A text title, describing the resource.
* @param string $author_name
* (optional) The name of the author/owner of the resource.
* @param string $author_url
* (optional) A URL for the author/owner of the resource.
* @param int $cache_age
* (optional) The suggested cache lifetime for this resource, in seconds.
* @param string $thumbnail_url
* (optional) A URL to a thumbnail image representing the resource. If this
* parameter is present, $thumbnail_width and $thumbnail_height must also be
* present.
* @param int $thumbnail_width
* (optional) The width of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_height must also be present.
* @param int $thumbnail_height
* (optional) The height of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_width must also be present.
*
* @return static
*/
public static function link($url = NULL, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
$resource = new static($provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
$resource->type = self::TYPE_LINK;
$resource->url = $url;
return $resource;
}
/**
* Creates a photo resource.
*
* @param string $url
* The URL of the photo.
* @param int $width
* The width of the photo, in pixels.
* @param int $height
* The height of the photo, in pixels.
* @param \Drupal\media\OEmbed\Provider $provider
* (optional) The resource provider.
* @param string $title
* (optional) A text title, describing the resource.
* @param string $author_name
* (optional) The name of the author/owner of the resource.
* @param string $author_url
* (optional) A URL for the author/owner of the resource.
* @param int $cache_age
* (optional) The suggested cache lifetime for this resource, in seconds.
* @param string $thumbnail_url
* (optional) A URL to a thumbnail image representing the resource. If this
* parameter is present, $thumbnail_width and $thumbnail_height must also be
* present.
* @param int $thumbnail_width
* (optional) The width of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_height must also be present.
* @param int $thumbnail_height
* (optional) The height of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_width must also be present.
*
* @return static
*/
public static function photo($url, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
if (empty($url)) {
throw new \InvalidArgumentException('Photo resources must provide a URL.');
}
$resource = static::link($url, $provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
$resource->type = self::TYPE_PHOTO;
$resource->setDimensions($width, $height);
return $resource;
}
/**
* Creates a rich resource.
*
* @param string $html
* The HTML representation of the resource.
* @param int $width
* The width of the resource, in pixels.
* @param int $height
* The height of the resource, in pixels.
* @param \Drupal\media\OEmbed\Provider $provider
* (optional) The resource provider.
* @param string $title
* (optional) A text title, describing the resource.
* @param string $author_name
* (optional) The name of the author/owner of the resource.
* @param string $author_url
* (optional) A URL for the author/owner of the resource.
* @param int $cache_age
* (optional) The suggested cache lifetime for this resource, in seconds.
* @param string $thumbnail_url
* (optional) A URL to a thumbnail image representing the resource. If this
* parameter is present, $thumbnail_width and $thumbnail_height must also be
* present.
* @param int $thumbnail_width
* (optional) The width of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_height must also be present.
* @param int $thumbnail_height
* (optional) The height of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_width must also be present.
*
* @return static
*/
public static function rich($html, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
if (empty($html)) {
throw new \InvalidArgumentException('The resource must provide an HTML representation.');
}
$resource = new static($provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
$resource->type = self::TYPE_RICH;
$resource->html = $html;
$resource->setDimensions($width, $height);
return $resource;
}
/**
* Creates a video resource.
*
* @param string $html
* The HTML required to display the video.
* @param int $width
* The width of the video, in pixels.
* @param int $height
* The height of the video, in pixels.
* @param \Drupal\media\OEmbed\Provider $provider
* (optional) The resource provider.
* @param string $title
* (optional) A text title, describing the resource.
* @param string $author_name
* (optional) The name of the author/owner of the resource.
* @param string $author_url
* (optional) A URL for the author/owner of the resource.
* @param int $cache_age
* (optional) The suggested cache lifetime for this resource, in seconds.
* @param string $thumbnail_url
* (optional) A URL to a thumbnail image representing the resource. If this
* parameter is present, $thumbnail_width and $thumbnail_height must also be
* present.
* @param int $thumbnail_width
* (optional) The width of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_height must also be present.
* @param int $thumbnail_height
* (optional) The height of the thumbnail, in pixels. If this parameter is
* present, $thumbnail_url and $thumbnail_width must also be present.
*
* @return static
*/
public static function video($html, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
$resource = static::rich($html, $width, $height, $provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
$resource->type = self::TYPE_VIDEO;
return $resource;
}
/**
* Returns the resource type.
*
* @return string
* The resource type. Will be one of the self::TYPE_* constants.
*/
public function getType() {
return $this->type;
}
/**
* Returns the title of the resource.
*
* @return string|null
* The title of the resource, if known.
*/
public function getTitle() {
return $this->title;
}
/**
* Returns the name of the resource author.
*
* @return string|null
* The name of the resource author, if known.
*/
public function getAuthorName() {
return $this->authorName;
}
/**
* Returns the URL of the resource author.
*
* @return \Drupal\Core\Url|null
* The absolute URL of the resource author, or NULL if none is provided.
*/
public function getAuthorUrl() {
return $this->authorUrl ? Url::fromUri($this->authorUrl)
->setAbsolute() : NULL;
}
/**
* Returns the resource provider, if known.
*
* @return \Drupal\media\OEmbed\Provider|null
* The resource provider, or NULL if the provider is not known.
*/
public function getProvider() {
return $this->provider;
}
/**
* Returns the URL of the resource's thumbnail image.
*
* @return \Drupal\Core\Url|null
* The absolute URL of the thumbnail image, or NULL if there isn't one.
*/
public function getThumbnailUrl() {
return $this->thumbnailUrl ? Url::fromUri($this->thumbnailUrl)
->setAbsolute() : NULL;
}
/**
* Returns the width of the resource's thumbnail image.
*
* @return int|null
* The thumbnail width in pixels, or NULL if there is no thumbnail.
*/
public function getThumbnailWidth() {
return $this->thumbnailWidth;
}
/**
* Returns the height of the resource's thumbnail image.
*
* @return int|null
* The thumbnail height in pixels, or NULL if there is no thumbnail.
*/
public function getThumbnailHeight() {
return $this->thumbnailHeight;
}
/**
* Returns the width of the resource.
*
* @return int|null
* The width of the resource in pixels, or NULL if the resource has no
* width.
*/
public function getWidth() {
return $this->width;
}
/**
* Returns the height of the resource.
*
* @return int|null
* The height of the resource in pixels, or NULL if the resource has no
* height.
*/
public function getHeight() {
return $this->height;
}
/**
* Returns the URL of the resource. Only applies to 'photo' resources.
*
* @return \Drupal\Core\Url|null
* The resource URL, if it has one.
*/
public function getUrl() {
if ($this->url) {
return Url::fromUri($this->url)
->setAbsolute();
}
return NULL;
}
/**
* Returns the HTML representation of the resource.
*
* Only applies to 'rich' and 'video' resources.
*
* @return string|null
* The HTML representation of the resource, if it has one.
*/
public function getHtml() {
return isset($this->html) ? (string) $this->html : NULL;
}
/**
* Sets the thumbnail dimensions.
*
* @param int $width
* The width of the resource.
* @param int $height
* The height of the resource.
*
* @throws \InvalidArgumentException
* If either $width or $height are not numbers greater than zero.
*/
protected function setThumbnailDimensions($width, $height) {
$width = (int) $width;
$height = (int) $height;
if ($width > 0 && $height > 0) {
$this->thumbnailWidth = $width;
$this->thumbnailHeight = $height;
}
else {
throw new \InvalidArgumentException('The thumbnail dimensions must be numbers greater than zero.');
}
}
/**
* Sets the dimensions.
*
* @param int|null $width
* The width of the resource.
* @param int|null $height
* The height of the resource.
*
* @throws \InvalidArgumentException
* If either $width or $height are not numbers greater than zero.
*/
protected function setDimensions($width, $height) {
if (isset($width) && $width <= 0 || isset($height) && $height <= 0) {
throw new \InvalidArgumentException('The dimensions must be NULL or numbers greater than zero.');
}
$this->width = isset($width) ? (int) $width : NULL;
$this->height = isset($height) ? (int) $height : NULL;
}
}
Classes
Title | Deprecated | Summary |
---|---|---|
Resource | Value object representing an oEmbed resource. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.