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

Add ndrum files

<?php

namespace Drupal\media;

use Drupal\Component\Plugin\ConfigurableInterface;
use Drupal\Component\Plugin\ConfigurablePluginInterface;
use Drupal\Component\Plugin\DependentPluginInterface;
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Core\Entity\Display\EntityFormDisplayInterface;
use Drupal\Core\Entity\Display\EntityViewDisplayInterface;
use Drupal\Core\Plugin\PluginFormInterface;

/**
 * Defines the interface for media source plugins.
 *
 * Media sources provide the critical link between media items in Drupal and the
 * actual media itself, which typically exists independently of Drupal. Each
 * media source works with a certain kind of media. For example, local files and
 * YouTube videos can both be catalogued in a similar way as media items, but
 * they need very different handling to actually display them.
 *
 * Each media type needs exactly one source. A single source can be used on many
 * media types.
 *
 * Examples of possible sources are:
 * - File: handles local files,
 * - Image: handles local images,
 * - oEmbed: handles resources that are exposed through the oEmbed standard,
 * - YouTube: handles YouTube videos,
 * - SoundCloud: handles SoundCloud audio,
 * - Instagram: handles Instagram posts,
 * - Twitter: handles tweets,
 * - ...
 *
 * Their responsibilities are:
 * - Defining how media is represented (stored). Media sources are not
 *   responsible for actually storing the media. They only define how it is
 *   represented on a media item (usually using some kind of a field).
 * - Providing thumbnails. Media sources that are responsible for remote
 *   media will generally fetch the image from a third-party API and make
 *   it available for the local usage. Media sources that represent local
 *   media (such as images) will usually use some locally provided image.
 *   Media sources should fall back to a pre-defined default thumbnail if
 *   everything else fails.
 * - Validating a media item before it is saved. The entity constraint system
 *   will be used to ensure the valid structure of the media item.
 *   For example, media sources that represent remote media might check the
 *   URL or other identifier, while sources that represent local files might
 *   check the MIME type of the file.
 * - Providing a default name for a media item. This will save users from
 *   manually entering the name when it can be reliably set automatically.
 *   Media sources for local files will generally use the filename, while media
 *   sources for remote resources might obtain a title attribute through a
 *   third-party API. The name can always be overridden by the user.
 * - Providing metadata specific to the given media type. For example, remote
 *   media sources generally get information available through a
 *   third-party API and make it available to Drupal, while local media sources
 *   can expose things such as EXIF or ID3.
 * - Mapping metadata to the media item. Metadata that a media source exposes
 *   can automatically be mapped to the fields on the media item. Media
 *   sources will be able to define how this is done.
 *
 * @see \Drupal\media\Annotation\MediaSource
 * @see \Drupal\media\MediaSourceBase
 * @see \Drupal\media\MediaSourceManager
 * @see \Drupal\media\MediaTypeInterface
 * @see \Drupal\media\MediaSourceEntityConstraintsInterface
 * @see \Drupal\media\MediaSourceFieldConstraintsInterface
 * @see plugin_api
 */
interface MediaSourceInterface extends PluginInspectionInterface, ConfigurableInterface, DependentPluginInterface, ConfigurablePluginInterface, PluginFormInterface {

  /**
   * Default empty value for metadata fields.
   */
  const METADATA_FIELD_EMPTY = '_none';

  /**
   * Gets a list of metadata attributes provided by this plugin.
   *
   * Most media sources have associated metadata, describing attributes
   * such as:
   * - dimensions
   * - duration
   * - encoding
   * - date
   * - location
   * - permalink
   * - licensing information
   * - ...
   *
   * This method should list all metadata attributes that a media source MAY
   * offer. In other words: it is possible that a particular media item does
   * not contain a certain attribute. For example: an oEmbed media source can
   * contain both video and images. Images don't have a duration, but
   * videos do.
   *
   * (The term 'attributes' was chosen because it cannot be confused
   * with 'fields' and 'properties', both of which are concepts in Drupal's
   * Entity Field API.)
   *
   * @return array
   *   Associative array with:
   *   - keys: metadata attribute names
   *   - values: human-readable labels for those attribute names
   */
  public function getMetadataAttributes();

  /**
   * Gets the value for a metadata attribute for a given media item.
   *
   * @param \Drupal\media\MediaInterface $media
   *   A media item.
   * @param string $attribute_name
   *   Name of the attribute to fetch.
   *
   * @return mixed|null
   *   Metadata attribute value or NULL if unavailable.
   */
  public function getMetadata(MediaInterface $media, $attribute_name);

  /**
   * Get the source field definition for a media type.
   *
   * @param \Drupal\media\MediaTypeInterface $type
   *   A media type.
   *
   * @return \Drupal\Core\Field\FieldDefinitionInterface|null
   *   The source field definition, or NULL if it doesn't exist or has not been
   *   configured yet.
   */
  public function getSourceFieldDefinition(MediaTypeInterface $type);

  /**
   * Creates the source field definition for a type.
   *
   * @param \Drupal\media\MediaTypeInterface $type
   *   The media type.
   *
   * @return \Drupal\field\FieldConfigInterface
   *   The unsaved field definition. The field storage definition, if new,
   *   should also be unsaved.
   */
  public function createSourceField(MediaTypeInterface $type);

  /**
   * Prepares the media type fields for this source in the view display.
   *
   * This method should normally call
   * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
   * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
   * configure the media type fields in the view display.
   *
   * @param \Drupal\media\MediaTypeInterface $type
   *   The media type which is using this source.
   * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
   *   The display which should be prepared.
   *
   * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
   * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
   */
  public function prepareViewDisplay(MediaTypeInterface $type, EntityViewDisplayInterface $display);

  /**
   * Prepares the media type fields for this source in the form display.
   *
   * This method should normally call
   * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
   * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
   * configure the media type fields in the form display.
   *
   * @param \Drupal\media\MediaTypeInterface $type
   *   The media type which is using this source.
   * @param \Drupal\Core\Entity\Display\EntityFormDisplayInterface $display
   *   The display which should be prepared.
   *
   * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
   * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
   */
  public function prepareFormDisplay(MediaTypeInterface $type, EntityFormDisplayInterface $display);

  /**
   * Get the primary value stored in the source field.
   *
   * @param MediaInterface $media
   *   A media item.
   *
   * @return mixed
   *   The source value.
   *
   * @throws \RuntimeException
   *   If the source field for the media source is not defined.
   */
  public function getSourceFieldValue(MediaInterface $media);

}