Refinery
![Software License][ico-license]
![Coverage Status][ico-coverage]
, (*1)
Refinery is a console-based package of Migrations Class for the Codeigniter 3. It uses the Describe package for retrieving the database tables for creating database migrations., (*2)
Installation
From an existing Codeigniter 3 project, the Refinery package can be installed through Composer:, (*3)
``` bash
$ composer require rougin/refinery --dev, (*4)
``` json
// ciacme/composer.json
{
// ...
"require-dev":
{
"mikey179/vfsstream": "1.6.*",
"phpunit/phpunit": "4.* || 5.* || 9.*",
"rougin/refinery": "~0.4"
}
}
Then configure the project's database connectivity settings:, (*5)
``` php
// ciacme/application/config/database.php, (*6)
// ..., (*7)
$db['default'] = array(
'dsn' => '',
'hostname' => 'localhost',
'username' => '',
'password' => '',
'database' => '',
'dbdriver' => 'mysqli',, (*8)
// ...
);, (*9)
> [!NOTE]
> Although using database connection is not required in using `Refinery`, this is only applicable when creating migration files based on an existing database. Please see [Creating from database](https://github.com/rougin/refinery?tab=readme-ov-file#creating-from-database) below for its usage.
## Basic Usage
### Creating migration files
To create a new database migration, kindly run the `create` command:
``` bash
$ vendor/bin/refinery create create_users_table
[PASS] "20241019044009_create_users_table.php" successfully created!
``` php
// ciacme/application/migrations/20241019044009_create_users_table.php, (*10)
use Rougin\Refinery\Migration;, (*11)
class Migration_create_users_table extends Migration
{
/**
* @return void
*/
public function up()
{
$data = array('id' => array());
$data['id']['type'] = 'integer';
$data['id']['auto_increment'] = true;
$data['id']['constraint'] = 10;
$this->dbforge->add_field($data);
$this->dbforge->add_key('id', true);, (*12)
$this->dbforge->create_table('users');
}
/**
* @return void
*/
public function down()
{
$this->dbforge->drop_table('users');
}
}, (*13)
> [!NOTE]
> * The `Migration` class under `Refinery` is directly extended on `CI_Migration`.
> * The created file will be in `migrations` directory under `application`. If it does not exists, `Refinery` will automatically create the specified directory.
When creating database migrations, `Refinery` will try to guess the expected output of `up` and `down` methods of a migration file based on its name (e.g., `add_name_in_users_table`):
```bash
$ vendor/bin/refinery create add_name_in_users_table
"20241019044035_add_name_in_users_table.php" has been created.
``` php
// ciacme/application/migrations/20241019044035_add_name_in_users_table.php, (*14)
use Rougin\Refinery\Migration;, (*15)
class Migration_add_name_in_users_table extends Migration
{
/**
* @return void
*/
public function up()
{
$data = array('name' => array());
$data['name']['type'] = 'varchar';
$data['name']['auto_increment'] = false;
$data['name']['constraint'] = 100;
$data['name']['default'] = null;
$data['name']['null'] = true;
$data['name']['unsigned'] = false;
$this->dbforge->add_column('users', $data);
}, (*16)
/**
* @return void
*/
public function down()
{
$this->dbforge->drop_column('users', 'name');
}
}, (*17)
Please see the accepted keywords below when creating database migration files:
| Keyword | Description | Example |
|----------|------------------------------------------------|------------------------------|
| `add` | Adds new column to a table | `add_name_in_users_table` |
| `create` | Creates new table with `id` as the primary key | `create_users_table` |
| `delete` | Deletes a column from a table | `delete_name_in_users_table` |
| `modify` | Updates a column of a table | `modify_name_in_users_table` |
### Running the migrations
Kindly use the `migrate` command to use the files for database migrations:
``` bash
$ vendor/bin/refinery migrate
[INFO] Migrating "create_users_table"...
[PASS] "create_users_table" migrated!
[INFO] Migrating "add_name_in_users_table"...
[PASS] "add_name_in_users_table" migrated!
When running this command, the target timestamp (--target) will always be the latest file in the migrations directory if not specified (e.g., add_name_in_users_table). Use the --target option to migrate to a specific version:, (*18)
``` bash
$ vendor/bin/refinery migrate --target=20241019044009
[INFO] Migrating "create_users_table"...
[PASS] "create_users_table" migrated!, (*19)
To rollback a database, kindly use the `rollback` command:
``` bash
$ vendor/bin/refinery rollback
[INFO] Rolling back "add_name_in_users_table"...
[PASS] "add_name_in_users_table" rolled back!
[!NOTE]
Without a --target option, the rollback will only revert to its previous version (e.g., create_users_table)., (*20)
To reset back the database schema to version 0, the reset command can be used:, (*21)
``` bash
$ vendor/bin/refinery migrate
[INFO] Migrating "add_name_in_users_table"...
[PASS] "add_name_in_users_table" migrated!, (*22)
$ vendor/bin/refinery reset
[INFO] Rolling back "add_name_in_users_table"...
[PASS] "add_name_in_users_table" rolled back!
[INFO] Rolling back "create_users_table"...
[PASS] "create_users_table" rolled back!, (*23)
## Creating from database
`Refinery` also allows to create a database migration based on the existing database table. Prior in creating its database migration, kindly ensure that the specified table already exists in the database schema:
``` sql
CREATE TABLE IF NOT EXISTS `users` (
`id` int NOT NULL AUTO_INCREMENT,
`name` varchar(100) DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3;
After checking the database table exists, run the same create command with the --from-database option:, (*24)
``` bash
$ vendor/bin/refinery create create_users_table --from-database
"20241019044729_create_users_table.php" has been created., (*25)
``` php
// ciacme/application/migrations/20241019044729_create_users_table.php
use Rougin\Refinery\Migration;
class Migration_create_users_table extends Migration
{
/**
* @return void
*/
public function up()
{
$data = array('id' => array());
$data['id']['type'] = 'integer';
$data['id']['auto_increment'] = true;
$data['id']['constraint'] = 10;
$this->dbforge->add_field($data);
$this->dbforge->add_key('id', true);
$data = array('name' => array());
$data['name']['type'] = 'varchar';
$data['name']['auto_increment'] = false;
$data['name']['constraint'] = 100;
$data['name']['default'] = null;
$data['name']['null'] = true;
$data['name']['unsigned'] = false;
$this->dbforge->add_field($data);
$this->dbforge->create_table('users');
}
/**
* @return void
*/
public function down()
{
$this->dbforge->drop_table('users');
}
}
[!NOTE]
The --from-database option only exists when creating files under the create_*_table prefix., (*26)
Creating sequential migrations
By default, Refinery uses a timestamp prefix as its numbering style when creating migration files. To change it to a sequential numbering, kindly update the value of migration_type in the config/migration.php to sequential:, (*27)
``` php
// ciacme/application/config/migration.php, (*28)
/*
|--------------------------------------------------------------------------
| Migration Type
|--------------------------------------------------------------------------
|
| Migration file names may be based on a sequential identifier or on
| a timestamp. Options are:
|
| 'sequential' = Sequential migration naming (001_add_blog.php)
| 'timestamp' = Timestamp migration naming (20121031104401_add_blog.php)
| Use timestamp format YYYYMMDDHHIISS.
|
| Note: If this configuration value is missing the Migration library
| defaults to 'sequential' for backward compatibility with CI2.
|
*/
$config['migration_type'] = 'sequential';, (*29)
Then run the `create` command to generate a migration file in sequential migration:
``` bash
$ vendor/bin/refinery create create_users_table
[PASS] "001_create_users_table.php" successfully created!
Alternatively, the --sequential option can also be added in the create command to update the said configuration:, (*30)
``` bash
$ vendor/bin/refinery create add_name_in_users_table --sequential
[PASS] "002_add_name_in_users_table.php" successfully created!, (*31)
> [!NOTE]
> When using the `--sequential` option, the `migration_type` in the `config/migration.php` is also set as `sequential`.
## Using `refinery.yml`
`Refinery` currently works out of the box after the configuration based on `Installation`. However, using a `refinery.yml` can be used for complex setups like specifying the new application path:
``` yaml
# refinery.yml
app_path: %%CURRENT_DIRECTORY%%
To create a refinery.yml, simply run the initialize command:, (*32)
``` bash
$ vendor/bin/refinery initialize
[PASS] "refinery.yml" added successfully!, (*33)
> [!NOTE]
> `%%CURRENT_DIRECTORY%%` is a placeholder variable which is the current directory of `refinery.yml`.
### `app_path`
This property specifies the `application` directory. It may updated to any directory (e.g., `ciacme/application`, `ciacme/config`, etc.) as long it can detect the `config/config.php` file from the defined directory:
``` yaml
# refinery.yml
app_path: %%CURRENT_DIRECTORY%%/Sample
# ...
[!NOTE]
Refinery will try to check the path specified in app_path if it is a valid Codeigniter 3 project. Then it will perform another check if the application directory exists or if the config directory can be accessed directly from the directory defined in app_path., (*34)
Changelog
Please see CHANGELOG for more information what has changed recently., (*35)
Testing
bash
$ composer test, (*36)
Credits
License
The MIT License (MIT). Please see LICENSE for more information., (*37)
Wallogit.com
