Download the PHP package kolossal-io/laravel-multiplex without Composer

A Laravel package to attach time-sliced meta data to Eloquent models.

View Table of Contents

--- ## What it does Multiplex allows you to attach time-sliced metadata to Eloquent models in a convenient way. ## Features - Metadata is saved in versions: Schedule changes to metadata, change history or retrieve metadata for a specific point in time. - Supports fluent syntax: Use your model’s metadata as if they were properties. - Polymorphic relationship allows adding metadata to any Eloquent model without worrying about the database schema. - Easy to try: Extend existing database columns of your model with versionable metadata without touching or deleting your original columns. - Type conversion system heavily based on [Laravel-Metable](https://github.com/plank/laravel-metable) allows data of numerous different scalar and object types to be stored and retrieved. ## Why another Metadata Package? The main difference is that the metadata in Multiplex has a timestamp that defines validity. This allows changes to be tracked and planned. You can inspect all metadata on your model at a specific point in time and Multiplex will by default only give you the most current. Since Multiplex is storing the metadata in a [polymorphic](https://laravel.com/docs/9.x/eloquent-relationships#polymorphic-relationships) table, it can easily be plugged into existing projects to expand properties of your models. This even works without removing the relevant table columns of your model: They are used as a fallback. And it’s low profile: If you don't like it, just [remove the `HasMeta` Trait](#installation) and everything is back to normal. ## Table of Contents - [Installation](#installation) - [Attaching Metadata](#attaching-metadata) - [Retrieving Metadata](#retrieving-metadata) - [Query by Metadata](#query-by-metadata) - [Events](#events) - [Time Traveling](#time-traveling) - [Limit Meta Keys](#limit-meta-keys) - [Extending Database Columns](#extending-database-columns) - [Deleting Metadata](#deleting-metadata) - [Performance](#performance) - [Configuration](#configuration) - [Enum Support](#enum-support) - [UUID and ULID Support](#uuid-and-ulid-support) ## Installation You can install the package via composer: Publish the migrations to create the `meta` table where metadata will be stored. Attach the `HasMeta` trait to any Eloquent model that needs meta attached. ## Attaching Metadata By default you can use any `key` for attaching metadata. You can [limit which keys can be used](#limit-meta-keys). You may also set multiple meta values by passing an `array`. All metadata will be stored automatically when saving your model. You can also save your model without saving metadata. You can reset metadata changes that were not yet saved. Metadata can be stored right away without waiting for the parent model to be saved. ### Schedule Metadata You can save metadata for a specific publishing date. This way you can change historic data as well. You may also save multiple metadata records at once. ### How Metadata is stored Multiplex will store metadata in a polymorphic table and take care of serializing and unserializing datatypes for you. The underlying polymorphic `meta` table may look something like this: | metable_type | metable_id | key | value | type | published_at | | --------------- | ---------: | ----- | ----: | ------- | ------------------- | | App\Models\Post | `1` | color | #000 | string | 2022-11-29 13:13:45 | | App\Models\Post | `1` | likes | 24 | integer | 2020-01-01 00:00:00 | | App\Models\Post | `1` | hide | true | boolean | 2022-11-27 16:32:08 | | App\Models\Post | `1` | color | #fff | string | 2030-01-01 00:00:00 | The corresponding meta values would look like this: ## Retrieving Metadata You can access metadata as if they were properties on your model. Or use the `getMeta()` method to specify a fallback value for non-existent meta. You can also retrieve the `meta` relation on your model. This will only retrieve the most recent value per `key` that is released yet. There is a shorthand to pluck all the current meta data attached to the model. This will include all [explicitly defined meta keys](#limit-meta-keys) with a default of `null`. If you instead want to retrieve all meta that was published yet, use the `publishedMeta` relation. If you want to inspect _all_ metadata including unpublished records, use the `allMeta` relation. You can determine if a `Meta` instance is the most recent published record for the related model or if it is not yet released. ### Querying `Meta` Model There are also some query scopes on the `Meta` model itself that may be helpful. By default these functions will use `Carbon::now()` to determine what metadata is considered the most recent, but you can also pass a datetime to look from. ## Query by Metadata ### Querying Metadata Existence You can query records having meta data for the given key(s). ### Querying Metadata Absence You can query records not having meta data for the given key(s). ### Querying Metadata by Value You can retrieve models having meta with the given key and value. Multiplex will take care of finding the right datatype for the passed query. You may also query by an array if values. Each array value will be typecasted individually. If you would like to query without typecasting use `whereRawMeta()` instead. You can also define which [datatype](config/multiplex.php) to use. ### Querying empty or non-empty Metadata You can query for empty or non-empty metadata where `null` or empty strings would be considered being empty. ## Events You can listen for the following events that will be fired by Multiplex. ### `MetaHasBeenAdded` This event will be fired once a new version of meta is saved to the model. ### `MetaHasBeenRemoved` This event will be fired once metadata is removed by using [`deleteMeta`](#deleting-metadata). The event will fire only once per key and the `$meta` property on the event will contain the latest meta only. ## Time Traveling You can get the metadata for a model at a specific point in time. This way you can inspect the whole set of metadata that was valid at the time. You can also query by meta for a specific point in time. Remember to travel back if you want to perform further actions. ## Limit Meta Keys You can limit which keys can be used for metadata by setting `$metaKeys` on the model. By default all keys are allowed. You can also change the allowed meta keys dynamically. You might as well cast your attributes using the `MetaAttribute` cast which will automatically allow the attribute being used as a meta key. Trying to assign a value to a meta key that is not allowed will throw a `Kolossal\Multiplex\Exceptions\MetaException`. If you have [Eloquent Strictness](https://laravel.com/docs/10.x/eloquent#configuring-eloquent-strictness) enabled it is recommended to [explicitely cast the meta attributes to `MetaAttribute`](https://github.com/kolossal-io/laravel-multiplex/issues/19#issuecomment-1584150675). ## Typecast Meta Keys Sometimes you may wish to force typecasting of meta attributes. You can bypass guessing the correct type and define which type should be used for specific meta keys. ## Extending Database Columns By default Multiplex will not touch columns of your model. But sometimes it might be useful to have meta records as an extension for your existing table columns. Consider having an existing `Post` model with only a `title` and a `body` column. By explicitely adding `body` to our array of meta keys `body` will be handled by Multiplex from now on – not touching the `posts` table, but using the database column as a fallback. In case of using Multiplex for extending table columns, Multiplex will remove the original column when retrieving models from the database so you don’t get stale data. ## Deleting Metadata You can delete any metadata associated with the model from the database. ## Performance Since Multiplex stores metadata in a polymorphic [One To Many](https://laravel.com/docs/9.x/eloquent-relationships#one-to-many-polymorphic-relations) relationship querying your models could easily result in a [`N+1` query problem](https://laravel.com/docs/9.x/eloquent-relationships#eager-loading). Depending on your use case you should consider eager loading the `meta` relation, for example using `$with` on your model. This might be especially useful if you are [extending database columns](#extending-database-columns). ## Configuration There is no need to configure anything but if you like, you can publish the config file with: ## Enum Support Multiplex supports [backed enumerations](https://www.php.net/manual/en/language.enumerations.backed.php) introduced in PHP 8.1 whereas basic enumerations would not work. ## UUID and ULID Support If your application uses UUIDs or ULIDs for the model(s) using metadata, you may set the `multiplex.morph_type` setting to `uuid` or `ulid` **before** running the migrations. You might as well set the `MULTIPLEX_MORPH_TYPE` environment variable instead, if you don’t want to publish the configuration file. This will ensure `Meta` models will use UUID/ULID and that proper keys and foreign keys are used when running the migrations. ## Credits This package is heavily based on and inspired by [Laravel-Metable](https://github.com/plank/laravel-metable) by [Sean Fraser](https://github.com/frasmage) as well as [laravel-meta](https://github.com/kodeine/laravel-meta) by [Kodeine](https://github.com/kodeine). The [Package Skeleton](https://github.com/spatie/package-skeleton-laravel) by the great [Spatie](https://spatie.be/) was used as a starting point. ## License

Copyright © [kolossal](https://kolossal.io). Released under [MIT License](LICENSE.md).