Adds missing DATABASE.md

.github/workflows/php.yml

@@ -124,7 +124,7 @@ jobs:
 
       - name: Check exported files
         run: |
-          EXPECTED=LICENSE.md,MIGRATIONS.md,README.md,composer.json
+          EXPECTED=DATABASE.md,LICENSE.md,README.md,composer.json
           CURRENT=$(git archive HEAD | tar --list --exclude=src --exclude=src/* --exclude=.stubs --exclude=.stubs/*  --exclude=routes --exclude=routes/* --exclude=stubs --exclude=stubs/* --exclude=lang --exclude=lang/* --exclude=config --exclude=config/* --exclude=database --exclude=database/* --exclude=resources --exclude=resources/* | paste -s -d ,)
           echo CURRENT =${CURRENT}
           echo EXPECTED=${EXPECTED}

DATABASE.md

@@ -0,0 +1,137 @@
+# Model customization
+
+You can further customize the package Models using the `customize()` method with a callback that receives the freshly instanced model instance. For example, you may want to hide some attributes, or change the table and connection the Model by default. Preferably, you would do this in your `bootstrap/app.php`.
+
+```php
+use Illuminate\Foundation\Application;
+use Illuminate\Foundation\Configuration\Exceptions;
+use Illuminate\Foundation\Configuration\Middleware;
+use Vendor\Package\Models\Driver;
+
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        web: __DIR__.'/../routes/web.php',
+        commands: __DIR__.'/../routes/console.php',
+        health: '/up',
+    )
+    ->booted(function () {
+        // Add the relationship.
+        Car::customize(function (Car $model) {
+            $model->setTable('my_custom_car');
+            $model->setConnection('readonly-mysql');
+
+            $model->setHidden('private_notes');
+        })
+    })->create();
+```
+
+> [!TIP]
+>
+> For your convenience, the Migration will automatically pick up the table and connection you set in the Model.
+
+# Migration customization
+
+The library you have installed comes with a very hands-off approach for migrations. If you check the new migrations published at `database/migrations`, you will find something very similar to this:
+
+```php
+// database/migrations/2022_01_01_193000_create_cars_migration.php
+use Vendor\Package\Models\Car;
+
+return Car::migration();
+```
+
+Worry not, the migration will still work. It has been _simplified_ for easy customization.
+
+## Adding columns
+
+To add columns to the migration, add a callback to the `with()` method. The callback will receive the table blueprint so you can modify the table while it's being created.
+
+```php
+use Illuminate\Database\Schema\Blueprint;
+use Laragear\Package\Models\Car;
+
+return Car::migration()->with(function (Blueprint $table) {
+    $table->boolean('is_cool')->default(true);
+    $table->string('color');
+});
+```
+
+### Relationships
+
+If the package supports it, you may add relationships through their proper migration columns. For example, if we want to add the `driver` relationship to the model, we can use the native `resolveRelationUsing()` on your `bootstrap/app.php()`.
+
+```php
+use Illuminate\Foundation\Application;
+use Illuminate\Foundation\Configuration\Exceptions;
+use Illuminate\Foundation\Configuration\Middleware;
+use Vendor\Package\Models\Driver;
+
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        web: __DIR__.'/../routes/web.php',
+        commands: __DIR__.'/../routes/console.php',
+        health: '/up',
+    )
+    ->booted(function () {
+        // Add the relationship.
+        Car::resolveRelationUsing('driver', function (Car $car) {
+            return $car->belongsTo(Driver::class, 'driver_id')
+        })
+    })->create();
+```
+
+In the published package migration, you should be able to add the required column to connect your model like normal. In this case, we can use the [`foreignIdFor()`](https://laravel.com/docs/migrations#column-method-foreignIdFor) method to safely set the proper column type.
+
+```php
+use App\Models\Driver;
+use Illuminate\Database\Schema\Blueprint;
+use Laragear\Package\Models\Car;
+
+return Car::migration(function (Blueprint $table) {
+    // ...
+
+    $table->foreignIdFor(Driver::class);
+});
+```
+
+## After Up & Before Down
+
+If you need to execute logic after creating the table, or before dropping it, use the `afterUp()` and `beforeDown()` methods, respectively.
+
+```php
+use Illuminate\Database\Schema\Blueprint;
+use Laragear\Package\Models\Car;
+
+return Car::migration()
+    ->afterUp(function (Blueprint $table) {
+        $table->foreignId('sociable_id')->references('id')->on('users');
+    })
+    ->beforeDown(function (Blueprint $table) {
+        $table->dropForeign('sociable_id');
+    });
+```
+
+### Morphs
+
+Some packages will create a morph relation automatically to easily handle default relationship across multiple models. For example, a morph migration to support an `owner` being either one of your models `Company` or `Person`.
+
+```php
+use Laragear\Package\Models\Car;
+
+$car = Car::find(1);
+
+$owners = $car->owner; // App/Models/Company or App/Models/Person
+```
+
+You may find yourself with models that use UUID, ULID or other types of primary keys, but with a migration that creates morphs for integer primary keys.
+
+You can change the morph type with the `morph...` property access preferably, or the `morph()` method with `numeric`, `uuid` or `ulid` if you need to also set an index name (in case your database engine doesn't play nice with large ones).
+
+```php
+use Illuminate\Database\Schema\Blueprint;
+use Laragear\Package\Models\Car;
+
+return Car::migration()->morphUuid;
+
+return Car::migration()->morph('uuid', 'shorter_morph_index_name');
+```