updated documentation

Author: toramanlis

.wiki

@@ -38,15 +38,15 @@
 
 ## What It Is
 
-This package is a tool that creates Laravel migration files by inspecting the application's models with the command `php artisan implicit-migrations:generate`. Even after you change the model classes, you can run the command to generate a migration with the necessary update operations.
+This package is a tool that creates Laravel migration files by inspecting the application's models with the command `php artisan implicit-migrations:generate`. Even after you change the model classes, you can run the command and generate a migration with the necessary update operations.
 
 ## How It Works
 
-With the most basic configuration, the `implicit-migrations:generate` artisan command looks at the Eloquent model and finds necessary information about the table properties such as the table name, primary key etc. Then it goes over the properties of the model and collects the name, type and default value information if provided. With the information collected, it creates a migration file and populates the `up()` and `down()` methods with the appropriate definitions.
+With the most basic configuration, the `implicit-migrations:generate` artisan command looks at a Eloquent model and finds necessary information about the table properties such as the table name, primary key etc. Then it goes over the properties of the model and collects the name, type and default value information if provided. With the information collected, it creates a migration file and populates the `up()` and `down()` methods with the appropriate definitions.
 
 ### Implications
 
-For further details, the generator refers to some additional data in the model class which we call "Implications". These can be specified with either annotations or attributes on the class, properties and methods.
+For further details, the generator refers to some additional data in the model class which we call "Implications". These can be specified with either annotations or attributes on the class, its properties and methods.
 
 #### Annotations
 
@@ -108,12 +108,12 @@ return new class extends Migration
 };
 ```
 
-You can find out more on other implications are available in the [Implication Reference](#implication-reference) section.
+You can find out more on other implications in the [Implication Reference](#implication-reference) section.
 
 
 #### PHP Attributes
 
-Another way of specifying implications is using PHP's attributes. The very same implications are avaliable as attributes with the same notation. This is the same model definition as above as far as the generator is concerned:
+Another way of specifying implications is using PHP attributes. The very same implications are avaliable as attributes with the same notation. This is the same model definition as above as far as the generator is concerned:
 
 ```php
 <?php
@@ -132,7 +132,7 @@ class OrderItem extends Model
 
 The advantage of this option is that your IDE/Editor will recognize the attributes as the classes they are and provide autocompletion and descriptions. The down side is that the classes have to be referenced in the models and now they need to be existent in the production environment too.
 
-The obvious approach to this is just adding the `implicit-migrations` package to the `require` instead of `require-dev`. The neat approach is to get the attribute classes to the `database/migrations/attributes` directory in the project by publishing them with the `php artisan vendor:publish --tag=implication-attributes` command and add `"database/attributes/composer.json"` to the `composer.json` file like this:
+The obvious approach to tackling this is just adding the `implicit-migrations` package to the `require` instead of `require-dev`. The neat approach, on the other hand, is to get the attribute classes to the `database/migrations/attributes` directory of the project by publishing them with the `php artisan vendor:publish --tag=implication-attributes` command and add `"database/attributes/composer.json"` to the `composer.json` file like this:
 
 ```json
 ...
@@ -146,11 +146,11 @@ The obvious approach to this is just adding the `implicit-migrations` package to
 ...
 ```
 
-This way, you can have the package in the `require` section of your `composer.json` and still have the attribute classes available in production.
+This way, you can have the package in the `require-dev` section of your `composer.json` and still have the attribute classes available in production.
 
 ### Updates
 
-This tool doesn't only work for creating a table for a model. If you change your model and run `implicit-migrations:generate` again, it will resolve the changes in the model by referring to the already generated migrations (**Only** the generated migrations that is. [See: Manual Migrations](#manual-migrations)) and generate a new migration that applies the changes to the table structure.
+This tool doesn't only work for creating a table for a model. If you change your model and run `implicit-migrations:generate` again, it will resolve the changes  by referring to the already generated migrations (**Only** the generated migrations that is. [See: Manual Migrations](#manual-migrations)) and generate a new migration that applies the changes to the table structure.
 
 For example if you update the above model and add another property to it:
 
@@ -220,9 +220,9 @@ return new class extends Migration
 
 # Installation
 
-The recommended installation is using `composer require --dev toramanlis/implicit-migrations` command. Since **this will make the implication attributes unavailable in production**, if you want to use attributes for implications you have to take one of these approaches:
+The recommended installation is using `composer require --dev toramanlis/implicit-migrations` command. Since **this will make the implication attributes unavailable in production**, if you want to use attributes for implications you have to take one of the following approaches:
 
-## Publishing The Attributes
+### Publishing The Attributes
 
 You can publish the attribute classes with `php artisan vendor:publish --tag=implication-attributes` and add the line `"database/attributes/composer.json"` in the `composer.json` file like this:
 
@@ -238,34 +238,40 @@ You can publish the attribute classes with `php artisan vendor:publish --tag=imp
 ...
 ```
 
-## Opting Out From Attributes
+### Opting Out From Attributes
 
 Each and every one of the implications are available as both attributes and annotations. You can completely give up using attributes and switch to the annotation notation with no missing functionality.
 
 
-## Installing To Production
+### Installing To Production
 
 Alternatively, you can always install the package with `composer install toramanlis/implicit-migrations` without the `--dev` option. Having a tool like this in production sure is unnecessary, but it's just that, unnecessary.
 
 
 # Configuration
 
 ## `database.model_paths`
+##### Type: *`array`*
+##### Default: *`['app/Models']`*
 
-An `array` of paths relative to the project directory where application models reside. The default is a single path the same as Laravel' default model path: `['app/Models']`
+An `array` of paths relative to the project directory where application models reside. If there are multiple model and migration paths in a project, the migration files are created in the migration path that is closest to the source model in the directory tree (complicit with [nWidart/laravel-modules](https://github.com/nWidart/laravel-modules)).
 
 ## `database.auto_infer_migrations`
+##### Type: *`bool`*
+##### Default: *`true`*
 
-This is a `boolean` value that controls, you guessed it, whether or not to infer the migration information automatically. What this means is basically, unless specified otherwise with an implication, none of the models, properties or methods are going to be inspected for migration information. If a property or method of a model has an implication, that model will also be inspected. The default is `true`.
+This is a `boolean` value that controls, you guessed it, whether or not to infer the migration information automatically. What this means is basically, unless specified otherwise with an implication, none of the models, properties or methods are going to be inspected for migration information. However, if a property or method of a model has an implication, that model will be inspected. The default is `true`.
 
 ## `database.implications.<implication_name_in_snake>`
+##### Type: *`bool`*
+##### Default: *`true`*
 
-These are `boolean` values that can be used to enable or disable implications. The implication names have to be in snake case as per Laravel's convention of configuration keys e.g. `database.implications.foreign_key`. This set to `true` by default for all the implications.
+These are `boolean` values that can be used to enable or disable each implication. The implication names have to be in snake case as per Laravel's convention for configuration keys e.g. `database.implications.foreign_key`. This set to `true` by default for all the implications.
 
 
 # Manual Migrations
 
-It's always a good idea to have a backup plan. You might come accross some more intricate or complicated requirements from a migration. For this reason, this tool doesn't take into account any migrations that does not have a `getSource()` method. This way, you can add your own custom migrations that are processed with Laravel's `migrate` command, but completely invisible to `implicit-migrations:generate`.
+It's always a good idea to have a backup plan. You might come accross some more intricate or complicated requirements from a migration. For this reason, this tool doesn't take into account any migrations that does not have a `getSource()` method. This way, you can add your own custom migrations that are processed by Laravel's `migrate` command, but completely invisible to `implicit-migrations:generate`.
 
 If a manual migration happens to have a method named `getSource`, the [Off](#off) implication can be utilized to indicate that it is in fact a manual migration.
 
@@ -275,16 +281,16 @@ If a manual migration happens to have a method named `getSource`, the [Off](#off
 
 All the PHP attributes for the implications reside in the namespace `Toramanlis\ImplicitMigrations\Attributes`. If you choose to utilize them, make sure they're available in your production environment as well. See the [installation section](#installation) for details.
 
-Generally, the parameters of the implications are optional as they often have default values or can possibly be inferred from the rest of the information available in the application such as the native PHP definitions of models, properties and methods or other implications' details.
+Generally, the parameters of the implications are optional as they often have default values or can possibly be inferred from the rest of the information available in the application, such as the native PHP definitions of models, properties and methods or other implications' details.
 
-Best to keep in mind that these details still might not be sufficient to create the migration and some of the *optional* parameters might, in fact, be required.
+Best to keep in mind that these details still might not be sufficient to make a definition and some of the *optional* parameters might, in fact, be required.
 
 ## `Table`
 ##### Target: *`class`*
 
 `Table(?string $name = null, ?string $engine = null, ?string $charset = null, ?string $collation = null)`
 
-Used with classes for specifying the table details. When the `database.auto_infer_migrations` configuration option is set to `true`, using this implication lets the class processed.
+Used with classes for specifying the table details. When the `database.auto_infer_migrations` configuration option is set to `true`, using this implication lets the class get processed.
 
 
 ## `Column`
@@ -293,7 +299,7 @@ Used with classes for specifying the table details. When the `database.auto_infe
 
 `Column(?string $type = null, ?string $name = null, ?bool $nullable = null, $default = null, ?int $length = null, ?bool $unsigned = null, ?bool $autoIncrement = null, ?int $precision = null, ?int $total = null, ?int $places = null, ?array $allowed = null, ?bool $fixed = null, ?string $subtype = null, ?int $srid = null, ?string $expression = null, ?string $collation = null, ?string $comment = null, ?string $virtualAs = null, ?string $storedAs = null, ?string $after = null)`
 
-Can be used with both classes and properties to define columns. The `name` parameter is mandatory when used with classes as it won't be able to infer the column name. In contrast, when used with a property, column name defaults to the name of the property. Either by using it on a property or providing a `name` that matches a property allows it to infer whatever information available in the definition of said property.
+Can be used both on classes and properties to define columns. The `name` parameter is mandatory when used on classes as it won't be able to infer the column name. In contrast, when used on a property, column name defaults to the name of the property. Either by using it on a property or providing a `name` that matches a property allows it to infer whatever information available in the definition of said property.
 
 
 ## `Index`
@@ -302,9 +308,9 @@ Can be used with both classes and properties to define columns. The `name` param
 
 `Index(null|array|string $column = null, string $type = 'index', ?string $name = null, ?string $algorithm = null, ?string $language = null)`
 
-Just like `Column`, this can also be used with both classes and properties. The `column` parameter is optional when used with a property and defaults to the column name associated with that property even if the property doesn't have a `Column` implication of its own. When used with a class, the `column` parameter is mandatory.
+Just like `Column`, this can also be used both on classes and properties. The `column` parameter is optional when used on a property and defaults to the column name associated with that property even if the property doesn't have a `Column` implication of its own. When used on a class, the `column` parameter is mandatory.
 
-When `Index` is associated with a single column name by either using it with a property or having given one value to the `column` parameter, it will try and ensure the existence of a column with that name, using any information available in the model definition.
+When `Index` is associated with a single column name by either using it on a property or having given a value to the `column` parameter, it will try and ensure the existence of a column with that name, using any information available in the model definition.
 
 
 ## `Unique`
@@ -331,7 +337,7 @@ Alias for `Index($column, type: 'primary', ...$args)`
 
 `Relationship()`
 
-Specifies that a method is a Laravel relationship. What kind of relationship it is will always be inferred by the return type of the method. This implication is redundant if the `database.auto_infer_migrations` configuration option is on, as the return type of a `public` method is already taken as an implication of whether or not it's a relationship method.
+Specifies that a method is a Laravel relationship. What kind of relationship it is will always be inferred by the return type of the method. This implication is redundant if the `database.auto_infer_migrations` configuration option is set to `true`, as the return type of a `public` method is already taken as an implication of whether or not it's a relationship method.
 
 If the type of relationship requires tables and columns that are not defined, `Relationship` will try to ensure them in the migration using whatever information is available.
 
@@ -342,7 +348,7 @@ If the type of relationship requires tables and columns that are not defined, `R
 
 `ForeignKey(string $on, null|array|string $column = null, null|array|string $references = null, ?string $onUpdate = null, ?string $onDelete = null)`
 
-Similar to `Index`, this can be used with both classes and properties, but with classes, it's mandatory to provide the `column` parameter.
+Similar to `Index`, this can be used both on classes and properties, but with classes, it's mandatory to provide the `column` parameter.
 
 The `on` parameter can be a table name or a class name of a model.
 
@@ -362,7 +368,7 @@ Specifies the details of a pivot table of a relationship. Even if no `Relationsh
 
 `PivotColumn(?string $name, protected ?string $type = null, ?bool $nullable = null, $default = null, ?int $length = null, ?bool $unsigned = null, ?bool $autoIncrement = null, ?int $precision = null, ?int $total = null, ?int $places = null, ?array $allowed = null, ?bool $fixed = null, ?string $subtype = null, ?int $srid = null, ?string $expression = null, ?string $collation = null, ?string $comment = null, ?string $virtualAs = null, ?string $storedAs = null, ?string $after = null)`
 
-Defines a column on a pivot table of a relationship. Just like [`PivotTable`](#pivottable), having this implication lets the generator know it's a relationship method. Since pivot tables typically don't have models of their own, we define any extra columns on the relationship method they are required by.
+Defines a column on a pivot table of a relationship. Just like [`PivotTable`](#pivottable), having this implication lets the generator know it's a relationship method. Since pivot tables typically don't have models of their own, we define any **extra** columns on the relationship method they are required by. Only the columns other than the foreign keys need this implicaiton, foreign keys are already covered with the relationship. It's still allowed to use this implication to fine tune them, though.
 
 
 ## `Off`
@@ -371,4 +377,4 @@ Defines a column on a pivot table of a relationship. Just like [`PivotTable`](#p
 
 `Off()`
 
-Lets the generator know that the given class, property or method should be ignored. This includes `getSource` method a migration. If you have a manually written migration that happens to have a method name `getSource`, you can add this implication to that method to keep the generator off that migration.
+Lets the generator know that the given class, property or method should be ignored. This includes `getSource` method a migration. If you have a manually written migration that happens to have a method named `getSource`, you can add this implication to that method to keep the generator off of that migration.