annotate core/modules/media/src/OEmbed/Resource.php @ 19:fa3358dc1485 tip

Add ndrum files

<?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.');
    }
  }

}