Commit 5421fdee authored by alexpott's avatar alexpott

Issue #2624660 by Lars Toomre: Some fixes to migrate/src/Plugin/*.php files

parent 1a6baa4c
......@@ -11,8 +11,8 @@
* Defines the builder plugin type.
*
* Builder plugins implement custom logic to generate migration entities from
* migration templates. For example, a migration may need to be customized
* based on data that's present in the source database; such customization is
* migration templates. For example, a migration may need to be customized based
* on data that's present in the source database; such customization is
* implemented by builders.
*/
interface MigrateBuilderInterface {
......
......@@ -12,6 +12,8 @@
use Drupal\migrate\Row;
/**
* Defines an interface for Migration Destination classes.
*
* Destinations are responsible for persisting source data into the destination
* Drupal.
*
......@@ -43,11 +45,11 @@ public function getIds();
* Derived classes must implement fields(), returning a list of available
* destination fields.
*
* @todo Review the cases where we need the Migration parameter,
* can we avoid that?
* @todo Review the cases where we need the Migration parameter, can we avoid
* that? To be resolved with https://www.drupal.org/node/2543568.
*
* @param \Drupal\migrate\Entity\MigrationInterface $migration
* (optional) The migration containing this destination.
* (optional) The migration containing this destination. Defaults to NULL.
*
* @return array
* - Keys: machine names of the fields
......
......@@ -5,7 +5,6 @@
* Contains \Drupal\migrate\Plugin\MigrateDestinationPluginManager.
*/
namespace Drupal\migrate\Plugin;
use Drupal\Core\Cache\CacheBackendInterface;
......@@ -37,7 +36,7 @@ class MigrateDestinationPluginManager extends MigratePluginManager {
*
* @param string $type
* The type of the plugin: row, source, process, destination, entity_field,
* id_map.
* id_map.
* @param \Traversable $namespaces
* An object that implements \Traversable which contains the root paths
* keyed by the corresponding namespace to look for plugin implementations.
......@@ -48,7 +47,8 @@ class MigrateDestinationPluginManager extends MigratePluginManager {
* @param \Drupal\Core\Entity\EntityManagerInterface $entity_manager
* The entity manager.
* @param string $annotation
* The annotation class name.
* (optional) The annotation class name. Defaults to
* 'Drupal\migrate\Annotation\MigrateDestination'.
*/
public function __construct($type, \Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler, EntityManagerInterface $entity_manager, $annotation = 'Drupal\migrate\Annotation\MigrateDestination') {
parent::__construct($type, $namespaces, $cache_backend, $module_handler, $annotation);
......
......@@ -37,8 +37,8 @@ interface MigrateIdMapInterface extends \Iterator, PluginInspectionInterface {
/**
* Saves a mapping from the source identifiers to the destination identifiers.
*
* Called upon import of one row, we record a mapping from the source ID
* to the destination ID. Also may be called, setting the third parameter to
* Called upon import of one row, we record a mapping from the source ID to
* the destination ID. Also may be called, setting the third parameter to
* NEEDS_UPDATE, to signal an existing record should be re-migrated.
*
* @param \Drupal\migrate\Row $row
......@@ -47,9 +47,11 @@ interface MigrateIdMapInterface extends \Iterator, PluginInspectionInterface {
* @param array $destination_id_values
* An array of destination identifier values.
* @param int $status
* Status of the source row in the map.
* (optional) Status of the source row in the map. Defaults to
* self::STATUS_IMPORTED.
* @param int $rollback_action
* How to handle the destination object on rollback.
* (optional) How to handle the destination object on rollback. Defaults to
* self::ROLLBACK_DELETE.
*/
public function saveIdMapping(Row $row, array $destination_id_values, $status = self::STATUS_IMPORTED, $rollback_action = self::ROLLBACK_DELETE);
......@@ -61,7 +63,8 @@ public function saveIdMapping(Row $row, array $destination_id_values, $status =
* @param string $message
* The message to record.
* @param int $level
* Optional message severity (defaults to MESSAGE_ERROR).
* (optional) The message severity. Defaults to
* MigrationInterface::MESSAGE_ERROR.
*/
public function saveMessage(array $source_id_values, $message, $level = MigrationInterface::MESSAGE_ERROR);
......@@ -69,10 +72,11 @@ public function saveMessage(array $source_id_values, $message, $level = Migratio
* Retrieves an iterator over messages relate to source records.
*
* @param array $source_id_values
* (optional) The source identifier keyed values of the record, e.g. ['nid' => 5].
* If empty, all messages are retrieved.
* (optional) The source identifier keyed values of the record, e.g.
* ['nid' => 5]. If empty (the default), all messages are retrieved.
* @param int $level
* (optional) Message severity. If NULL, retrieve messages of all severities.
* (optional) Message severity. If NULL (the default), retrieve messages of
* all severities.
*
* @return \Iterator
* Retrieves an iterator over the message rows.
......@@ -136,7 +140,7 @@ public function messageCount();
* @param array $source_id_values
* The source identifier keyed values of the record, e.g. ['nid' => 5].
* @param bool $messages_only
* TRUE to only delete the migrate messages.
* (optional) TRUE to only delete the migrate messages. Defaults to FALSE.
*/
public function delete(array $source_id_values, $messages_only = FALSE);
......
......@@ -34,7 +34,7 @@ class MigratePluginManager extends DefaultPluginManager {
*
* @param string $type
* The type of the plugin: row, source, process, destination, entity_field,
* id_map.
* id_map.
* @param \Traversable $namespaces
* An object that implements \Traversable which contains the root paths
* keyed by the corresponding namespace to look for plugin implementations.
......@@ -43,7 +43,8 @@ class MigratePluginManager extends DefaultPluginManager {
* @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
* The module handler to invoke the alter hook with.
* @param string $annotation
* The annotation class name.
* (optional) The annotation class name. Defaults to
* 'Drupal\Component\Annotation\PluginID'.
*/
public function __construct($type, \Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler, $annotation = 'Drupal\Component\Annotation\PluginID') {
$plugin_interface = isset($plugin_interface_map[$type]) ? $plugin_interface_map[$type] : NULL;
......
......@@ -37,12 +37,12 @@ interface MigrateProcessInterface extends PluginInspectionInterface {
* @param \Drupal\migrate\MigrateExecutableInterface $migrate_executable
* The migration in which this process is being executed.
* @param \Drupal\migrate\Row $row
* The row from the source to process. Normally, just transforming the
* value is adequate but very rarely you might need to change two columns
* at the same time or something like that.
* The row from the source to process. Normally, just transforming the value
* is adequate but very rarely you might need to change two columns at the
* same time or something like that.
* @param string $destination_property
* The destination property currently worked on. This is only used
* together with the $row above.
* The destination property currently worked on. This is only used together
* with the $row above.
*
* @return string|array
* The newly transformed value.
......
......@@ -31,7 +31,7 @@ interface MigrateSourceInterface extends \Countable, \Iterator, PluginInspection
public function fields();
/**
* Add additional data to the row.
* Adds additional data to the row.
*
* @param \Drupal\Migrate\Row $row
* The row object.
......@@ -41,13 +41,17 @@ public function fields();
*/
public function prepareRow(Row $row);
/**
* Allows class to decide how it will react when it is treated like a string.
*/
public function __toString();
/**
* Defines the source fields uniquely identifying a source row. None of these
* fields should contain a NULL value - if necessary, use prepareRow() or
* hook_migrate_prepare_row() to rewrite NULL values to appropriate empty
* values (such as '' or 0).
* Defines the source fields uniquely identifying a source row.
*
* None of these fields should contain a NULL value. If necessary, use
* prepareRow() or hook_migrate_prepare_row() to rewrite NULL values to
* appropriate empty values (such as '' or 0).
*
* @return array
* Array keyed by source field name, with values being a schema array
......
......@@ -22,6 +22,8 @@
class DedupeEntity extends DedupeBase implements ContainerFactoryPluginInterface {
/**
* The entity query factory.
*
* @var \Drupal\Core\Entity\Query\QueryFactoryInterface
*/
protected $entityQueryFactory;
......
......@@ -11,7 +11,6 @@
use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\Row;
/**
* This plugin sets missing values on the destination.
*
......@@ -30,4 +29,5 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
}
return $value ?: $this->configuration['default_value'];
}
}
......@@ -34,4 +34,5 @@ class Flatten extends ProcessPluginBase {
public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
return iterator_to_array(new \RecursiveIteratorIterator(new \RecursiveArrayIterator($value)), FALSE);
}
}
......@@ -21,6 +21,8 @@
class Get extends ProcessPluginBase {
/**
* Flag indicating whether there are multiple values.
*
* @var bool
*/
protected $multiple;
......@@ -69,4 +71,5 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
public function multiple() {
return $this->multiple;
}
}
......@@ -65,4 +65,5 @@ protected function transformKey($key, MigrateExecutableInterface $migrate_execut
public function multiple() {
return TRUE;
}
}
......@@ -29,6 +29,8 @@
class MachineName extends ProcessPluginBase implements ContainerFactoryPluginInterface {
/**
* The transliteration service.
*
* @var \Drupal\Component\Transliteration\TransliterationInterface
*/
protected $transliteration;
......@@ -37,13 +39,13 @@ class MachineName extends ProcessPluginBase implements ContainerFactoryPluginInt
* Constructs a MachineName plugin.
*
* @param array $configuration
* The plugin configuration.
* The plugin configuration.
* @param string $plugin_id
* The plugin ID.
* The plugin ID.
* @param mixed $plugin_definition
* The plugin definition.
* The plugin definition.
* @param \Drupal\Component\Transliteration\TransliterationInterface $transliteration
* The transliteration service.
* The transliteration service.
*/
public function __construct(array $configuration, $plugin_id, $plugin_definition, TransliterationInterface $transliteration) {
parent::__construct($configuration, $plugin_id, $plugin_definition);
......
......@@ -5,7 +5,6 @@
* Contains \Drupal\migrate\Plugin\migrate\process\Migration.
*/
namespace Drupal\migrate\Plugin\migrate\process;
use Drupal\Core\Entity\EntityStorageInterface;
......@@ -28,11 +27,15 @@
class Migration extends ProcessPluginBase implements ContainerFactoryPluginInterface {
/**
* The process plugin manager.
*
* @var \Drupal\migrate\Plugin\MigratePluginManager
*/
protected $processPluginManager;
/**
* The entity storage manager.
*
* @var \Drupal\Core\Entity\EntityStorageInterface
*/
protected $migrationStorage;
......@@ -148,7 +151,7 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
}
/**
* Skip the migration process entirely if the value is FALSE.
* Skips the migration process entirely if the value is FALSE.
*
* @param mixed $value
* The incoming value to transform.
......
<?php
/**
* @file
* Contains \Drupal\migrate\Plugin\migrate\process\Route.
......@@ -22,6 +23,8 @@
class Route extends ProcessPluginBase implements ContainerFactoryPluginInterface {
/**
* The path validator service.
*
* @var \Drupal\Core\Path\PathValidatorInterface
*/
protected $pathValidator;
......@@ -29,10 +32,10 @@ class Route extends ProcessPluginBase implements ContainerFactoryPluginInterface
/**
* {@inheritdoc}
*/
public function __construct(array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration, PathValidatorInterface $pathValidator) {
public function __construct(array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration, PathValidatorInterface $path_validator) {
parent::__construct($configuration, $plugin_id, $plugin_definition);
$this->migration = $migration;
$this->pathValidator = $pathValidator;
$this->pathValidator = $path_validator;
}
/**
......@@ -60,7 +63,7 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
if ($extracted) {
if ($extracted->isExternal()) {
$route['route_name'] = null;
$route['route_name'] = NULL;
$route['route_parameters'] = array();
$route['options'] = $options;
$route['url'] = $extracted->getUri();
......@@ -83,7 +86,7 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
unset($route['options']['query']);
}
$route['options'] = $route['options'] + $options;
$route['url'] = null;
$route['url'] = NULL;
}
}
......@@ -91,4 +94,3 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
}
}
......@@ -8,10 +8,12 @@
namespace Drupal\migrate\Plugin\migrate\source;
/**
* Provides a dummy select query object for source plugins.
*
* Trait providing a dummy select query object for source plugins based on
* SqlBase which override initializeIterator() to obtain their data from other
* SqlBase services instead of a direct query. This ensures that query() returns
* a valid object, even though it isn't used for iteration.
* a valid object, even though it is not used for iteration.
*/
trait DummyQueryTrait {
......@@ -19,7 +21,8 @@ trait DummyQueryTrait {
* {@inheritdoc}
*/
public function query() {
// Pass an arbritrary table name - the query should never be executed anyway.
// Pass an arbritrary table name - the query should never be executed
// anyway.
$query = $this->select(uniqid(), 's')
->range(0, 1);
$query->addExpression('1');
......
......@@ -34,6 +34,9 @@ public function initializeIterator() {
return new \ArrayIterator(array(array('id' => '')));
}
/**
* Allows class to decide how it will react when it is treated like a string.
*/
public function __toString() {
return '';
}
......
......@@ -28,11 +28,15 @@
abstract class SourcePluginBase extends PluginBase implements MigrateSourceInterface {
/**
* The module handler service.
*
* @var \Drupal\Core\Extension\ModuleHandlerInterface
*/
protected $moduleHandler;
/**
* The entity migration object.
*
* @var \Drupal\migrate\Entity\MigrationInterface
*/
protected $migration;
......@@ -47,14 +51,14 @@ abstract class SourcePluginBase extends PluginBase implements MigrateSourceInter
protected $highWaterProperty;
/**
* The current row from the query
* The current row from the query.
*
* @var \Drupal\Migrate\Row
*/
protected $currentRow;
/**
* The primary key of the current row
* The primary key of the current row.
*
* @var array
*/
......@@ -92,6 +96,8 @@ abstract class SourcePluginBase extends PluginBase implements MigrateSourceInter
protected $skipCount = FALSE;
/**
* Flags whether to track changes to incloming data.
*
* If TRUE, we will maintain hashed source rows to determine whether incoming
* data has changed.
*
......@@ -100,6 +106,8 @@ abstract class SourcePluginBase extends PluginBase implements MigrateSourceInter
protected $trackChanges = FALSE;
/**
* Flags whether source plugin will read the map row and add to data row.
*
* By default, next() will directly read the map row and add it to the data
* row. A source plugin implementation may do this itself (in particular, the
* SQL source can incorporate the map table into the query) - if so, it should
......@@ -110,16 +118,22 @@ abstract class SourcePluginBase extends PluginBase implements MigrateSourceInter
protected $mapRowAdded = FALSE;
/**
* The backend cache.
*
* @var \Drupal\Core\Cache\CacheBackendInterface
*/
protected $cache;
/**
* The migration ID map.
*
* @var \Drupal\migrate\Plugin\MigrateIdMapInterface
*/
protected $idMap;
/**
* The iterator to iterate over the source rows.
*
* @var \Iterator
*/
protected $iterator;
......@@ -150,7 +164,7 @@ public function __construct(array $configuration, $plugin_id, $plugin_definition
}
/**
* Initialize the iterator with the source data.
* Initializes the iterator with the source data.
*
* @return array
* An array of the data for this source.
......@@ -158,7 +172,7 @@ public function __construct(array $configuration, $plugin_id, $plugin_definition
protected abstract function initializeIterator();
/**
* Get the module handler.
* Gets the module handler.
*
* @return \Drupal\Core\Extension\ModuleHandlerInterface
* The module handler.
......@@ -212,6 +226,7 @@ public function prepareRow(Row $row) {
* Returns the iterator that will yield the row arrays to be processed.
*
* @return \Iterator
* The iterator that will yield the row arrays to be processed.
*/
protected function getIterator() {
if (!isset($this->iterator)) {
......@@ -228,7 +243,7 @@ public function current() {
}
/**
* Get the iterator key.
* Gets the iterator key.
*
* Implementation of Iterator::key - called when entering a loop iteration,
* returning the key of the current row. It must be a scalar - we will
......@@ -240,17 +255,17 @@ public function key() {
}
/**
* Whether the iterator is currently valid.
* Checks whether the iterator is currently valid.
*
* Implementation of Iterator::valid() - called at the top of the loop,
* returning TRUE to process the loop and FALSE to terminate it
* returning TRUE to process the loop and FALSE to terminate it.
*/
public function valid() {
return isset($this->currentRow);
}
/**
* Rewind the iterator.
* Rewinds the iterator.
*
* Implementation of Iterator::rewind() - subclasses of MigrateSource should
* implement performRewind() to do any class-specific setup for iterating
......@@ -311,14 +326,14 @@ public function next() {
// 2. Explicitly set to update.
// 3. The row is newer than the current highwater mark.
// 4. If no such property exists then try by checking the hash of the row.
if (!$row->getIdMap() || $row->needsUpdate() || $this->aboveHighwater($row) || $this->rowChanged($row) ) {
if (!$row->getIdMap() || $row->needsUpdate() || $this->aboveHighwater($row) || $this->rowChanged($row)) {
$this->currentRow = $row->freezeSource();
}
}
}
/**
* Check if the incoming data is newer than what we've previously imported.
* Checks if the incoming data is newer than what we've previously imported.
*
* @param \Drupal\migrate\Row $row
* The row we're importing.
......@@ -331,7 +346,7 @@ protected function aboveHighwater(Row $row) {
}
/**
* Check if the incoming row has changed since our last import.
* Checks if the incoming row has changed since our last import.
*
* @param \Drupal\migrate\Row $row
* The row we're importing.
......@@ -344,20 +359,20 @@ protected function rowChanged(Row $row) {
}
/**
* Getter for currentSourceIds data member.
* Gets the currentSourceIds data member.
*/
public function getCurrentIds() {
return $this->currentSourceIds;
}
/**
* Get the source count.
* Gets the source count.
*
* Return a count of available source records, from the cache if appropriate.
* Returns -1 if the source is not countable.
*
* @param bool $refresh
* Whether or not to refresh the count.
* (optional) Whether or not to refresh the count. Defaults to FALSE.
*
* @return int
* The count.
......@@ -395,7 +410,7 @@ public function count($refresh = FALSE) {
}
/**
* Get the cache object.
* Gets the cache object.
*
* @return \Drupal\Core\Cache\CacheBackendInterface
* The cache object.
......
......@@ -27,11 +27,15 @@
abstract class SqlBase extends SourcePluginBase implements ContainerFactoryPluginInterface {
/**
* The query string.
*
* @var \Drupal\Core\Database\Query\SelectInterface
*/
protected $query;
/**
* The database object.
*
* @var \Drupal\Core\Database\Connection
*/
protected $database;
......@@ -65,7 +69,7 @@ public static function create(ContainerInterface $container, array $configuratio
}
/**
* Print the query string when the object is used a string.
* Prints the query string when the object is used as a string.
*
* @return string
* The query string.
......@@ -75,7 +79,7 @@ public function __toString() {
}
/**
* Get the database connection object.
* Gets the database connection object.
*
* @return \Drupal\Core\Database\Connection
* The database connection.
......@@ -95,8 +99,9 @@ public function getDatabase() {
}
/**
* Get a connection to the referenced database, adding the connection if
* necessary.
* Gets a connection to the referenced database.
*
* This method will add the database connection if necessary.
*
* @param array $database_info
* Configuration for the source database connection. The keys are:
......@@ -136,7 +141,7 @@ protected function select($table, $alias = NULL, array $options = array()) {
}
/**