Laravel Enum Seeder

This extension allows easy creation of DB seeders for the dictionary (enum) type tables, such as statuses, types, categories and so on.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the "require" section of your composer.json.

Usage

Almost every project requires specification of so called 'dictionary' or 'enum' entities, such as statuses, types, categories and so on. It is not always practical to keep such data as PHP enums or class-base enums. Sometimes it has to be put into a database table. For example: when we need to provide ability for the system administrator to edit human-readable title or description of the particular category or status, or enable/disable particular records, or simply to keep the database integrity.

Obviously keeping dictionary (enum) in the database tables creates a problem of its synchronization. As our project evolves new categories and statuses may appear, and some may become obsolete. Thus, we need a tool, which allows updating of the data in the dictionary (enum) tables. This package provides such a tool.

The idea is in creation of the special kind of database seeder, which synchronizes particular enum table with the predefined data in the way, it could be invoked multiple times without creation of redundant records or breaking an integrity. You can create such seeder extending Illuminatech\EnumSeeder\EnumSeeder. For example:

With seeders defined in such way, you can invoke following command after each project update:

As the result table 'item_categories' will always be up-to-date with the values from ItemCategorySeeder::rows(). In case you need to add a new item category, you can simply add another entry to the ItemCategorySeeder::rows() and run the seeder again. It will gracefully add the missing records, keeping already existing ones intact.

You can control the seeding options overriding methods from Illuminatech\EnumSeeder\ControlsWorkflow.

Heads up! Make sure you do not setup a sequence (autoincrement) for the primary key (id) of the dictionary (enum) table, otherwise EnumSeeder may be unable to properly handle its data synchronization.

The example of the database migration for the dictionary (enum) table:

Tip: Remember that it is not mandatory for primary key field to be always an integer - you may use strings for it just as well, keeping your database records more human-readable. For example:

Processing of the obsolete records

By default Illuminatech\EnumSeeder\EnumSeeder does not deletes the records, which are no longer specified at rows() method, as the database may already contain the references to those records via foreign keys, and deleting enum value may cause a data loss. However, if you sure what you are doing, you can control the deletion feature via shouldDeleteObsolete() method. For example:

Each time ContentPageSeeder will be called, it will delete all the records from 'content_pages', which 'id' is missing at rows() method declaration.

Note: Remember that you can specify a complex logic at shouldDeleteObsolete() to suite your needs. For example, you can allow deleting of obsolete rows for "local" environment, while forbidding it for "prod":

Deletion is not the only way to deal with obsolete records. In order to keep the database integrity, it is better to simply mark the obsolete records as outdated, e.g. perform a "soft-delete". This can be achieved via shouldUpdateObsoleteWith() method. For example:

Common data for the records creation

You may simplify rows() method for the particular seeder extracting common attributes in shouldCreateWith() method. It defines the default attribute values for each created record, unless it explicitly overridden by the entry from rows(). For example:

Updating of the existing records

Each time the enum seeder is executed it updates existing records with the actual data from rows() if they mismatch. You can disable the update defining shouldUpdateExisting() method. For example:

However, most likely you will need to allow updating for some attributes, while disallow it for the others. For example, if you setup content pages, you probably want control whether particular page is active or not via seeder, while the content fields, which are edited by the administrator, should remain intact. This can be achieved using shouldUpdateExistingOnly() method. For example:

You may specify the attributes, which should be applied on each row update, using shouldUpdateExistingWith(). For example:

Heads up! Methods shouldUpdateExistingOnly() and shouldUpdateExistingWith() take precedence over shouldUpdateExisting(). If, at least, one of them defined, return value of shouldUpdateExisting() will be ignored, and the records will be updated anyway.

Eloquent enum seeders

It might be more convenient for you to operate Eloquent models instead of plain tables for enum seeding. Manipulating data via active record models allows you to use its full features such as "events", "timestamps" and "soft-delete". You can setup a enum seeder for particular Eloquent model using Illuminatech\EnumSeeder\EloquentEnumSeeder. For example:

Heads up! Remember to disable Illuminate\Database\Eloquent\Model::$incrementing for the enum Eloquent model, otherwise EloquentEnumSeeder may be unable to properly handle its data synchronization. For example:

Heads up! In case you are using string values as a primary key for enum table, you should also adjust Illuminate\Database\Eloquent\Model::$keyType accordingly. For example: