You are here

Home » API reference » Drupal 9 » Resource.php

class Resource in Drupal 9

Same name and namespace in other branches
  1. 8 core/modules/media/src/OEmbed/Resource.php \Drupal\media\OEmbed\Resource

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.

@internal This class is an internal part of the oEmbed system and should only be instantiated by \Drupal\media\OEmbed\ResourceFetcherInterface::fetchResource().

Hierarchy

Expanded class hierarchy of Resource

See also

https://oembed.com/#section2

6 files declare their use of Resource
OEmbed.php in core/modules/media/src/Plugin/media/Source/OEmbed.php
OEmbedFormatter.php in core/modules/media/src/Plugin/Field/FieldFormatter/OEmbedFormatter.php
OEmbedIframeControllerTest.php in core/modules/media/tests/src/Kernel/OEmbedIframeControllerTest.php
OEmbedSourceTest.php in core/modules/media/tests/src/Kernel/OEmbedSourceTest.php
ResourceFetcherTest.php in core/modules/media/tests/src/Functional/ResourceFetcherTest.php

... See full list

File

core/modules/media/src/OEmbed/Resource.php, line 29

Namespace

Drupal\media\OEmbed
View source 
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
   *   (optional) 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 = NULL, 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
   *   (optional) 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 = NULL, 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
   *   (optional) 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 = 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 = 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;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
CacheableDependencyTrait::$cacheContexts protected property Cache contexts.
CacheableDependencyTrait::$cacheMaxAge protected property Cache max-age.
CacheableDependencyTrait::$cacheTags protected property Cache tags.
CacheableDependencyTrait::getCacheContexts public function 4
CacheableDependencyTrait::getCacheMaxAge public function 4
CacheableDependencyTrait::getCacheTags public function 4
CacheableDependencyTrait::setCacheability protected function Sets cacheability; useful for value object constructors.
Resource::$authorName protected property The name of the author/owner of the resource.
Resource::$authorUrl protected property A URL for the author/owner of the resource.
Resource::$height protected property The height of the resource, in pixels.
Resource::$html protected property The HTML representation of the resource.
Resource::$provider protected property The resource provider.
Resource::$thumbnailHeight protected property The height of the thumbnail, in pixels.
Resource::$thumbnailUrl protected property A URL to a thumbnail image representing the resource.
Resource::$thumbnailWidth protected property The width of the thumbnail, in pixels.
Resource::$title protected property A text title, describing the resource.
Resource::$type protected property The resource type. Can be one of the static::TYPE_* constants.
Resource::$url protected property The resource URL. Only applies to 'photo' and 'link' resources.
Resource::$width protected property The width of the resource, in pixels.
Resource::getAuthorName public function Returns the name of the resource author.
Resource::getAuthorUrl public function Returns the URL of the resource author.
Resource::getHeight public function Returns the height of the resource.
Resource::getHtml public function Returns the HTML representation of the resource.
Resource::getProvider public function Returns the resource provider, if known.
Resource::getThumbnailHeight public function Returns the height of the resource's thumbnail image.
Resource::getThumbnailUrl public function Returns the URL of the resource's thumbnail image.
Resource::getThumbnailWidth public function Returns the width of the resource's thumbnail image.
Resource::getTitle public function Returns the title of the resource.
Resource::getType public function Returns the resource type.
Resource::getUrl public function Returns the URL of the resource. Only applies to 'photo' resources.
Resource::getWidth public function Returns the width of the resource.
Resource::link public static function Creates a link resource.
Resource::photo public static function Creates a photo resource.
Resource::rich public static function Creates a rich resource.
Resource::setDimensions protected function Sets the dimensions.
Resource::setThumbnailDimensions protected function Sets the thumbnail dimensions.
Resource::TYPE_LINK constant The resource type for link resources.
Resource::TYPE_PHOTO constant The resource type for photo resources.
Resource::TYPE_RICH constant The resource type for rich resources.
Resource::TYPE_VIDEO constant The resource type for video resources.
Resource::video public static function Creates a video resource.
Resource::__construct protected function Resource constructor.