Download the PHP package laragear/meta-model without Composer

Meta Model

Let other developers customize your package model and migrations.

[!TIP]

Did you come here from a package? You probably want to read the MIGRATIONS.md file instead.

Keep this package free

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word!

Requirements

• Laravel 10 or later

Installation

Fire up Composer and require it into your package:

Customizing models

Most of the time, your users will want to customize the models and migrations in your package. For example, they would want to add columns and cast them to specific data types, or modify which properties are hidden. This can be done with a model that incorporates the CustomizableModel trait.

From there, the end-developer can customize the model using the available static properties:

• $useConnection: The custom connection name to use.
• $useTable: The custom table name to use.
• $useCasts: The casts attributes to merge.
• $useFillable: The fillable attributes to merge.
• $useGuarded: The guarded attributes to merge.
• $useHidden: The hidden attributes to merge.
• $useVisible: The visible attributes to merge.
• $useAppends: The appends attributes to merge.

All of these static properties, except for $useTable, accept a Closure that receives the model and returns an array of attributes. The end-developer should modify these properties in the boot() method of the AppServiceProvider.

Appends

As you are guessing, the useAppend only works when your model has attributes accessors. If you expect the user to append attributes in your model serialization, ensure you have the proper accessors.

For example, we could add the color and chassis attribute accessors in our Car model.

Later, the end-developer can append these at runtime.

Customizable Migration

To allow customizable migrations, create a standard migration file, but, instead of returning a class that extends the default Migration class, return a migration() call to your model class.

Let's explain this is awesome.

For example, let's say we want to create a migration for a Car model. We will create a class that extends the CustomizableMigration class. From there, the table schema will be handled in the create() method.

After defining our default migration class, we need tell the Model where is in the $migration static property:

Once then, we can create the migration file 0000_00_00_000000_create_cars_table.php. Instead of returning a class that extends the default Laravel migration, we use our model and the migration() method.

Booting

You can run custom logic when the migration is instanced using the boot() method.

[!CAUTION]

The boot() method runs every time the migration is instanced. Ensure the method effects are idempotent when required.

Adding Custom Columns

You may want to let the end-developer to add additional columns to the migration. For that, just call addColumns() anywhere inside the create() method, ensuring you pass the Blueprint instance. A great place to call this is just before the timestamps() or after the primary key.

After that, in your migration file, add an empty callback to the migration() method, or use the with() method, so the end-developer knows he can extend the table schema.

An end-developer can also add multiple callbacks programmatically if needed, which are great to separate concerns.

[!TIP]

You can omit the addColumns() call if you don't want to support additional columns, as any added callback won't be executed.

Morphs

[!CAUTION]

Morphs are only supported for a single relation. Multiple morphs relations on a single table is highly discouraged.

If your migration requires morph relationships, you will find that end-developers won't always have the same key type in their application. This problem can be fixed by using the createMorph() or createNullableMorph() method with the Blueprint instance and the name of the morph type.

This will let the end-developer to change the morph type through the morph() method if needed. For example, if he's using ULID morphs for the target models, he may set it in one line:

Default index name

You may also set a custom index name for the morph. It will be used as a default, unless the user overrides it manually.

After Up & Before Down

An end-developer can execute logic after the table is created, and before the table is dropped, using the afterUp() and beforeDown() methods, respectively. This allows the developer to run enhance the table, or avoid failing migrations.

For example, the end-developer can use these methods to create foreign column references, and remove them before dropping the table.

[!IMPORTANT]

The afterUp() and beforeDown() adds callbacks to the migration, it doesn't replace them.

Package documentation

If you plan to add this to your package, you may also want to copy-and-paste the MIGRATIONS.md file in your package. This way developers will know how to use your model and migrations. Alternatively, you may also just copy its contents, or link back to this repository.

Laravel Octane compatibility

• There are no singletons using a stale application instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.
• Trait static properties are only written once by end-developer.

There should be no problems using this package with Laravel Octane.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

This specific package version is licensed under the terms of the MIT License, at time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2024 Laravel LLC.