Skip to content

Commit 1758935

Browse files
chrishalbertchrishalbert
authored
Merge pull request #30 from chrishalbert/addBetterDocumentation
Add better documentation
2 parents d70a176 + 059ee32 commit 1758935

9 files changed

+146
-155
lines changed

Diff for: ‎README.md

+27-155
Original file line numberDiff line numberDiff line change
@@ -1,174 +1,46 @@
1+
![Laravel Nomadic Header](./docs/NomadLife.png)
12
# laravel-nomadic
23
[![Build Status](https://travis-ci.org/chrishalbert/laravel-nomadic.svg?branch=master)](https://travis-ci.org/chrishalbert/laravel-nomadic)
34
[![Coverage Status](https://coveralls.io/repos/github/chrishalbert/laravel-nomadic/badge.svg?branch=master)](https://coveralls.io/github/chrishalbert/laravel-nomadic?branch=master)
45
[![Latest Stable Version](https://poser.pugx.org/chrishalbert/laravel-nomadic/v/stable)](https://packagist.org/packages/chrishalbert/laravel-nomadic)
56
[![Total Downloads](https://poser.pugx.org/chrishalbert/laravel-nomadic/downloads)](https://packagist.org/packages/chrishalbert/laravel-nomadic)
67
[![License](https://poser.pugx.org/chrishalbert/laravel-nomadic/license)](https://packagist.org/packages/chrishalbert/laravel-nomadic)
78

8-
9-
A configuration based tool kit of enhancements to Laravel's migrations. Exposes functionality so that developers can customize how migrations are generated.
9+
A powerful configuration based toolkit of enhancements to Laravel's migrations. This exposes an event driven design so that developers can create reusable functionality that executes automatically using the same developer workflow.
1010

1111
## Features
12-
* **Nomadic Schema** - Associate data with each migration. Maybe you want to save the date and time the migration was run,
13-
how long it ran for, or specific data with regards to nature of the migration itself.
14-
* **Nomadic Traits** - Inject your own custom traits into your migrations so that you can reuse common code.
15-
* **Nomadic Hooks** - Apply hooks before or after a migration is generated.
16-
* More to come...
17-
18-
## Installation -
19-
20-
1. Installation:
21-
22-
```
23-
composer require chrishalbert/laravel-nomadic
24-
```
25-
26-
or manually add it to the require-dev section of your composer file.
27-
28-
```json
29-
{
30-
"require" : {
31-
"chrishalbert/laravel-nomadic": "1.*"
32-
}
33-
}
34-
```
35-
36-
2. Next, add the Service Provider to the config/app.php
12+
* [**Hooks**](docs/NomadicHooks.md) - Use pre/post hooks for migration commands: `make:migration`, `migrate`, and `migrate:rollback`
13+
![Up Down Hook Ideas](./docs/LaravelNomadic-upDownHooks.png)
14+
* **Stubs** - Add developer notes to the generated migration
15+
![Stub Migrations](./docs/LaravelNomadic-Stub.PNG)
16+
* [**Schema**](docs/NomadicSchema.md) - Associate extra data within your `migrations` table
17+
18+
| id | migration | batch | author | comments | rollback |
19+
|----|:-------------------:|------:|-------:|---------------------------:|-----------:|
20+
| 1 | 20200811_CreateTable| 1 | John | Stores data for product x | NULL |
21+
| 2 | 20200812_AddData | 1 | Jack | Populate product x features| NULL |
22+
| 3 | 20200812_UpdateData | 2 | Jane | Fix description typo | {desc: "Grate product."}|
23+
24+
* [**Traits**](docs/NomadicTraits.md) - Add reusable functionality to every migration, via traits. Bonus: You can use hooks here too!
25+
![Using Traits](./docs/LaravelNomadic-Trait.PNG)
26+
27+
## Installation
28+
1. ```composer require chrishalbert/laravel-nomadic```
29+
2. Add the Service Provider to the config/app.php:
3730
```php
3831
'providers' => [
39-
4032
/**
4133
* Custom Providers...
4234
*/
4335
ChrisHalbert\LaravelNomadic\NomadicServiceProvider::class,
4436
]
4537
```
46-
47-
3. Lastly, publish some default configs into your application.
48-
```
49-
php artisan vendor:publish // Installs the nomadic.php config
50-
```
51-
52-
53-
## Nomadic Schema
54-
* Use Case: A developer wants to track the migration's runtime.
55-
* Use Case: A developer wants to know exactly when a migration started or ended.
56-
* Use Case: A developer deletes records from a table. To rollback this migration, the down() function would include
57-
hardcoded values. While this could work for some simple applications, any randomized or scrubbed database will not
58-
necessarily translate across tables.
59-
* Use Case: A developer inserts new records into a table. To rollback this migration, the down() function would need
60-
to query the exact records that were inserted. If the developer's database is a lean version of production, the query
61-
may not be accurate.
62-
* Use Case: A developer updates records in table. Similarly, to rollback, the down() function would need to know the
63-
exact values of the records prior to updating. This could differ for randomized data.
64-
65-
### Setup
66-
1. First, you will need to add the field(s) to your migration table - this is on you to do :)
67-
2. Open up the nomadic.php and add the fields in the schema array
68-
```
69-
return [
70-
// Just some examples below - these would be the additional columns in your migration table.
71-
'schema' => [
72-
'flag',
73-
'author',
74-
'runTime',
75-
'migrationInfo'
76-
],
77-
];
78-
```
79-
80-
Now, verify the configurations are complete.
81-
```
82-
php artisan make:migration VerifyNomadicInstalled
83-
```
84-
85-
In your migration, you should now see that your migration `extends NomadicMigration`.
86-
87-
As noted above in your new migration's comments:
88-
```php
89-
/**
90-
* @return void
91-
*/
92-
public function up()
93-
{
94-
// Use $this->setProperty($migrationColumn, $insertedIds);
95-
// The $migrationColumn MUST be added to the configs/nomadic.php
96-
}
97-
98-
/**
99-
* Reverse the migrations.
100-
*
101-
* @return void
102-
*/
103-
public function down()
104-
{
105-
// And now you can $insertedIds = $this->getProperty($migrationColumn) and delete
106-
}
107-
```
108-
109-
## Nomadic Traits
110-
* Use Case: Reuse common functionality that your migrations tend to use.
111-
112-
### Usage
113-
Open up the nomadic.php and add your custom traits
114-
```
115-
return [
116-
'traits' => [
117-
\My\Custom\Trait::class
118-
],
119-
];
120-
```
121-
Now when you create migrations, you should see your stubbed migration using your custom traits.
122-
123-
## Nomadic Hooks
124-
* Use Case: You would like to alert the developer to run all migrations before creating a new one.
125-
* Use Case: After a migration is generated, you want to remind the user to add schema changes to the release notes.
126-
127-
### Usage
128-
Open up the nomadic.php where you can add 2 different types of hooks.
129-
130-
#### Create Hooks
131-
These are hooks used when you run `php artisan make:migration`. These hooks can ONLY be defined here in the config file. You can pass a closure, or you can pass a NomadicHookInterface. The benefit of passing the NomadicCreateHookInterface, is that you get the same data passed to the create(). These arguments are
132-
passed to the execute() method, which is what is called.
133-
```
134-
return [
135-
'hooks' => [
136-
'preCreate' => [
137-
function() {
138-
\Log::info('Make sure to run all migrations');
139-
},
140-
],
141-
'postCreate' => [
142-
new NomadicCreateHookInterfaceImplementation()
143-
]
144-
],
145-
];
146-
```
147-
148-
#### Migration Hooks
149-
These hooks are excuted when the migration runs. The construct hook can only be set in the config file. Everything else can be set here in the configuration
150-
or modified at runtime.
151-
```
152-
return [
153-
154-
// Hooks executed with the migrations
155-
'hooks' => [
156-
'construct' => [ // Can only be defined in the configs
157-
],
158-
'preMigrate' => [ // Executed before up()
159-
],
160-
'postMigrate' => [ // Executed after up()
161-
],
162-
'preRollback' => [ // Executed before rolling down()
163-
],
164-
'postRollback' => [ // Executed after rolling down()
165-
],
166-
'destruct' => [ // Executed during destruction
167-
]
168-
],
169-
];
170-
```
171-
38+
3, Publish default configs/nomadic.php: ```php artisan vendor:publish```
17239

17340
## Feature Requests/Bugs
174-
Submit feature requests or bugs to [laravel-nomadic Issues](https://github.com/chrishalbert/laravel-nomadic/issues).
41+
Submit feature requests or bugs to [laravel-nomadic issues](https://github.com/chrishalbert/laravel-nomadic/issues).
42+
43+
## Services
44+
_Do you have an internal need or enhancement you care not to share with the world?_
45+
####I can help!
46+
Reach out to me directly for rates, scope and your business needs. I can furnish an NDA as needed.

Diff for: ‎docs/LaravelNomadic-Stub.PNG

86.7 KB
Loading

Diff for: ‎docs/LaravelNomadic-Trait.PNG

39.8 KB
Loading

Diff for: ‎docs/LaravelNomadic-preConstructHook.png

47.1 KB
Loading

Diff for: ‎docs/LaravelNomadic-upDownHooks.png

62.2 KB
Loading

Diff for: ‎docs/NomadLife.png

615 KB
Loading

Diff for: ‎docs/NomadicHooks.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Nomadic Hooks
2+
* Use Case: You would like to alert the developer to run all migrations before creating a new one.
3+
* Use Case: After a migration is generated, you want to remind the user to add schema changes to the release notes.
4+
![Up Down Hook Ideas](./LaravelNomadic-preConstructHook.png)
5+
6+
## Usage
7+
Open up the nomadic.php where you can add 2 different types of hooks.
8+
9+
### Create Hooks
10+
11+
These are hooks used when you run `php artisan make:migration`. These hooks can ONLY be defined here in the config file. You can pass a closure, or you can pass a NomadicHookInterface. The benefit of passing the NomadicCreateHookInterface, is that you get the same data passed to the create(). These arguments are
12+
passed to the execute() method, which is what is called.
13+
```
14+
return [
15+
'hooks' => [
16+
'preCreate' => [
17+
function() {
18+
\Log::info('Make sure to run all migrations');
19+
},
20+
],
21+
'postCreate' => [
22+
new NomadicCreateHookInterfaceImplementation()
23+
]
24+
],
25+
];
26+
```
27+
28+
### Migration Hooks
29+
These hooks are excuted when the migration runs. The construct hook can only be set in the config file. Everything else can be set here in the configuration
30+
or modified at runtime.
31+
![Up Down Hook Ideas](./LaravelNomadic-upDownHooks.png)
32+
```
33+
return [
34+
35+
// Hooks executed with the migrations
36+
'hooks' => [
37+
'construct' => [ // Can only be defined in the configs
38+
],
39+
'preMigrate' => [ // Executed before up()
40+
],
41+
'postMigrate' => [ // Executed after up()
42+
],
43+
'preRollback' => [ // Executed before rolling down()
44+
],
45+
'postRollback' => [ // Executed after rolling down()
46+
],
47+
'destruct' => [ // Executed during destruction
48+
]
49+
],
50+
];
51+
```

Diff for: ‎docs/NomadicSchema.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Nomadic Schema
2+
* Use Case: A developer wants to track the migration's runtime.
3+
* Use Case: A developer wants to know exactly when a migration started or ended.
4+
* Use Case: A developer deletes records from a table. To rollback this migration, the down() function would include
5+
hardcoded values. While this could work for some simple applications, any randomized or scrubbed database will not
6+
necessarily translate across tables.
7+
* Use Case: A developer inserts new records into a table. To rollback this migration, the down() function would need
8+
to query the exact records that were inserted. If the developer's database is a lean version of production, the query
9+
may not be accurate.
10+
* Use Case: A developer updates records in table. Similarly, to rollback, the down() function would need to know the
11+
exact values of the records prior to updating. This could differ for randomized data.
12+
13+
## Setup
14+
1. First, you will need to add the field(s) to your migration table - this is on you to do :)
15+
2. Open up the nomadic.php and add the fields in the schema array
16+
```
17+
return [
18+
// Just some examples below - these would be the additional columns in your migration table.
19+
'schema' => [
20+
'flag',
21+
'author',
22+
'runTime',
23+
'migrationInfo'
24+
],
25+
];
26+
```
27+
28+
Now, verify the configurations are complete.
29+
```
30+
php artisan make:migration VerifyNomadicInstalled
31+
```
32+
33+
In your migration, you should now see that your migration `extends NomadicMigration`.
34+
35+
As noted above in your new migration's comments:
36+
```php
37+
/**
38+
* @return void
39+
*/
40+
public function up()
41+
{
42+
// Use $this->setProperty($migrationColumn, $insertedIds);
43+
// The $migrationColumn MUST be added to the configs/nomadic.php
44+
}
45+
46+
/**
47+
* Reverse the migrations.
48+
*
49+
* @return void
50+
*/
51+
public function down()
52+
{
53+
// And now you can $insertedIds = $this->getProperty($migrationColumn) and delete
54+
}
55+
```

Diff for: ‎docs/NomadicTraits.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Nomadic Traits
2+
* Use Case: Reuse common functionality that your migrations tend to use.
3+
4+
## Usage
5+
Open up the nomadic.php and add your custom traits
6+
```
7+
return [
8+
'traits' => [
9+
\My\Custom\Trait::class
10+
],
11+
];
12+
```
13+
Now when you create migrations, you should see your stubbed migration using your custom traits.

0 commit comments

Comments
 (0)