- How do I install kodeine/laravel-meta in a Laravel application?
- Run composer require kodeine/laravel-meta, then add the Metable trait to each Eloquent model that needs metadata. Each metable model also needs its own meta table migration, and you can override settings such as $metaTable, $metaKeyName, and $defaultMetaValues on the model. Laravel package auto-discovery handles the service provider, so no manual registration is normally required.
- Which Laravel versions does kodeine/laravel-meta support?
- The v2 line targets Laravel 8 and newer; Laravel 7 and below require the older master or v1 branch. Before adopting it, verify the latest release and CI status because the repository has very low adoption and its README badge still points at the retired travis-ci.org service. Test against the exact Laravel version you run, especially if you are on a newer LTS.
- How does fluent meta access work on an Eloquent model?
- After adding the Metable trait, you can read, set, and unset meta keys like normal model properties, for example $post->content = 'value' or unset($post->content). The package overrides getAttribute and setAttribute to route these accesses to the meta table, with $disableFluentMeta and getAttributeRaw/setAttributeRaw as escape hatches. Because this changes attribute access globally on the model, check for conflicts with casts, encryption, audit traits, or other packages that also override attribute handling.
- How do I create the meta table for a model?
- Each metable model uses its own meta table, conventionally named {model}_meta, so you write one migration per model. The migration defines the model key, meta key, and value columns, and you can change the table name via the $metaTable property. This per-model convention avoids polymorphic joins but means migration work grows with every metable model you add.
- Why does setting a meta value to its default delete the row?
- In kodeine/laravel-meta, assigning a meta value equal to its configured default removes the meta row rather than storing it. That is useful when metas model sparse exception state, because the default is represented by absence. It is dangerous for a general-purpose key-value store, where a naive integration can appear to lose writes. Configure $defaultMetaValues deliberately and test write and read behavior.
- How can I query models by their meta values?
- Use the whereMeta scope, for example User::whereMeta($key, $value)->get(). The meta key is indexed, but the value column is unindexed text, so filtering or sorting on values will not scale for large datasets. If you need heavy querying, aggregation, or joins on those attributes, promote them to real database columns instead.
- How do I avoid N+1 queries when loading meta data?
- Metas live in a separate table, so eager load them with with('metas') whenever you will access meta properties across a collection of models. Enforce that convention in repositories or query scopes, because lazy access per model will issue extra queries. Also review $hideMeta if meta values should not appear in serialized model output.
- When are meta values persisted, and what are createdWithMetas and savedWithMetas?
- By default, metas are persisted when the model is saved, so setting a meta property and calling save() writes both the model and its meta. saveMeta() lets you persist meta separately when you need to decouple the two paths. The createdWithMetas and savedWithMetas events exist because queued jobs can otherwise read stale or missing meta, so use them when meta must be available immediately after model creation or save.
- What breaking changes should I know about when upgrading to v2?
- Version 2 drops Laravel 7 and below, removes the __get, __set, and __isset methods, and removes the legacy getter magic that mapped getSomething() to $model->something. It also renames getMetaDefaultValue to getDefaultMetaValue, changes the second getMeta argument to a default value for null, replaces whereMeta with scopeWhereMeta, and removes getModelKey. If your models alias Metable magic methods or define their own attribute accessors, remove those aliases and test attribute access carefully after upgrading.
- What are alternatives to kodeine/laravel-meta, and when should I not use it?
- Alternatives include real database columns, JSON columns on the model table, or a custom polymorphic key-value table, depending on how often the attributes change and how they are queried. Use real columns when you need type safety, joins, indexes, aggregation, or frequent filtering. Kodeine/laravel-meta fits sparse, per-record annotations on content-like models, but it is a poor fit for load-bearing domain data or high-scale meta queries.