You are here

Home » API reference » Drupal-to-Drupal data migration 7.2 » user.inc

abstract class DrupalUserMigration in Drupal-to-Drupal data migration 7.2

Base class for all user migrations - handles commonalities across all supported source Drupal versions.

Hierarchy

Expanded class hierarchy of DrupalUserMigration

File

./user.inc, line 11
Base class for migrating users into Drupal.

View source 
abstract class DrupalUserMigration extends DrupalMigration {

  /**
   * If there's a user picture migration, keep track of the machine name
   * for dependency management and sourceMigration.
   *
   * @var string
   */
  protected $pictureMigration = '';

  /**
   * If there's a user role migration, keep track of the machine name
   * for dependency management and sourceMigration.
   *
   * @var string
   */
  protected $roleMigration = '';

  /**
   * @param array $arguments
   * picture_migration - Machine name of a picture migration, used to establish
   *   dependencies and a sourceMigration for the picture mapping.
   * role_migration - Machine name of a role migration, used to establish
   *   dependencies and a sourceMigration for the picture mapping.
   */
  public function __construct(array $arguments) {
    parent::__construct($arguments);
    if (!empty($arguments['picture_migration'])) {
      $this->pictureMigration = $arguments['picture_migration'];
      $this->dependencies[] = $this->pictureMigration;
    }
    if (!empty($arguments['role_migration'])) {
      $this->roleMigration = $arguments['role_migration'];
      $this->dependencies[] = $this->roleMigration;
    }

    // Document known core fields
    $this->sourceFields += array(
      'uid' => t('User ID'),
      'mail' => t('Email address'),
      'name' => t('Username'),
      'pass' => t('Password'),
      'status' => t('Status'),
      'created' => t('Registered timestamp'),
      'access' => t('Last access timestamp'),
      'login' => t('Last login timestamp'),
      'picture' => t('Picture'),
      'signature' => t('Signature'),
      'signature_format' => t('Signature format'),
      'timezone' => t('Timezone'),
      'language' => t('Language'),
      'theme' => t('Default theme'),
      'init' => t('Init'),
      'data' => t('Data'),
    );

    // Get any CCK fields attached to users.
    $this->sourceFields += $this->version
      ->getSourceFields('user', 'user');
    if ($this
      ->moduleExists('path')) {
      $this->sourceFields['path'] = t('Path alias');
    }
    if ($this->roleMigration) {
      $this->sourceFields['roles'] = t('Roles');
    }
    if (!isset($this->sourceOptions['track_changes']) && !$this->newOnly) {
      $this->sourceOptions['track_changes'] = TRUE;
    }
    $this->source = new MigrateSourceSQL($this
      ->query(), $this->sourceFields, NULL, $this->sourceOptions);
    $this->map = new MigrateSQLMap($this->machineName, array(
      'uid' => array(
        'type' => 'int',
        'unsigned' => TRUE,
        'not null' => TRUE,
        'description' => 'Source user ID',
        'alias' => 'u',
      ),
    ), DrupalDestinationUser::getKeySchema(), $this->mapConnection);

    // Most mappings are straight-forward
    $this
      ->addSimpleMappings(array(
      'pass',
      'mail',
      'theme',
      'signature',
      'created',
      'access',
      'login',
      'status',
      'language',
      'init',
      'timezone',
    ));

    // user_save() expects the data field to be unpacked
    $this
      ->addFieldMapping('data', 'data')
      ->callbacks('unserialize');

    // Dedupe username collisions by appending _1, _2, etc.
    $this
      ->addFieldMapping('name', 'name')
      ->dedupe('users', 'name');
    if (isset($this->pictureMigration)) {
      $this
        ->addFieldMapping('picture', 'picture')
        ->sourceMigration($this->pictureMigration);
    }
    else {
      $this
        ->addFieldMapping('picture', 'picture');
    }
    if (isset($this->roleMigration)) {
      $this
        ->addFieldMapping('roles', 'roles')
        ->sourceMigration($this->roleMigration);
    }
    else {
      $this
        ->addFieldMapping('roles');
    }
    $this
      ->addFieldMapping('signature_format', 'signature_format')
      ->callbacks(array(
      $this,
      'mapFormat',
    ));
    $this
      ->addUnmigratedDestinations(array(
      'is_new',
      'role_names',
    ));
    if (module_exists('path') && $this
      ->moduleExists('path')) {
      $this
        ->addFieldMapping('path', 'path')
        ->description('Handled in prepareRow');
    }
    else {
      if (module_exists('path')) {
        $this
          ->addUnmigratedDestinations(array(
          'path',
        ));
      }
      elseif ($this
        ->moduleExists('path')) {
        $this
          ->addUnmigratedSources(array(
          'path',
        ));
      }
    }
    if (module_exists('pathauto')) {
      $this
        ->addFieldMapping('pathauto')
        ->description('By default, disable in favor of migrated paths')
        ->defaultValue(0);
    }
  }

  /**
   * Query for the basic user data. Same query is used for all currently-supported
   * versions of Drupal.
   *
   * @return QueryConditionInterface
   */
  protected function query() {

    // Do not attempt to migrate the anonymous user row.
    $query = Database::getConnection('default', $this->sourceConnection)
      ->select('users', 'u')
      ->fields('u')
      ->condition('u.uid', 0, '>');
    return $query;
  }

  /**
   * Review a data row after fetch, returning FALSE to skip it.
   *
   * @param $row
   * @return bool
   */
  public function prepareRow($row) {
    if (parent::prepareRow($row) === FALSE) {
      return FALSE;
    }

    // On initial import, if this email address already exists, just map to the
    // existing uid and don't allow it to be deleted. When updating, we can
    // take the existing uid from the map instead of querying for it. Make sure
    // when updating an imported user that we don't apply this logic.
    if (empty($row->migrate_map_destid1)) {
      $new_uid = db_select('users', 'u')
        ->fields('u', array(
        'uid',
      ))
        ->condition('mail', $row->mail)
        ->execute()
        ->fetchField();

      // If we haven't mapped the admin account based on email address, map it
      // directly to the destination admin account.
      if (!$new_uid && $row->uid == 1) {
        $new_uid = 1;
      }
    }
    elseif ($row->migrate_map_needs_update == MigrateMap::STATUS_IGNORED && $row->migrate_map_rollback_action == MigrateMap::ROLLBACK_PRESERVE) {
      $new_uid = $row->migrate_map_destid1;
    }
    if (!empty($new_uid)) {
      $hash = isset($row->migrate_map_hash) ? $row->migrate_map_hash : NULL;
      $this->map
        ->saveIDMapping($row, array(
        $new_uid,
      ), MigrateMap::STATUS_IGNORED, MigrateMap::ROLLBACK_PRESERVE, $hash);
      $this->rollbackAction = MigrateMap::ROLLBACK_PRESERVE;
      return FALSE;
    }

    // Add the path to the source row, if relevant
    if ($this
      ->moduleExists('path')) {
      $path = $this->version
        ->getPath('user/' . $row->uid);
      if ($path) {
        $row->path = $path;
      }
    }

    // Pick up profile data.
    $this->version
      ->getSourceValues($row, $row->uid);

    // Populate the source roles
    if ($this->roleMigration) {
      $result = Database::getConnection('default', $this->sourceConnection)
        ->select('users_roles', 'ur')
        ->fields('ur', array(
        'rid',
      ))
        ->condition('uid', $row->uid)
        ->execute();
      foreach ($result as $role_row) {
        $row->roles[] = $role_row->rid;
      }
    }
    return TRUE;
  }

  /**
   * Implements Migration::prepare().
   *
   * @param $account
   * @param $row
   */
  public function prepare($account, $row) {

    // Unserialize data if necessary.
    if (!is_array($account->data) && !strncmp($account->data, 'a:', 2)) {
      $account->data = unserialize($account->data);
    }
  }

  /**
   * Actions to take after a user account has been saved.
   *
   * @param $account
   * @param $row
   */
  public function complete($account, $row) {

    // If we've migrated a picture, update its ownership
    if (isset($this->pictureMigration)) {
      if ($account->picture) {
        db_update('file_managed')
          ->fields(array(
          'uid' => $account->uid,
        ))
          ->condition('fid', $account->picture)
          ->execute();
      }
    }
  }

}

Members

Namesort descending Modifiers Type Description Overrides
DrupalMigration::$formatMappings protected property Map format mappings from the source system to the destination. Automated generation of these mappings is version-dependent (through Drupal 6 they were identified by numeric IDs, Drupal 7 introduced machine names).
DrupalMigration::$mapConnection protected property Controls what db connection the MigrateSQLMaps use.
DrupalMigration::$newOnly protected property Set to TRUE to suppress highwater marks or track_changes (i.e., to only import new items, skipping updated items, on subsequent imports).
DrupalMigration::$sourceConnection protected property Connection key for the DatabaseConnection holding the source Drupal installation.
DrupalMigration::$sourceFields protected property An array of available source fields, beyond those in the base query. Derived classes should populate this before calling the parent constructor.
DrupalMigration::$sourceOptions protected property Options to be passed to source constructors.
DrupalMigration::$sourceType protected property Source type (bundle), if any. 2
DrupalMigration::$sourceVersion protected property The major version of the Drupal install serving as the migration source, e.g. '6'.
DrupalMigration::$version protected property While much of the version-specific work can be done in the leaf classes, to share data and behavior among all classes for a given Drupal version we use this helper object.
DrupalMigration::mapFormat protected function Field mapping callback: translate an incoming format ID (through D6) or machine name (D7+) to a D7 format machine name.
DrupalMigration::moduleExists protected function Check to see if a given module is enabled in the source installation. @todo: move to DrupalVersion?
DrupalUserMigration::$pictureMigration protected property If there's a user picture migration, keep track of the machine name for dependency management and sourceMigration.
DrupalUserMigration::$roleMigration protected property If there's a user role migration, keep track of the machine name for dependency management and sourceMigration.
DrupalUserMigration::complete public function Actions to take after a user account has been saved. 1
DrupalUserMigration::prepare public function Implements Migration::prepare().
DrupalUserMigration::prepareRow public function Review a data row after fetch, returning FALSE to skip it. Overrides Migration::prepareRow 2
DrupalUserMigration::query protected function Query for the basic user data. Same query is used for all currently-supported versions of Drupal. Overrides DrupalMigration::query
DrupalUserMigration::__construct public function Overrides DrupalMigration::__construct 3
Migration::$allFieldMappings protected property All field mappings, with those retrieved from the database overriding those defined in code.
Migration::$codedFieldMappings protected property Field mappings retrieved from storage.
Migration::$counts protected property An array of counts. Initially used for cache hit/miss tracking.
Migration::$defaultRollbackAction protected property The default rollback action for this migration. Can be overridden on a per-row basis by setting $row->rollbackAction in prepareRow().
Migration::$destination protected property Destination object for the migration, derived from MigrateDestination.
Migration::$destinationValues protected property The object currently being constructed
Migration::$highwaterField protected property If present, an array with keys name and alias (optional). Name refers to the source columns used for tracking highwater marks. alias is an optional table alias.
Migration::$map protected property Map object tracking relationships between source and destination data
Migration::$needsUpdate public property Specify value of needs_update for current map row. Usually set by MigrateFieldHandler implementations.
Migration::$queuedMessages protected property Queue up messages that can't be safely saved (in particular, if they're generated in prepareRow().
Migration::$rollbackAction public property The rollback action to be saved for the current row.
Migration::$rollbackBatchSize protected property When performing a bulkRollback(), the maximum number of items to pass in a single call. Can be overridden in derived class constructor.
Migration::$source protected property Source object for the migration, derived from MigrateSource.
Migration::$sourceValues protected property The current data row retrieved from the source.
Migration::$storedFieldMappings protected property Field mappings defined in code.
Migration::$storedFieldMappingsRetrieved protected property
Migration::$subfieldDelimiter protected property
Migration::$systemOfRecord protected property
Migration::addFieldMapping public function Add a mapping for a destination field, specifying a source field and/or a default value. 1
Migration::addSimpleMappings public function Shortcut for adding several fields which have the same name on both source and destination sides.
Migration::addUnmigratedDestinations public function Shortcut for adding several destination fields which are to be explicitly not migrated.
Migration::addUnmigratedSources public function Shortcut for adding several source fields which are to be explicitly not migrated.
Migration::analyze public function Perform an analysis operation - report on field values in the source.
Migration::applyMappings protected function Apply field mappings to a data row received from the source, returning a populated destination object. 1
Migration::beginProcess protected function Override MigrationBase::beginProcess, to make sure the map/message tables are present. Overrides MigrationBase::beginProcess
Migration::checkStatus protected function Standard top-of-loop stuff, common between rollback and import - check for exceptional conditions, and display feedback.
Migration::createStubWrapper protected function If stub creation is enabled, try to create a stub and save the mapping.
Migration::currentSourceKey protected function Fetch the key array for the current source record.
Migration::deregisterMigration public static function Deregister a migration - remove all traces of it from the database (without touching any content which was created by this migration). Overrides MigrationBase::deregisterMigration
Migration::DESTINATION constant
Migration::endProcess public function Override MigrationBase::endProcess, to call post hooks. Note that it must be public to be callable as the shutdown function. Overrides MigrationBase::endProcess
Migration::errorCount public function Get the number of source records which failed to import. TODO: Doesn't yet account for informationals, or multiple errors for a source record.
Migration::getCodedFieldMappings public function
Migration::getDefaultRollbackAction public function
Migration::getDestination public function
Migration::getFieldMappings public function
Migration::getHighwaterField public function
Migration::getMap public function
Migration::getSource public function
Migration::getStoredFieldMappings public function
Migration::getSystemOfRecord public function
Migration::handleDedupe protected function For fields which require uniqueness, assign a new unique value if necessary.
Migration::handleSourceMigration protected function Look up a value migrated in another migration.
Migration::import protected function Perform an import operation - migrate items from source to destination.
Migration::importedCount public function Get the number of records successfully imported.
Migration::isComplete public function Reports whether this migration process is complete (i.e., all available source rows have been processed). Overrides MigrationBase::isComplete
Migration::itemOptionExceeded protected function Test whether we've exceeded the designated item limit.
Migration::loadFieldMappings public function Load any stored field mappings from the database.
Migration::messageCount public function Get the number of messages associated with this migration
Migration::onEmptyDestination protected function React when migration didn't failed but destination ids are empty.
Migration::onException protected function React when there is an exception
Migration::onMigrateException protected function React when there is a migrate exception
Migration::onSuccess protected function React when the migration has been successful.
Migration::postImport protected function
Migration::postRollback protected function
Migration::preImport protected function Default implementations of pre/post import/rollback methods. These call the destination methods (if they exist) - when overriding, always call parent::preImport() etc.
Migration::prepareKey public function Default implementation of prepareKey. This method is called from the source plugin immediately after retrieving the raw data from the source - by default, it simply assigns the key values based on the field names passed to MigrateSQLMap(). Override…
Migration::prepareUpdate public function Prepares this migration to run as an update - that is, in addition to unmigrated content (source records not in the map table) being imported, previously-migrated content will also be updated in place.
Migration::preRollback protected function
Migration::processedCount public function Get the number of source records processed.
Migration::progressMessage protected function Outputs a progress message, reflecting the current status of a migration process.
Migration::queueMessage public function Queue messages to be later saved through the map class.
Migration::registerMigration public static function Register a new migration process in the migrate_status table. This will generally be used in two contexts - by the class detection code for static (one instance per class) migrations, and by the module implementing dynamic (parameterized class)… Overrides MigrationBase::registerMigration
Migration::removeFieldMapping public function Remove any existing coded mappings for a given destination or source field.
Migration::rollback protected function Perform a rollback operation - remove migrated items from the destination.
Migration::saveFieldMappings public static function Record an array of field mappings to the database.
Migration::saveMessage public function Pass messages through to the map class. Overrides MigrationBase::saveMessage
Migration::saveQueuedMessages public function Save any messages we've queued up to the message table.
Migration::setDefaultRollbackAction public function
Migration::setDestination public function
Migration::setHighwaterField public function
Migration::setMap public function
Migration::setSource public function
Migration::setSystemOfRecord public function
Migration::setUpdate public function Set the specified row to be updated, if it exists.
Migration::SOURCE constant Indicate whether the primary system of record for this migration is the source, or the destination (Drupal). In the source case, migration of an existing object will completely replace the Drupal object with data from the source side. In the…
Migration::sourceCount public function Convenience function to return count of total source records
Migration::updateCount public function Get the number of records marked as needing update.
MigrationBase::$arguments protected property Arguments configuring a migration.
MigrationBase::$batchTimeLimit protected property A time limit in seconds appropriate to be used in a batch import. Defaults to 240.
MigrationBase::$currentMigration protected static property Track the migration currently running, so handlers can easily determine it without having to pass a Migration object everywhere.
MigrationBase::$dependencies protected property List of other Migration classes which should be imported before this one. E.g., a comment migration class would typically have node and user migrations as dependencies.
MigrationBase::$description protected property Detailed information describing the migration.
MigrationBase::$disableHooks protected property Any module hooks which should be disabled during migration processes.
MigrationBase::$displayFunction protected static property Name of a function for displaying feedback. It must take the message to display as its first argument, and a (string) message type as its second argument (see drush_log()).
MigrationBase::$emptyArgumentsWarning protected static property
MigrationBase::$enabled protected property Disabling a migration prevents it from running with --all, or individually without --force
MigrationBase::$group protected property A migration group object, used to collect related migrations.
MigrationBase::$groupArgumentWarning protected static property Have we already warned about obsolete constructor argumentss on this request?
MigrationBase::$issuePattern protected property If provided, an URL for an issue tracking system containing :id where the issue number will go (e.g., 'http://example.com/project/ticket/:id').
MigrationBase::$logHistory protected property Whether to maintain a history of migration processes in migrate_log
MigrationBase::$logID protected property Primary key of the current history record (inserted at the beginning of a process, to be updated at the end)
MigrationBase::$machineName protected property The machine name of this Migration object, derived by removing the 'Migration' suffix from the class name. Used to construct default map/message table names, displayed in drush migrate-status, key to migrate_status table...
MigrationBase::$mailSystem protected property An array to track 'mail_system' variable if disabled.
MigrationBase::$memoryLimit protected property The PHP memory_limit expressed in bytes.
MigrationBase::$memoryThreshold protected property The fraction of the memory limit at which an operation will be interrupted. Can be overridden by a Migration subclass if one would like to push the envelope. Defaults to 85%.
MigrationBase::$options protected property Save options passed to current operation
MigrationBase::$previousErrorHandler protected property If we set an error handler (during import), remember the previous one so it can be restored.
MigrationBase::$processing protected property Indicates that we are processing a rollback or import - used to avoid excess writes in endProcess()
MigrationBase::$showEncryptionWarning protected static property Track whether or not we've already displayed an encryption warning
MigrationBase::$starttime protected property When the current operation started.
MigrationBase::$status protected property Are we importing, rolling back, or doing nothing?
MigrationBase::$team protected property MigrateTeamMember objects representing people involved with this migration.
MigrationBase::$timeLimit protected property The PHP max_execution_time.
MigrationBase::$timeThreshold protected property The fraction of the time limit at which an operation will be interrupted. Can be overridden by a Migration subclass if one would like to push the envelope. Defaults to 90%.
MigrationBase::$total_processed protected property Number of "items" processed in the current migration process (whatever that means for the type of process)
MigrationBase::addArguments public function
MigrationBase::addHardDependencies public function
MigrationBase::addSoftDependencies public function
MigrationBase::currentMigration public static function
MigrationBase::decrypt public static function Decrypt an incoming value.
MigrationBase::decryptArguments public static function Make sure any arguments we want to be decrypted get decrypted.
MigrationBase::dependenciesComplete protected function Reports whether all (hard) dependencies have completed migration
MigrationBase::disableMailSystem public function Disables mail system to prevent emails from being sent during migrations.
MigrationBase::displayMessage public static function Output the given message appropriately (drush_print/drupal_set_message/etc.)
MigrationBase::encrypt public static function Encrypt an incoming value. Detects for existence of the Drupal 'Encrypt' module.
MigrationBase::encryptArguments public static function Make sure any arguments we want to be encrypted get encrypted.
MigrationBase::errorHandler public function Custom PHP error handler. TODO: Redundant with hook_watchdog?
MigrationBase::generateMachineName protected function The migration machine name is stored in the arguments. 1
MigrationBase::getArguments public function
MigrationBase::getDependencies public function
MigrationBase::getDescription public function
MigrationBase::getDisableHooks public function
MigrationBase::getEnabled public function
MigrationBase::getGroup public function
MigrationBase::getHardDependencies public function
MigrationBase::getHighwater public function Fetch the current highwater mark for updated content.
MigrationBase::getInstance public static function Return the single instance of the given migration.
MigrationBase::getIssuePattern public function
MigrationBase::getItemLimit public function
MigrationBase::getLastImported public function Retrieve the last time an import operation completed successfully.
MigrationBase::getLastThroughput public function Retrieve the last throughput for current Migration (items / minute).
MigrationBase::getMachineName public function
MigrationBase::getMessageLevelName public function Get human readable name for a message constant.
MigrationBase::getOption public function
MigrationBase::getSoftDependencies public function
MigrationBase::getStatus public function Check the current status of a migration.
MigrationBase::getTeam public function
MigrationBase::getTimeLimit public function
MigrationBase::handleException public function Takes an Exception object and both saves and displays it, pulling additional information on the location triggering the exception.
MigrationBase::incompleteDependencies public function Returns an array of the migration's dependencies that are incomplete.
MigrationBase::isDynamic Deprecated public static function 1
MigrationBase::machineFromClass protected static function Given only a class name, derive a machine name (the class name with the "Migration" suffix, if any, removed).
MigrationBase::memoryExceeded protected function Test whether we've exceeded the desired memory threshold. If so, output a message.
MigrationBase::MESSAGE_ERROR constant Message types to be passed to saveMessage() and saved in message tables. MESSAGE_INFORMATIONAL represents a condition that did not prevent the operation from succeeding - all others represent different severities of conditions resulting in a source…
MigrationBase::MESSAGE_INFORMATIONAL constant
MigrationBase::MESSAGE_NOTICE constant
MigrationBase::MESSAGE_WARNING constant
MigrationBase::processImport public function Perform an operation during the import phase
MigrationBase::processRollback public function Perform an operation during the rollback phase.
MigrationBase::resetStatus public function Reset the status of the migration to IDLE (to be used when the status gets stuck, e.g. if a process core-dumped)
MigrationBase::restoreMailSystem public function Restores the original saved mail system for migrations that require it.
MigrationBase::RESULT_COMPLETED constant Codes representing the result of a rollback or import process.
MigrationBase::RESULT_DISABLED constant
MigrationBase::RESULT_FAILED constant
MigrationBase::RESULT_INCOMPLETE constant
MigrationBase::RESULT_SKIPPED constant
MigrationBase::RESULT_STOPPED constant
MigrationBase::saveHighwater protected function Save the highwater mark for this migration (but not when using an idlist).
MigrationBase::saveMailSystem public function Saves the current mail system, or set a system default if there is none.
MigrationBase::setArguments public function
MigrationBase::setBatchTimeLimit public function Set the PHP time limit. This method may be called from batch callbacks before calling the processImport method.
MigrationBase::setDescription public function
MigrationBase::setDisplayFunction public static function
MigrationBase::setEnabled public function
MigrationBase::setHardDependencies public function
MigrationBase::setIssuePattern public function
MigrationBase::setSoftDependencies public function
MigrationBase::setTeam public function
MigrationBase::staticInitialize public static function Initialize static members, before any class instances are created.
MigrationBase::STATUS_DISABLED constant
MigrationBase::STATUS_IDLE constant Codes representing the current status of a migration, and stored in the migrate_status table.
MigrationBase::STATUS_IMPORTING constant
MigrationBase::STATUS_ROLLING_BACK constant
MigrationBase::STATUS_STOPPING constant
MigrationBase::stopProcess public function Signal that any current import or rollback process should end itself at the earliest opportunity
MigrationBase::timeExceeded protected function Test whether we're approaching the PHP time limit.
MigrationBase::timeOptionExceeded protected function Test whether we've exceeded the designated time limit.
MigrationBase::timestamp public static function Convert an incoming string (which may be a UNIX timestamp, or an arbitrarily-formatted date/time string) to a UNIX timestamp.