Skip to content

Commit

Permalink
Merge pull request #2 from myaghobi/2.0
Browse files Browse the repository at this point in the history
2.0
  • Loading branch information
myaaghubi committed Jul 6, 2021
2 parents ef0b0cd + f426c59 commit d2451af
Show file tree
Hide file tree
Showing 14 changed files with 12,389 additions and 922 deletions.
94 changes: 25 additions & 69 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,25 @@
# F3-Migrations
F3-Migrations is a database helper plugin for the [Fat-Free Framework](http://github.com/bcosca/fatfree).
It's something like version control for the sql databases. Every time you have to make some changes manually in your database, you can make a `MigrationCase` class in the `migrations` directory, and the `Migrations` will handle that.
It's something like version control for the sql databases. Every time you have to make some changes manually in your database, you can make a `MigrationCase`, and the plugin will handle that.


- [F3-Migrations](#f3-migrations)
- [Installation](#installation)
- [Operation and basic usage](#operation-and-basic-usage)
- [Instantiate](#instantiate)
- [First migration case](#first-migration-case)
- [Migrate](#migrate)
- [First migration](#first-migration)
- [Config](#config)
- [Logging](#logging)
- [CLI mode](#cli-mode)
- [Migration cases](#migration-cases)
- [Filename](#filename)
- [Content](#content)
- [Upgrade](#upgrade)
- [License](#license)

## Installation

If you use composer, run the below code:

```
composer require myaghobi/f3-migrations
composer require `myaghobi/f3-migrations:2.0.x-dev`
```
For manual installation:
1. Copy the content of `lib/` folder into your `lib/` folder.
Expand All @@ -32,17 +29,19 @@ For manual installation:

## Operation and basic usage

The plugin provides a simple web interface, consists of 3 routes that will auto add to your app:
The plugin provides a simple web interface, consists of 4 routes that will auto add to your app:

* `GET /migrations` displays the web interface
* `GET /migrations/@action` triggers an action
* `GET /migrations/@action/@target` specific target version for the action
* `GET /migrations/theme/@type/@file` to retrive css/js files if you have stored the UI dir in non-web-accessible path

Also, it will create a table in your database named `migrations` to handle migrations.

### Instantiate

Instantiate the `Migrations` class before `f3->run()`. The plugin works if `DEBUG>=3`, otherwise, it goes disable because of security issues and to get no resource usage. Also to work with `Migrations` you need an active SQL connection:
Instantiate the `Migrations` class before `f3->run()`. The plugin works if `DEBUG>=3`, otherwise, it goes disable because of security issues and to get no resource usage.
To work with `Migrations` you need an active SQL connection:

```php
// require('vendor/autoload.php');
Expand All @@ -53,26 +52,27 @@ $f3=require('lib/base.php');
// MySQL, SQLite, PostgreSQL & SQL Server are supported
$db = new \DB\SQL('mysql:host=localhost;port=3306;dbname='.$DBName, $user, $pass);
...
\DB\SQL\Migrations::instance($db);
\DB\MIGRATIONS\Migrations::instance($db);
$f3->run();
```

### First migration case
### First migration

Make your first migration case by creating a file named `migration_case_1.0.0.php` in `lib/db/migrations`(default path) contains a class extended of `\DB\SQL\MigrationCase`.

### Migrate

Call `yourAppPublicUrl/migrations` in browser and use `migrate`.
1. Make sure the path of your cases directory be exists and secure.
2. Call `yourAppPublicUrl/migrations` in browser.
3. Use `makecase` action to make your first migration case.
4. Call `migrate` action.


### Config
This plugin is configurable via config file:
``` ini
[migrations]
ENABLE=true
; PATH relative to `lib/` folder
PATH=db/migrations
; PATH relative to `index.php`
PATH=../migrations
SHOW_BY_VERSOIN=true
CASE_PREFIX=migration_case_
LOG=true
```
The above config is the default, you can ignore/remove each one you don't need to change.
Expand All @@ -88,61 +88,17 @@ Just run the below code:
php index.php /migrations
```

## Migration cases

### Filename
## Upgrade

The version of cases is a positive(non-zero) and not duplicated number with a max length of 14, such as a timestamp or version number(separated with dots).
Also, you can add your description after the vesrion `migration_case_{version}_{description}.php`.
1. First update the plugin via composer or manually.
2. Make sure the path of migration cases be exists because in this version the path is relative to `index.php`.
3. Make a backup of your DB and migration cases.
4. Call `upgrademc` action to update the old migration cases.

Some correct examples:
```
migration_case_1.0.0.php
migration_case_1.0.0_producst_table.php
migration_case_1603283078427_producst_table2.php
```
Some incorrect examples:
```
migration_producst_table_1.0.0.php
migration_case_1_0_0.php
migration_case_0.php
migration_case.php
```

### Content

An example of the content for a migration case:
```php
<?php
// the class name can be duplicate
class CreateProductsTable extends \DB\SQL\MigrationCase {
// this method will call on upgrade
public function up($f3, $db, $schema) {
// your cods here
// https://github.com/ikkez/f3-schema-builder#create-tables
$table = $schema->createTable('products');
$table->addColumn('title')->type($schema::DT_VARCHAR128);
$table->addColumn('description')->type($schema::DT_TEXT);
$table->build();

// return TRUE when the upgrade be successful
return true;
}

// this method will call on downgrade
public function down($f3, $db, $schema) {
// your cods here
$schema->dropTable('products');

// return TRUE when the downgrade be successful
return true;
}
}
?>
```
Finally call `fresh` action.

## License

You are allowed to use this plugin under the terms of the GNU General Public License version 3 or later.

Copyright (C) 2020 Mohammad Yaghobi
Copyright (C) 2021 Mohammad Yaghobi
5 changes: 3 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
"f3-migrations",
"fat-free-plugin",
"fat-free-framework",
"sql-database",
"database-migration"
"sql",
"database",
"migration"
],
"homepage": "https://github.com/myaghobi/f3-migrations",
"license": "GPL-3.0",
Expand Down
47 changes: 47 additions & 0 deletions lib/db/migrations/MigrationCase.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?php

/**
* @package F3 Migrations, MigrationCase
* @version 2.0.1
* @link http://github.com/myaghobi/F3-Migrations Github
* @author Mohammad Yaghobi <[email protected]>
* @copyright Copyright (c) 2021, Mohammad Yaghobi
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3
*/

namespace DB\MIGRATIONS;

class MigrationCase {
/**
* this method will call on upgrade
*
* @param object $f3
* @param object $db
* @param object $schema
* @return bool
*/
public function up($f3, $db, $schema) {
// your cods here

// return TRUE when the upgrade be successful
return true;
}


/**
* this method will call on upgrade
*
* @param object $f3
* @param object $db
* @param object $schema
* @return bool
*/
public function down($f3, $db, $schema) {
// your cods here

// return TRUE when the downgrade be successful
return true;
}
}

?>
94 changes: 94 additions & 0 deletions lib/db/migrations/MigrationCaseItem.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<?php

/**
* @package F3 Migrations, MigrationCaseItem
* @version 2.0.1
* @link http://github.com/myaghobi/F3-Migrations Github
* @author Mohammad Yaghobi <[email protected]>
* @copyright Copyright (c) 2021, Mohammad Yaghobi
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3
*/

namespace DB\MIGRATIONS;

use DB\MIGRATIONS\Migrations;

class MigrationCaseItem {
public $file;
public $name;
public $version;
public $timestamp;
public $content;
public $valid;

private $casePrefix;
private $f3;


/**
* constructor
*
* @param string $path
* @return void
*/
function __construct($path=null) {
$this->f3 = \Base::instance();

$this->casePrefix = $this->f3->get('migrations.CASE_PREFIX') ?: 'migration_case_';

$this->valid = false;
$this->parsByFile($path);
}


/**
* pars attrs with path
*
* @param string $path
* @return void
*/
function parsByFile($path=null) {
$this->valid = false;

if (!$path || !file_exists($path)) {
return;
}

$this->file = $path;

$fileName = pathinfo($path)['basename'];
preg_match('/' . $this->casePrefix . '(.*?)(\d+(\.\d+)*)?_(\d+).php/', $fileName, $matches);
if ($matches) {
$this->name = $matches[1];
$this->version = $matches[2];
$this->timestamp = $matches[4];
}

$fileContent = file_get_contents($path);

if (preg_match('/class\s+(\w+)\s+extends/', $fileContent, $matches)) {
$str = str_replace($matches[0], 'new class() extends', $fileContent) . ';';
$this->content = $str;
}

$this->valid = true;
}


/**
* find a migration case by timestamp
*
* @param string $path
* @return void
*/
function findByTimestamp($timestamp) {
$this->valid = false;

$result = glob(Migrations::$path.$this->casePrefix.'*_'.$timestamp.'.php');
if (count($result)==1) {
$this->parsByFile($result[0]);
}
}
}

?>
29 changes: 29 additions & 0 deletions lib/db/migrations/MigrationCaseSample.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<?php

namespace DB\MIGRATIONS;
// the class name can be duplicate
class MigrationCaseSample extends \DB\MIGRATIONS\MigrationCase {
// this method will call on upgrade
public function up($f3, $db, $schema) {
// your cods here

// e.g. https://github.com/ikkez/f3-schema-builder#create-tables
// $table = $schema->createTable('products');
// $table->addColumn('title')->type($schema::DT_VARCHAR128);
// $table->addColumn('description')->type($schema::DT_TEXT);
// $table->build();

// return TRUE when the upgrade be successful
return true;
}

// this method will call on downgrade
public function down($f3, $db, $schema) {
// your cods here
// $schema->dropTable('products');

// return TRUE when the downgrade be successful
return true;
}
}
?>
Loading

0 comments on commit d2451af

Please sign in to comment.