summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNathaniel Catchpole2017-12-21 10:49:53 (GMT)
committerNathaniel Catchpole2017-12-21 10:50:42 (GMT)
commit4851f311e25ef59dc0b0742fe05e7560e4b1b79d (patch)
treee2b10a38c4f99d152f5d72dcc59b7b4e232b45f8
parentbe64202643a512a694c3bcb48d6fc6d38970abe3 (diff)
Issue #2862671 by masipila, Jo Fitzgerald, kleog, phenaproxima, quietone: Add documentation to SqlBase source plugin
-rw-r--r--core/modules/migrate/src/Plugin/migrate/source/SqlBase.php63
1 files changed, 38 insertions, 25 deletions
diff --git a/core/modules/migrate/src/Plugin/migrate/source/SqlBase.php b/core/modules/migrate/src/Plugin/migrate/source/SqlBase.php
index 35ab8ab..08653b2 100644
--- a/core/modules/migrate/src/Plugin/migrate/source/SqlBase.php
+++ b/core/modules/migrate/src/Plugin/migrate/source/SqlBase.php
@@ -17,35 +17,48 @@ use Symfony\Component\DependencyInjection\ContainerInterface;
/**
* Sources whose data may be fetched via a database connection.
*
- * Database configuration, which may appear either within the source plugin
- * configuration or in state, is structured as follows:
+ * Available configuration keys:
+ * - database_state_key: (optional) Name of the state key which contains an
+ * array with database connection information.
+ * - key: (optional) The database key name. Defaults to 'migrate'.
+ * - target: (optional) The database target name. Defaults to 'default'.
+ * - batch_size: (optional) Number of records to fetch from the database during
+ * each batch. If omitted, all records are fetched in a single query.
+ * - ignore_map: (optional) Source data is joined to the map table by default.
+ * If set to TRUE, the map table will not be joined.
*
- * 'key' - The database key name (defaults to 'migrate').
- * 'target' - The database target name (defaults to 'default').
- * 'database' - Database connection information as accepted by
- * Database::addConnectionInfo(). If not present, the key/target is assumed
- * to already be defined (e.g., in settings.php).
+ * For other optional configuration keys inherited from the parent class, refer
+ * to \Drupal\migrate\Plugin\migrate\source\SourcePluginBase.
*
- * This configuration info is obtained in the following order:
+ * About the source database determination:
+ * - If the source plugin configuration contains 'database_state_key', its value
+ * is taken as the name of a state key which contains an array with the
+ * database configuration.
+ * - Otherwise, if the source plugin configuration contains 'key', the database
+ * configuration with that name is used.
+ * - If both 'database_state_key' and 'key' are omitted in the source plugin
+ * configuration, the database connection named 'migrate' is used by default.
+ * - If all of the above steps fail, RequirementsException is thrown.
*
- * 1. If the source plugin configuration contains a key 'database_state_key',
- * its value is taken as the name of a state key which contains an array
- * with the above database configuration.
- * 2. Otherwise, if the source plugin configuration contains 'key', the above
- * database configuration is obtained directly from the plugin configuration.
- * 3. Otherwise, if the state 'migrate.fallback_state_key' exists, its value is
- * taken as the name of a state key which contains an array with the above
- * database configuration.
- * 4. Otherwise, if a connection named 'migrate' exists, that is used as the
- * database connection.
- * 5. Otherwise, RequirementsException is thrown.
+ * Drupal Database API supports multiple database connections. The connection
+ * parameters are defined in $databases array in settings.php or
+ * settings.local.php. It is also possible to modify the $databases array in
+ * runtime. For example, Migrate Drupal, which provides the migrations from
+ * Drupal 6 / 7, asks for the source database connection parameters in the UI
+ * and then adds the $databases['migrate'] connection in runtime before the
+ * migrations are executed.
*
- * It is strongly recommended that database connections be explicitly defined
- * via 'database_state_key' or in the source plugin configuration. Defining
- * migrate.fallback_state_key or a 'migrate' connection affects not only any
- * migrations intended to use that particular connection, but all
- * SqlBase-derived source plugins which do not have explicit database
- * configuration.
+ * As described above, the default source database is $databases['migrate']. If
+ * the source plugin needs another source connection, the database connection
+ * parameters should be added to the $databases array as, for instance,
+ * $databases['foo']. The source plugin can then use this connection by setting
+ * 'key' to 'foo' in its configuration.
+ *
+ * For a complete example on migrating data from an SQL source, refer to
+ * https://www.drupal.org/docs/8/api/migrate-api/migrating-data-from-sql-source
+ *
+ * @see https://www.drupal.org/docs/8/api/database-api
+ * @see \Drupal\migrate_drupal\Plugin\migrate\source\DrupalSqlBase
*/
abstract class SqlBase extends SourcePluginBase implements ContainerFactoryPluginInterface, RequirementsInterface {