| /** | |
| * Matomo - free/libre analytics platform | |
| * | |
| * @link https://matomo.org | |
| * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later | |
| */ | |
| namespace Piwik\Updater\Migration\Db; | |
| use Piwik\Common; | |
| use Piwik\Container\StaticContainer; | |
| /** | |
| * Provides database migrations. | |
| * | |
| * @api | |
| */ | |
| class Factory | |
| { | |
| /** | |
| * @var \Piwik\Container\Container | |
| */ | |
| private $container; | |
| /** | |
| * @ignore | |
| */ | |
| public function __construct() | |
| { | |
| $this->container = StaticContainer::getContainer(); | |
| } | |
| /** | |
| * Performs a custom SQL query during the update. | |
| * | |
| * Example: | |
| * $factory->sql("DELETE * FROM table_name WHERE plugin_name = 'MyPluginName'"); | |
| * | |
| * @param string $sql The SQL query that should be executed. Make sure to prefix a table name via | |
| * {@link Piwik\Commin::prefixTable()}. | |
| * @param int|int[] $errorCodesToIgnore Any given MySQL server error code will be ignored. For a list of all | |
| * possible error codes have a look at {@link \Piwik\Updater\Migration\Db}. | |
| * If no error should be ignored use an empty array or `false`. | |
| * @return Sql | |
| */ | |
| public function sql($sql, $errorCodesToIgnore = array()) | |
| { | |
| if ($errorCodesToIgnore === false) { | |
| $errorCodesToIgnore = array(); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\Sql', array( | |
| 'sql' => $sql, 'errorCodesToIgnore' => $errorCodesToIgnore, | |
| )); | |
| } | |
| /** | |
| * Performs a custom SQL query that uses bound parameters during the update. | |
| * | |
| * You can replace values with a question mark and then pass the actual value via `$bind` for better security. | |
| * | |
| * Example: | |
| * $factory->boundSql('DELETE * FROM table_name WHERE idsite = ?, array($idSite = 1)); | |
| * | |
| * @param string $sql The SQL query that should be executed. Make sure to prefix a table name via | |
| * {@link Piwik\Commin::prefixTable()}. | |
| * @param array $bind An array of values that need to be replaced with the question marks in the SQL query. | |
| * @param int|int[] $errorCodesToIgnore Any given MySQL server error code will be ignored. For a list of all | |
| * possible error codes have a look at {@link \Piwik\Updater\Migration\Db}. | |
| * If no error should be ignored use `false`. | |
| * @return BoundSql | |
| */ | |
| public function boundSql($sql, $bind, $errorCodesToIgnore = array()) | |
| { | |
| if ($errorCodesToIgnore === false) { | |
| $errorCodesToIgnore = array(); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\BoundSql', array( | |
| 'sql' => $sql, 'errorCodesToIgnore' => $errorCodesToIgnore, 'bind' => $bind, | |
| )); | |
| } | |
| /** | |
| * Creates a new database table. | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param array $columnNames An array of column names and their type they should use. For example: | |
| * array('column_name_1' => 'VARCHAR(200) NOT NULL', 'column_name_2' => 'INT(10) DEFAULT 0') | |
| * @param string|string[] $primaryKey Optional. One or multiple columns that shall define the primary key. | |
| * @return CreateTable | |
| */ | |
| public function createTable($table, $columnNames, $primaryKey = array()) | |
| { | |
| $table = $this->prefixTable($table); | |
| if (!empty($primaryKey) && !is_array($primaryKey)) { | |
| $primaryKey = array($primaryKey); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\CreateTable', array( | |
| 'table' => $table, 'columnNames' => $columnNames, 'primaryKey' => $primaryKey, | |
| )); | |
| } | |
| /** | |
| * Drops an existing database table. | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @return DropTable | |
| */ | |
| public function dropTable($table) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\DropTable', array( | |
| 'table' => $table, | |
| )); | |
| } | |
| /** | |
| * Adds a new database table column to an existing table. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string $columnName The name of the column that shall be added, eg 'my_column_name'. | |
| * @param string $columnType The column type it should have, eg 'VARCHAR(200) NOT NULL'. | |
| * @param string|null $placeColumnAfter If specified, the added column will be added after this specified column | |
| * name. If you specify a column be sure it actually exists and can be added | |
| * after this column. | |
| * @return AddColumn | |
| */ | |
| public function addColumn($table, $columnName, $columnType, $placeColumnAfter = null) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\AddColumn', array( | |
| 'table' => $table, 'columnName' => $columnName, 'columnType' => $columnType, 'placeColumnAfter' => $placeColumnAfter, | |
| )); | |
| } | |
| /** | |
| * Adds multiple new database table columns to an existing table at once. | |
| * | |
| * Adding multiple columns at the same time can lead to performance improvements compared to adding each new column | |
| * separately. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param array $columns An array of column name to column type pairs, | |
| * eg array('my_column_name' => 'VARCHAR(200) NOT NULL', 'column2' => '...') | |
| * @param string|null $placeColumnAfter If specified, the first added column will be added after this specified column | |
| * name. All following columns will be added after the previous specified in | |
| * $columns. If you specify a column be sure it actually exists and can be added | |
| * after this column. | |
| * @return AddColumns | |
| */ | |
| public function addColumns($table, $columns, $placeColumnAfter = null) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\AddColumns', array( | |
| 'table' => $table, 'columns' => $columns, 'placeColumnAfter' => $placeColumnAfter, | |
| )); | |
| } | |
| /** | |
| * Drops an existing database table column. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string $columnName The name of the column that shall be dropped, eg 'my_column_name'. | |
| * @return DropColumn | |
| */ | |
| public function dropColumn($table, $columnName) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\DropColumn', array( | |
| 'table' => $table, 'columnName' => $columnName, | |
| )); | |
| } | |
| /** | |
| * Drops an existing database table column. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param array $columnNames An array of column names that should be dropped eg ['column1', 'column2']. | |
| * @return DropColumns | |
| */ | |
| public function dropColumns($table, $columnNames) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\DropColumns', array( | |
| 'tableName' => $table, 'columnNames' => $columnNames, | |
| )); | |
| } | |
| /** | |
| * Changes the column name and column type of an existing database table column. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string $oldColumnName The current name of the column that shall be renamed/changed, eg 'column_name'. | |
| * @param string $newColumnName The new name of the column, eg 'new_column_name'. | |
| * @param string $columnType The updated type the new column should have, eg 'VARCHAR(200) NOT NULL'. | |
| * | |
| * @return ChangeColumn | |
| */ | |
| public function changeColumn($table, $oldColumnName, $newColumnName, $columnType) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\ChangeColumn', array( | |
| 'table' => $table, 'oldColumnName' => $oldColumnName, | |
| 'newColumnName' => $newColumnName, 'columnType' => $columnType, | |
| )); | |
| } | |
| /** | |
| * Changes the type of an existing database table column. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string $columnName The name of the column that shall be changed, eg 'my_column_name'. | |
| * @param string $columnType The updated type the column should have, eg 'VARCHAR(200) NOT NULL'. | |
| * | |
| * @return ChangeColumnType | |
| */ | |
| public function changeColumnType($table, $columnName, $columnType) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\ChangeColumnType', array( | |
| 'table' => $table, 'columnName' => $columnName, 'columnType' => $columnType, | |
| )); | |
| } | |
| /** | |
| * Changes the type of multiple existing database table columns at the same time. | |
| * | |
| * Changing multiple columns at the same time can lead to performance improvements compared to changing the type | |
| * of each column separately. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param array $columns An array of column name to column type pairs, | |
| * eg array('my_column_name' => 'VARCHAR(200) NOT NULL', 'column2' => '...') | |
| * | |
| * @return ChangeColumnTypes | |
| */ | |
| public function changeColumnTypes($table, $columns) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\ChangeColumnTypes', array( | |
| 'table' => $table, 'columns' => $columns, | |
| )); | |
| } | |
| /** | |
| * Adds an index to an existing database table. | |
| * | |
| * This is equivalent to an `ADD INDEX indexname (column_name_1, column_name_2)` in SQL. | |
| * It adds a normal index, no unique index. | |
| * | |
| * Note: If no indexName is specified, it will automatically generate a name for this index if which is basically: | |
| * `'index_' . implode('_', $columnNames)`. If a column name is eg `column1(10)` then only the first part (`column1`) | |
| * will be used. For example when using columns `array('column1', 'column2(10)')` then the index name will be | |
| * `index_column1_column2`. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string[]|string $columnNames Either one or multiple column names, eg array('column_name_1', 'column_name_2'). | |
| * A column name can be appended by a number bracket eg "column_name_1(10)". | |
| * @param string $indexName If specified, the given index name will be used instead of the automatically generated one. | |
| * @return AddIndex | |
| */ | |
| public function addIndex($table, $columnNames, $indexName = '') | |
| { | |
| $table = $this->prefixTable($table); | |
| if (!is_array($columnNames)) { | |
| $columnNames = array($columnNames); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\AddIndex', array( | |
| 'table' => $table, 'columnNames' => $columnNames, 'indexName' => $indexName, | |
| )); | |
| } | |
| /** | |
| * Adds a unique key to an existing database table. | |
| * | |
| * This is equivalent to an `ADD UNIQUE KEY indexname (column_name_1, column_name_2)` in SQL. | |
| * | |
| * Note: If no indexName is specified, it will automatically generate a name for this index if which is basically: | |
| * `'index_' . implode('_', $columnNames)`. If a column name is eg `column1(10)` then only the first part (`column1`) | |
| * will be used. For example when using columns `array('column1', 'column2(10)')` then the index name will be | |
| * `index_column1_column2`. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string[]|string $columnNames Either one or multiple column names, eg array('column_name_1', 'column_name_2'). | |
| * A column name can be appended by a number bracket eg "column_name_1(10)". | |
| * @param string $indexName If specified, the given unique key name will be used instead of the automatically generated one. | |
| * @return AddIndex | |
| */ | |
| public function addUniqueKey($table, $columnNames, $indexName = '') | |
| { | |
| $table = $this->prefixTable($table); | |
| if (!is_array($columnNames)) { | |
| $columnNames = array($columnNames); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\AddUniqueKey', array( | |
| 'table' => $table, 'columnNames' => $columnNames, 'indexName' => $indexName, | |
| )); | |
| } | |
| /** | |
| * Drops an existing index from a database table. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string $indexName The name of the index that shall be dropped. | |
| * @return DropIndex | |
| */ | |
| public function dropIndex($table, $indexName) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\DropIndex', array( | |
| 'table' => $table, 'indexName' => $indexName, | |
| )); | |
| } | |
| /** | |
| * Drops an existing index from a database table. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @return DropPrimaryKey | |
| */ | |
| public function dropPrimaryKey($table) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\DropPrimaryKey', array( | |
| 'table' => $table, | |
| )); | |
| } | |
| /** | |
| * Adds a primary key to an existing database table. | |
| * | |
| * This is equivalent to an `ADD PRIMARY KEY(column_name_1, column_name_2)` in SQL. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string[]|string $columnNames Either one or multiple column names, eg array('column_name_1', 'column_name_2') | |
| * @return AddPrimaryKey | |
| */ | |
| public function addPrimaryKey($table, $columnNames) | |
| { | |
| $table = $this->prefixTable($table); | |
| if (!is_array($columnNames)) { | |
| $columnNames = array($columnNames); | |
| } | |
| return $this->container->make('Piwik\Updater\Migration\Db\AddPrimaryKey', array( | |
| 'table' => $table, 'columnNames' => $columnNames, | |
| )); | |
| } | |
| /** | |
| * Inserts a new record / row into an existing database table. | |
| * | |
| * Make sure to specify all columns that need to be defined in order to insert a value successfully. There could | |
| * be for example columns that are not nullable and therefore need a value. | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param array $columnValuePairs An array containing column => value pairs. For example: | |
| * array('column_name_1' => 'value1', 'column_name_2' => 'value2') | |
| * @return Insert | |
| */ | |
| public function insert($table, $columnValuePairs) | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\Insert', array( | |
| 'table' => $table, 'columnValuePairs' => $columnValuePairs, | |
| )); | |
| } | |
| /** | |
| * Performs a batch insert into a specific table using either LOAD DATA INFILE or plain INSERTs, | |
| * as a fallback. On MySQL, LOAD DATA INFILE is 20x faster than a series of plain INSERTs. | |
| * | |
| * Please note that queries for batch inserts are currently not shown to an end user and should therefore not be | |
| * returned in an `Updates::getMigrations` method. Instead it needs to be execute directly in `Updates::doUpdate` | |
| * via `$updater->executeMigration($factory->dbBatchInsert(...));` | |
| * | |
| * @param string $table Unprefixed database table name, eg 'log_visit'. | |
| * @param string[] $columnNames An array of unquoted column names, eg array('column_name1', 'column_name_2') | |
| * @param array $values An array of data to be inserted, eg array(array('row1column1', 'row1column2'),array('row2column1', 'row2column2')) | |
| * @param bool $throwException Whether to throw an exception that was caught while trying LOAD DATA INFILE, or not. | |
| * @param string $charset The charset to use, defaults to utf8 | |
| * @return BatchInsert | |
| */ | |
| public function batchInsert($table, $columnNames, $values, $throwException = false, $charset = 'utf8') | |
| { | |
| $table = $this->prefixTable($table); | |
| return $this->container->make('Piwik\Updater\Migration\Db\BatchInsert', array( | |
| 'table' => $table, 'columnNames' => $columnNames, 'values' => $values, | |
| 'throwException' => $throwException, 'charset' => $charset, | |
| )); | |
| } | |
| private function prefixTable($table) | |
| { | |
| return Common::prefixTable($table); | |
| } | |
| } | |