Download the PHP package daikazu/laravel-meta without Composer
On this page you can find all versions of the php package daikazu/laravel-meta. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download daikazu/laravel-meta
More information about daikazu/laravel-meta
Files in daikazu/laravel-meta
Package laravel-meta
Short Description This is my package laravel-meta
License MIT
Homepage https://github.com/daikazu/laravel-meta
Informations about the package laravel-meta
laravel Meta
⚠️ Work in progress. This package is under active development and not yet stable. APIs may change without notice and it is not recommended for production use yet.
Typed, casted, queryable key-value metadata for any Eloquent model.
- One
$model->metaproperty gives you a full read/write/delete API. - Dot-notation for nested JSON values.
- Built-in casts (
string,integer,float,boolean,array,json,collection,datetime,encrypted) plus custom casts and zero-boilerplate plain value objects. - Two storage drivers: separate
model_metatable (default) or a JSON column on the model's own table. - Query scopes:
whereMeta,whereMetaIn,whereMetaBetween,whereMetaNull,orderByMeta, and more. - Optional in-memory caching, event broadcasting, schema validation, computed meta, and an indexed sidecar table for hot keys.
- 64 tests (Pest), PHPStan max, Laravel 11 / 12 / 13.
Requirements
- PHP 8.3+
- Laravel 11, 12, or 13
Installation
Run the install command to publish the config, publish the migrations, and optionally run them:
The command publishes two tags:
laravel-meta-config→config/meta.phplaravel-meta-migrations→ two migration stubs (create_model_meta_table,create_model_meta_index_table)
To force-overwrite existing published files:
Model Setup
Add the HasMeta trait to any Eloquent model:
That's it. The $model->meta property is now a MetaBag instance.
Optional: the HasMetadata interface
The HasMeta trait already provides everything, but you can additionally implement the HasMetadata interface for stronger typing. It's purely additive — no behaviour changes — and lets static analysis and other packages (such as daikazu/filament-meta) accept "a model with metadata" without falling back to mixed:
The interface declares a single method, meta(): MetaBag (and the @property-read MetaBag $meta accessor), both of which the trait already satisfies — so implementing it never requires extra code.
Basic Usage
Reading
Writing
Deleting
Existence
Dot-Notation
Dot notation reads and writes into nested JSON values stored under the top-level key:
Buffering on Unsaved Models
Writing to ->meta before the model is saved is safe. Values are buffered and flushed automatically inside the saved hook:
Casting
Declared Casts
Define $metaCasts on your model to control how values are serialised and hydrated:
Built-In Cast Aliases
| Alias | Notes |
|---|---|
string |
|
integer / int |
|
float / double |
|
boolean / bool |
|
array |
PHP array, JSON-encoded at rest |
json |
Alias for array |
collection |
Illuminate\Support\Collection |
datetime |
CarbonImmutable |
encrypted |
Encrypts the raw value using Laravel's encrypter |
Custom Cast Classes
Implement Daikazu\LaravelMeta\Contracts\MetaCast:
Then use the FQCN in $metaCasts:
The Castable Contract
For classes that produce their own cast, implement Daikazu\LaravelMeta\Contracts\Castable:
CastManager calls ::castUsing() automatically when it sees a Castable class.
Plain Value Objects (Zero Boilerplate)
Any class that is not a MetaCast or Castable is automatically wrapped in ValueObjectCast, which serialises and hydrates via the constructor's public promoted properties. No custom cast class needed:
Global Custom Casts via Config
Register additional aliases in config/meta.php so every model can use them by alias name:
Encrypted Meta
Two equivalent ways to encrypt a value at rest:
The encrypted() modifier applies only to the immediately following set() or setMany() call.
Storage Drivers
Table Driver (Default)
Stores each top-level key as a row in the model_meta table. This is the default and requires no per-model configuration.
JSON Column Driver
Stores all meta for a model in a single JSON column on the model's own table. Add the column and cast to your model:
When $metaColumn is defined, the JSON driver is selected automatically regardless of the global driver config. You can also set protected string $metaDriver = 'json' explicitly, in which case $metaColumn falls back to the json_column config value (meta_data by default).
Driver Resolution Order
protected string $metaDriver = '...'on the model — explicit override.protected string $metaColumn = '...'on the model — impliesjsondriver.meta.driverconfig key — global default (table).
Query Scopes
All scopes are available on every model that uses HasMeta.
Eager Loading
withMeta() is the canonical scope for eager-loading metadata. It loads the underlying metaRecords relation so the MetaBag can prime itself without additional queries:
Why withMeta() and not with('meta')?
$model->meta is a computed property (accessor) that returns a MetaBag — it is not an Eloquent relation. The underlying polymorphic relation is metaRecords. withMeta() calls ->with('metaRecords') under the hood and is the intended API.
Caching
Caching is enabled by default and wraps every repository read with the configured cache store.
Clear the cache manually:
Events
Events are dispatched after every write (enabled by default, toggle with 'events' => false in config).
| Event | When |
|---|---|
Daikazu\LaravelMeta\Events\MetaCreated |
A new key is written |
Daikazu\LaravelMeta\Events\MetaUpdated |
An existing key is overwritten |
Daikazu\LaravelMeta\Events\MetaDeleted |
A key is removed (forget, flush) |
All three carry the same constructor signature:
Example listener:
Schemas
Register a schema to attach casts and validation rules to specific keys. Schemas must be registered before the first ->meta access on that model class (e.g. in a service provider or AppServiceProvider::boot()).
Schema Field Classes
| Class | Cast applied |
|---|---|
TextMeta |
string |
NumberMeta |
float |
ToggleMeta |
boolean |
DateMeta |
datetime |
JsonMeta |
json |
All field classes extend MetaField and share these fluent methods: ->required(), ->min(int), ->max(int), ->default(mixed).
Validation
Call ->validate() with an array of key-value pairs to run the schema's Laravel validation rules:
Only keys present in both the payload and the schema are validated; unknown keys pass through unchecked.
Computed Meta
Computed meta keys are resolved lazily from a callback and are never persisted. Register before first ->meta access.
Setting a computed key throws InvalidArgumentException.
Indexed Metadata
For hot keys that need fast WHERE queries without JSON path overhead, configure them in indexed_keys. The package maintains a sidecar model_meta_index table with typed columns (string_value, numeric_value, boolean_value, datetime_value).
New writes to listed keys update the sidecar automatically. To backfill existing rows after adding a key to the list:
Warning — backfill before relying on a newly indexed key. Adding a key to
indexed_keysfor a table that already has data does not retroactively populate the sidecar. Until you runphp artisan meta:index,whereMeta()on that key (which routes through the sidecar) will return incomplete results, silently omitting pre-existing rows. Always run the backfill immediately after adding a key.Note — only
whereMeta()uses the sidecar. Equality/operator queries viawhereMeta()(andwhereMetaNot) read from the indexed sidecar table.whereMetaIn,whereMetaBetween,whereMetaNull, andorderByMetaalways read the basemodel_metatable and are unaffected by indexing.
Artisan Commands
| Command | Description |
|---|---|
meta:install |
Publish config + migrations, optionally run migrate |
meta:install --force |
Force-overwrite previously published files |
meta:cache:clear |
Flush the configured meta cache store |
meta:index |
Rebuild the indexed metadata sidecar from existing rows |
Testing
64 tests, Pest 4, PHPStan max (level 10).
Changelog
Please see CHANGELOG for recent changes.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
- Mike Wall
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of laravel-meta with dependencies
spatie/laravel-package-tools Version ^1.16
illuminate/contracts Version ^11.0||^12.0||^13.0