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