class Download in Drupal 8

Downloads a file from a HTTP(S) remote location into the local file system.

The source value is an array of two values:

• source URL, e.g. 'http://www.example.com/img/foo.img'
• destination URI, e.g. 'public://images/foo.img'

Available configuration keys:

• file_exists: (optional) Replace behavior when the destination file already exists:
  • 'replace' - (default) Replace the existing file.
  • 'rename' - Append _{incrementing number} until the filename is unique.
  • 'use existing' - Do nothing and return FALSE.
• guzzle_options: (optional) Array of request options for Guzzle.

Examples:

process:
  plugin: download
  source:
    - source_url
    - destination_uri

This will download source_url to destination_uri.

process:
  plugin: download
  source:
    - source_url
    - destination_uri
  file_exists: rename

This will download source_url to destination_uri and ensure that the destination URI is unique. If a file with the same name exists at the destination, a numbered suffix like '_0' will be appended to make it unique.

Plugin annotation

@MigrateProcessPlugin(
  id = "download"
)

Hierarchy

• class \Drupal\Component\Plugin\PluginBase implements DerivativeInspectionInterface, PluginInspectionInterface
  • class \Drupal\Core\Plugin\PluginBase uses DependencySerializationTrait, MessengerTrait, StringTranslationTrait
    • class \Drupal\migrate\ProcessPluginBase implements MigrateProcessInterface
      • class \Drupal\migrate\Plugin\migrate\process\FileProcessBase
        • class \Drupal\migrate\Plugin\migrate\process\Download implements ContainerFactoryPluginInterface

1 file declares its use of Download

DownloadTest.php in core/modules/migrate/tests/src/Kernel/process/DownloadTest.php

1 string reference to 'Download'

UpdateContribTest::assertCoreCompatibilityMessage in core/modules/update/tests/src/Functional/UpdateContribTest.php

Asserts that a core compatibility message is correct for an update.

File

core/modules/migrate/src/Plugin/migrate/process/Download.php, line 59

Namespace

Drupal\migrate\Plugin\migrate\process

class Download extends FileProcessBase implements ContainerFactoryPluginInterface {

  /**
   * The file system service.
   *
   * @var \Drupal\Core\File\FileSystemInterface
   */
  protected $fileSystem;

  /**
   * The Guzzle HTTP Client service.
   *
   * @var \GuzzleHttp\Client
   */
  protected $httpClient;

  /**
   * Constructs a download process plugin.
   *
   * @param array $configuration
   *   The plugin configuration.
   * @param string $plugin_id
   *   The plugin ID.
   * @param mixed $plugin_definition
   *   The plugin definition.
   * @param \Drupal\Core\File\FileSystemInterface $file_system
   *   The file system service.
   * @param \GuzzleHttp\Client $http_client
   *   The HTTP client.
   */
  public function __construct(array $configuration, $plugin_id, array $plugin_definition, FileSystemInterface $file_system, Client $http_client) {
    $configuration += [
      'guzzle_options' => [],
    ];
    parent::__construct($configuration, $plugin_id, $plugin_definition);
    $this->fileSystem = $file_system;
    $this->httpClient = $http_client;
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
    return new static($configuration, $plugin_id, $plugin_definition, $container
      ->get('file_system'), $container
      ->get('http_client'));
  }

  /**
   * {@inheritdoc}
   */
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {

    // If we're stubbing a file entity, return a uri of NULL so it will get
    // stubbed by the general process.
    if ($row
      ->isStub()) {
      return NULL;
    }
    list($source, $destination) = $value;

    // Modify the destination filename if necessary.
    $final_destination = $this->fileSystem
      ->getDestinationFilename($destination, $this->configuration['file_exists']);

    // Reuse if file exists.
    if (!$final_destination) {
      return $destination;
    }

    // Try opening the file first, to avoid calling prepareDirectory()
    // unnecessarily. We're suppressing fopen() errors because we want to try
    // to prepare the directory before we give up and fail.
    $destination_stream = @fopen($final_destination, 'w');
    if (!$destination_stream) {

      // If fopen didn't work, make sure there's a writable directory in place.
      $dir = $this->fileSystem
        ->dirname($final_destination);
      if (!$this->fileSystem
        ->prepareDirectory($dir, FileSystemInterface::CREATE_DIRECTORY | FileSystemInterface::MODIFY_PERMISSIONS)) {
        throw new MigrateException("Could not create or write to directory '{$dir}'");
      }

      // Let's try that fopen again.
      $destination_stream = @fopen($final_destination, 'w');
      if (!$destination_stream) {
        throw new MigrateException("Could not write to file '{$final_destination}'");
      }
    }

    // Stream the request body directly to the final destination stream.
    $this->configuration['guzzle_options']['sink'] = $destination_stream;
    try {

      // Make the request. Guzzle throws an exception for anything but 200.
      $this->httpClient
        ->get($source, $this->configuration['guzzle_options']);
    } catch (\Exception $e) {
      throw new MigrateException("{$e->getMessage()} ({$source})");
    }
    return $final_destination;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property	An array of entity type IDs keyed by the property name of their storages.
DependencySerializationTrait::$_serviceIds	protected	property	An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep	public	function		1
DependencySerializationTrait::__wakeup	public	function		2
Download::$fileSystem	protected	property	The file system service.
Download::$httpClient	protected	property	The Guzzle HTTP Client service.
Download::create	public static	function	Creates an instance of the plugin. Overrides ContainerFactoryPluginInterface::create
Download::transform	public	function	Performs the associated process. Overrides ProcessPluginBase::transform
Download::__construct	public	function	Constructs a download process plugin. Overrides FileProcessBase::__construct
MessengerTrait::$messenger	protected	property	The messenger.	29
MessengerTrait::messenger	public	function	Gets the messenger.	29
MessengerTrait::setMessenger	public	function	Sets the messenger.
PluginBase::$configuration	protected	property	Configuration information passed into the plugin.	1
PluginBase::$pluginDefinition	protected	property	The plugin implementation definition.	1
PluginBase::$pluginId	protected	property	The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR		constant	A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId	public	function	Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId	public	function	Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition	3
PluginBase::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable	public	function	Determines if the plugin is configurable.
ProcessPluginBase::multiple	public	function	Indicates whether the returned value requires multiple handling. Overrides MigrateProcessInterface::multiple	3
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	1
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.