Mercurial > hg > isophonics-drupal-site
view core/modules/media/src/OEmbed/Resource.php @ 19:fa3358dc1485 tip
Add ndrum files
author | Chris Cannam |
---|---|
date | Wed, 28 Aug 2019 13:14:47 +0100 |
parents | 129ea1e6d783 |
children |
line wrap: on
line 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 * dimensions */ 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 * dimensions. */ 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 $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 setDimensions($width, $height) { $width = (int) $width; $height = (int) $height; if ($width > 0 && $height > 0) { $this->width = $width; $this->height = $height; } else { throw new \InvalidArgumentException('The dimensions must be numbers greater than zero.'); } } }