Skip to content

Commit 0422fb2

Browse files
kitloongkitloong
authored
Merge pull request #265 from kitloong/feature/docs
Create documentation
2 parents f30badc + 698e053 commit 0422fb2

26 files changed

+766
-52
lines changed

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@
33

44
# Ignore all test and documentation with "export-ignore".
55
/.github export-ignore
6+
/docs export-ignore
67
/tests export-ignore
78
/.editorconfig export-ignore
89
/.gitattributes export-ignore
910
/.gitignore export-ignore
1011
/.phpmd.xml export-ignore
1112
/check_migrations.sh export-ignore
13+
/mkdocs.yml export-ignore
1214
/phpcs.xml export-ignore
1315
/phpstan.neon export-ignore
1416
/phpunit.xml.dist export-ignore

‎.github/workflows/docs.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: "Generate documentation"
2+
3+
on:
4+
push:
5+
branches:
6+
- 7.x
7+
8+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
9+
permissions:
10+
contents: write
11+
pages: write
12+
13+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
14+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: false
18+
19+
jobs:
20+
deploy:
21+
22+
runs-on: ubuntu-latest
23+
24+
steps:
25+
- name: Checkout code
26+
uses: actions/checkout@v4
27+
28+
- name: Set up Python
29+
uses: actions/setup-python@v5
30+
with:
31+
python-version: '3.x'
32+
33+
- name: Install dependencies
34+
run: |
35+
python -m pip install --upgrade pip
36+
pip install mkdocs
37+
38+
- name: Deploy
39+
run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
/migrations
66
/storage
77
/vendor
8+
/venv
9+
/site
810
.php-cs-fixer.cache
911
.php_cs.cache
1012
.phpstorm.meta.php

‎README.md‎

Lines changed: 26 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@
99

1010
Generate Laravel Migrations from an existing database, including indexes and foreign keys!
1111

12-
This package is a modified version of https://github.com/Xethron/migrations-generator that has been updated to support Laravel 5.6 and beyond, along with additional features.
12+
## Documentation
13+
14+
Checkout the [documentation](https://kitloong.github.io/laravel-migrations-generator/usage/) for more details.
1315

1416
## Supported Database
1517

@@ -80,7 +82,7 @@ You can also ignore tables with:
8082
php artisan migrate:generate --ignore="table3,table4,table5"
8183
```
8284

83-
Laravel Migrations Generator will first generate all the tables, columns and indexes, and afterwards setup all the foreign key constraints.
85+
Laravel Migrations Generator will first generate all the tables, columns and indexes, and afterward setup all the foreign key constraints.
8486

8587
So make sure you include all the tables listed in the foreign keys so that they are present when the foreign keys are created.
8688

@@ -104,56 +106,28 @@ php artisan migrate:generate --squash
104106

105107
Run `php artisan help migrate:generate` for a list of options.
106108

107-
| Options | Description |
108-
|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
109-
| -c, --connection[=CONNECTION] | The database connection to use |
110-
| -t, --tables[=TABLES] | A list of tables or views you wish to generate migrations for separated by a comma: users,posts,comments |
111-
| -i, --ignore[=IGNORE] | A list of tables or views you wish to ignore, separated by a comma: users,posts,comments |
112-
| -p, --path[=PATH] | Where should the file be created? |
113-
| -tp, --template-path[=TEMPLATE-PATH] | The location of the template for this generator |
114-
| --date[=DATE] | Migrations will be created with specified date. Views and foreign keys will be created with + 1 second. Date should be in format supported by `Carbon::parse` |
115-
| --table-filename[=TABLE-FILENAME] | Define table migration filename, default pattern: `[datetime]\_create_[name]_table.php` |
116-
| --view-filename[=VIEW-FILENAME] | Define view migration filename, default pattern: `[datetime]\_create_[name]_view.php` |
117-
| --proc-filename[=PROC-FILENAME] | Define stored procedure filename, default pattern: `[datetime]\_create_[name]_proc.php` |
118-
| --fk-filename[=FK-FILENAME] | Define foreign key migration filename, default pattern: `[datetime]\_add_foreign_keys_to_[name]_table.php` |
119-
| --log-with-batch[=LOG-WITH-BATCH] | Log migrations with given batch number. We recommend using batch number 0 so that it becomes the first migration |
120-
| --default-index-names | Don\'t use DB index names for migrations |
121-
| --default-fk-names | Don\'t use DB foreign key names for migrations |
122-
| --use-db-collation | Generate migrations with existing DB collation |
123-
| --skip-log | Don\'t log into migrations table |
124-
| --skip-vendor | Don\'t generate vendor migrations |
125-
| --skip-views | Don\'t generate views |
126-
| --skip-proc | Don\'t generate stored procedures |
127-
| --squash | Generate all migrations into a single file |
128-
| --with-has-table | Check for the existence of a table using `hasTable` |
129-
130-
## SQLite Alter Foreign Key
131-
132-
The generator first generates all tables and then adds foreign keys to existing tables.
133-
134-
However, SQLite only supports foreign keys upon creation of the table and not when tables are altered.
135-
*_add_foreign_keys_* migrations will still be generated, however will get omitted if migrate to SQLite type database.
136-
137-
## User-Defined Type Columns
138-
139-
The generator will recognize user-defined type from the schema, and then generate migration as
140-
141-
```php
142-
public function up()
143-
{
144-
Schema::create('table', function (Blueprint $table) {
145-
...
146-
});
147-
DB::statement("ALTER TABLE table ADD column custom_type NOT NULL");
148-
}
149-
```
150-
151-
Note that the new `column` is always added at the end of the created `table` which means the ordering of the column generated in migration will differ from what we have from the schema.
152-
153-
Supported database with user-defined types:
154-
155-
- [x] PostgreSQL
156-
- [x] SQL Server
109+
| Options | Description |
110+
|------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
111+
| [-c, --connection[=CONNECTION]](https://kitloong.github.io/laravel-migrations-generator/options/connection/) | The database connection to use |
112+
| [-t, --tables[=TABLES]](https://kitloong.github.io/laravel-migrations-generator/options/tables/) | A list of tables or views you wish to generate migrations for separated by a comma: users,posts,comments |
113+
| [-i, --ignore[=IGNORE]](https://kitloong.github.io/laravel-migrations-generator/options/ignore/) | A list of tables or views you wish to ignore, separated by a comma: users,posts,comments |
114+
| [-p, --path[=PATH]](https://kitloong.github.io/laravel-migrations-generator/options/path/) | Where should the file be created? |
115+
| [-tp, --template-path[=TEMPLATE-PATH]](https://kitloong.github.io/laravel-migrations-generator/options/template-path/) | The location of the template for this generator |
116+
| [--date[=DATE]](https://kitloong.github.io/laravel-migrations-generator/options/date/) | Migrations will be created with specified date. Views and foreign keys will be created with + 1 second. Date should be in format supported by `Carbon::parse` |
117+
| [--table-filename[=TABLE-FILENAME]](https://kitloong.github.io/laravel-migrations-generator/options/table-filename/) | Define table migration filename, default pattern: `[datetime]\_create_[name]_table.php` |
118+
| [--view-filename[=VIEW-FILENAME]](https://kitloong.github.io/laravel-migrations-generator/options/table-filename/) | Define view migration filename, default pattern: `[datetime]\_create_[name]_view.php` |
119+
| [--proc-filename[=PROC-FILENAME]](https://kitloong.github.io/laravel-migrations-generator/options/table-filename/) | Define stored procedure filename, default pattern: `[datetime]\_create_[name]_proc.php` |
120+
| [--fk-filename[=FK-FILENAME]](https://kitloong.github.io/laravel-migrations-generator/options/table-filename/) | Define foreign key migration filename, default pattern: `[datetime]\_add_foreign_keys_to_[name]_table.php` |
121+
| [--log-with-batch[=LOG-WITH-BATCH]](https://kitloong.github.io/laravel-migrations-generator/options/log-with-batch/) | Log migrations with given batch number. We recommend using batch number 0 so that it becomes the first migration |
122+
| [--default-index-names](https://kitloong.github.io/laravel-migrations-generator/options/default-index-names/) | Don\'t use DB index names for migrations |
123+
| [--default-fk-names](https://kitloong.github.io/laravel-migrations-generator/options/default-fk-names/) | Don\'t use DB foreign key names for migrations |
124+
| [--use-db-collation](https://kitloong.github.io/laravel-migrations-generator/options/use-db-collation/) | Generate migrations with existing DB collation |
125+
| [--skip-log](https://kitloong.github.io/laravel-migrations-generator/options/skip-log/) | Don\'t log into migrations table |
126+
| [--skip-vendor](https://kitloong.github.io/laravel-migrations-generator/options/skip-vendor/) | Don\'t generate vendor migrations |
127+
| [--skip-views](https://kitloong.github.io/laravel-migrations-generator/options/skip-views/) | Don\'t generate views |
128+
| [--skip-proc](https://kitloong.github.io/laravel-migrations-generator/options/skip-proc/) | Don\'t generate stored procedures |
129+
| [--squash](https://kitloong.github.io/laravel-migrations-generator/options/squash/) | Generate all migrations into a single file |
130+
| [--with-has-table](https://kitloong.github.io/laravel-migrations-generator/options/with-has-table/) | Check for the existence of a table using `hasTable` |
157131

158132
## Thank You
159133

‎docs/index.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Getting Started
2+
3+
Generate Laravel Migrations from an existing database, including indexes and foreign keys!
4+
5+
## Supported Database
6+
7+
Laravel Migrations Generator supports all five Laravel first-party support databases:
8+
9+
- MariaDB
10+
- MySQL
11+
- PostgreSQL
12+
- SQL Server
13+
- SQLite
14+
15+
## Install
16+
17+
The recommended way to install this is through composer:
18+
19+
```bash
20+
composer require --dev kitloong/laravel-migrations-generator
21+
```
22+
23+
## Version Compatibility
24+
25+
| Laravel | Version |
26+
|--------------------|-------------------------------------------------|
27+
| 12.x | 7.x |
28+
| 11.x | 7.x |
29+
| \>= 10.43.x | 7.x |
30+
| 10.x \| <= 10.42.x | 6.x |
31+
| 9.x | 6.x |
32+
| 8.x | 6.x |
33+
| 7.x | 6.x |
34+
| 6.x | 6.x |
35+
| 5.8.x | 6.x |
36+
| 5.7.x | 6.x |
37+
| 5.6.x | 6.x |
38+
| <= 5.5.x | https://github.com/Xethron/migrations-generator |
39+
40+
### Laravel Setup
41+
42+
Laravel will automatically register service provider for you.
43+
44+
### Lumen Setup
45+
46+
Auto-discovery is not available in Lumen, you need some modification on `bootstrap/app.php`.
47+
48+
#### Enable Facade
49+
50+
Uncomment the following line.
51+
52+
```php
53+
$app->withFacades();
54+
```
55+
56+
#### Register Provider
57+
58+
Add following line into the `Register Service Providers` section.
59+
60+
```php
61+
$app->register(\KitLoong\MigrationsGenerator\MigrationsGeneratorServiceProvider::class);
62+
```

‎docs/options/connection.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Connection
2+
3+
```bash
4+
-c, --connection[=CONNECTION]
5+
```
6+
7+
The `--connection` option allows you to specify the database connection to use. If you don't specify a connection, the default connection as defined in your Laravel's `config/database.php` will be used.
8+
9+
This option is particularly useful when you have multiple database connections defined in your Laravel application and you want to generate migrations for a specific connection.
10+
11+
### Example
12+
13+
Suppose you have a connection named `secondary` defined in your `config/database.php`. You can generate migrations for this connection by running:
14+
15+
```bash
16+
php artisan migrate:generate --connection="secondary"
17+
```
18+
19+
This command will generate migrations for the tables in the `secondary` database connection.
20+
21+
```php
22+
// Up
23+
Schema::connection('secondary')->create('users', function (Blueprint $table) {
24+
$table->bigIncrements('id');
25+
...
26+
});
27+
28+
// Down
29+
Schema::connection('secondary')->dropIfExists('users');
30+
```
31+
32+
If you are not sure what is the name of the connection you want to use, you can check the `connections` array in your `config/database.php` file.
33+
34+
```php
35+
array_keys(config('database.connections'))
36+
```

‎docs/options/date.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Date
2+
3+
```bash
4+
--date[=DATE]
5+
```
6+
7+
The `--date` option allows you to specify the date for the generated migration files.
8+
9+
Migrations will be created with the specified date. Views, procedures, and foreign keys will be created with an additional 1 second.
10+
11+
The date should be in a format supported by [`Carbon::parse`](https://github.com/briannesbitt/Carbon/blob/d481d8d69a94dc00e5c1b147ec1f7e7492626b12/src/Carbon/Traits/Creator.php#L207).
12+
13+
### Example
14+
15+
```bash
16+
php artisan migrate:generate --date="2024-10-08 12:30:00"
17+
```
18+
19+
Will generate the following migrations:
20+
21+
```bash
22+
2024_10_08_123000_create_comments_table.php
23+
2024_10_08_123000_create_users_table.php
24+
2024_10_08_123001_add_foreign_keys_to_comments_table.php
25+
```

‎docs/options/default-fk-names.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Default Foreign Key Names
2+
3+
```bash
4+
--default-fk-names
5+
```
6+
7+
Use Laravel's default naming convention for foreign keys instead of the database foreign key names.
8+
9+
### Example
10+
11+
```bash
12+
php artisan migrate:generate --default-fk-names
13+
```
14+
15+
Schema with foreign key:
16+
17+
```sql
18+
CREATE TABLE `comments` (
19+
...
20+
CONSTRAINT `user_id_fk` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)
21+
);
22+
```
23+
24+
Will generate as:
25+
26+
```php
27+
Schema::table('comments', function (Blueprint $table) {
28+
...
29+
$table->foreign('user_id')->references('id')->on('users');
30+
});
31+
```

‎docs/options/default-index-names.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Default Index Names
2+
3+
```bash
4+
--default-index-names
5+
```
6+
7+
Use Laravel's default naming convention for indexes instead of the database index names.
8+
9+
### Example
10+
11+
```bash
12+
php artisan migrate:generate --default-index-names
13+
```
14+
15+
Schema with index:
16+
17+
```sql
18+
CREATE TABLE `comments` (
19+
...
20+
INDEX `user_id_idx` (`user_id`)
21+
);
22+
```
23+
24+
Will generate as:
25+
26+
```php
27+
Schema::create('comments', function (Blueprint $table) {
28+
...
29+
$table->index('user_id');
30+
});
31+
```

‎docs/options/ignore.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Ignore
2+
3+
```bash
4+
-i, --ignore[=IGNORE]
5+
```
6+
7+
The `--ignore` option allows you to specify which tables you want to exclude when generating migrations. This is useful when you want to generate migrations for all tables in your database except for a few specific ones.
8+
9+
### Example
10+
11+
To use the `--ignore` option, you need to provide a comma-separated list of table names. For example:
12+
13+
```bash
14+
php artisan migrate:generate --ignore="users,comments"
15+
```

0 commit comments

Comments
 (0)