Download the PHP package hosmelq/laravel-model-preferences without Composer

Laravel Model Preferences

Laravel Model Preferences provides a simple, fluent API for storing per-model preferences. You may store preferences in a JSON column or database tables and define defaults and validation rules per model.

Table of Contents

• Introduction
• Installation
• Configuration
  • Default Store
  • Store Configuration
  • Environment Variables
• Defining Preferences
  • The InteractsWithPreferences Trait
  • The preferencesConfig Method
  • Defaults
  • Validation Rules
• Using Preferences
  • Obtaining a Preferences Instance
  • Retrieving Preferences
  • Storing Preferences
  • Checking for Presence
  • Retrieving All Preferences
  • Defaults & Missing Values
  • Deleting Preferences
• Enum Keys
• Preference Stores
  • Column Driver (JSON Column)
  • Shared Table Driver (Polymorphic)
  • Per-Model Table Driver
  • Custom Tables & the Artisan Generator
• Adding Custom Preference Drivers
  • Implementing a Driver
  • Registering a Driver
• Model Cleanup
• Testing
• Changelog
• Contributing
• License

Introduction

Model preferences are small settings that live alongside a model, such as themes, notification options, or feature toggles. This package provides a clean API to read and write preferences with sensible defaults and validation.

Installation

First, install the package via Composer:

Next, publish the configuration and migration files:

If you prefer, you may publish the assets manually:

Finally, run your migrations if you are using the shared or table stores:

Configuration

After publishing the package assets, the configuration file will be located at config/model-preferences.php. This configuration file allows you to specify the default store and configure each store.

Default Store

You may specify the default preference store using the model-preferences.default configuration value or the MODEL_PREFERENCES_DRIVER environment variable. Supported drivers are column, shared, and table.

Store Configuration

Each store has its own configuration. For example, you may configure the JSON column name for the column driver or the database connection and table name for the shared and table drivers.

Environment Variables

The following environment variables are supported:

• MODEL_PREFERENCES_DRIVER (default: shared)
• MODEL_PREFERENCES_COLUMN_NAME (default: preferences)
• MODEL_PREFERENCES_TABLE (default: preferences)
• MODEL_PREFERENCES_DB_CONNECTION (default: DB_CONNECTION)

Defining Preferences

The InteractsWithPreferences Trait

To define preferences on a model, add the InteractsWithPreferences trait and implement the HasPreferences contract:

The preferencesConfig Method

The preferencesConfig method allows you to define defaults, validation rules, and the driver for a given model:

Defaults

Defaults may be defined per model using withDefaults. These values will be returned when the preference key is not present in the store:

Validation Rules

You may validate preferences using Laravel's validation rules. Rules are evaluated when calling set, and a PreferenceValidationException will be thrown if validation fails:

Using Preferences

Obtaining a Preferences Instance

Call the preferences method on your model to obtain a scoped preferences instance:

Retrieving Preferences

Use get to retrieve a single preference value. You may pass a default value or a closure that will be evaluated lazily. To retrieve multiple preferences at once, use getMultiple:

Storing Preferences

Use set to store a preference value or setMultiple to store multiple values:

Checking for Presence

Use has to determine if a preference key exists. You may also use missing to check the opposite:

Retrieving All Preferences

Use all to retrieve all stored preferences:

Defaults & Missing Values

Preference lookup follows these rules:

• If the preference exists (even if its value is null), get returns that value.
• If the preference does not exist and a model default is configured, the default is returned.
• If the preference does not exist and a default is passed to get, that default is returned.
• Otherwise, null is returned.

Deleting Preferences

Use delete to remove a single preference, deleteMultiple for batches, and clear to remove all preferences:

Enum Keys

Preference keys may be strings, backed enums, or unit enums. Backed enums use their backed value, while unit enums use their name:

Preference Stores

You may select a store globally via configuration or per model using withDriver.

Column Driver (JSON Column)

The column driver stores all preferences in a single JSON column on the model's table. You may configure the column name via withColumn or the model-preferences.stores.column.name setting. When using this driver, the InteractsWithPreferences trait automatically adds a JSON cast for the configured column.

Example migration column:

Shared Table Driver (Polymorphic)

The shared driver stores preferences in a single table using a polymorphic relation. The published migration creates a preferences table with preferable_type, preferable_id, key, and value columns.

Per-Model Table Driver

The table driver stores preferences in a dedicated table per model. When using this driver, you must configure the table name in preferencesConfig:

Custom Tables & the Artisan Generator

You may generate a preferences table migration using the Artisan command:

This stub creates a table with model_id, key, and value columns and a unique index on model_id and key.

Adding Custom Preference Drivers

Implementing a Driver

To add your own driver, implement the PreferenceDriver contract. If you need to distinguish between missing values and null, implement PresenceAwarePreferenceDriver and return a PreferenceRead instance from getWithPresence.

Registering a Driver

Register your driver via the preferences manager, then configure your model to use it:

Model Cleanup

When using the shared or table drivers, the InteractsWithPreferences trait automatically removes stored preferences when the model is deleted.

Testing

Changelog

See CHANGELOG.md for a list of changes.

Contributing

Pull requests are welcome. Please run the test suite before submitting changes.

License

The MIT License (MIT). Please see License File for more information.