Skip to content
meta / 1

Defining meta fields

Last updated:

On this page

Define a model's meta fields once, in a service provider's boot(), with javaabu/stencil fields:

use App\Models\Post;
use Javaabu\Meta\Facades\MetaFields;
use Javaabu\Stencil\Fields\Checkbox;
use Javaabu\Stencil\Fields\DatePicker;
use Javaabu\Stencil\Fields\Select;
use Javaabu\Stencil\Fields\Textarea;
use Javaabu\Stencil\Fields\TextInput;

public function boot(): void
{
    MetaFields::for(Post::class, [
        TextInput::make('subtitle')->label(__('Subtitle'))->maxLength(255)->thaana(),
        Textarea::make('summary')->label(__('Summary'))->thaana(),
        Checkbox::make('featured')->label(__('Featured')),
        TextInput::make('views')->label(__('Views'))->integer(),
        TextInput::make('rating')->label(__('Rating'))->numeric()->minValue(0)->maxValue(5),
        DatePicker::make('event_date')->label(__('Event date')),
        Select::make('tags')->label(__('Tags'))->multiple()->options([
            'news' => __('News'),
            'sports' => __('Sports'),
        ]),
    ]);
}

Each field's name is the meta key. The field gives:

  • The meta type: which column the value is stored in and how it's cast. It's inferred from the field (below).
  • Validation: the field's rules (required, maxLength, options, …) plus the type's rules.
  • The form input of meta forms, with its label, help, placeholder, Thaana and conditions.

Defining a field isn't required to store a value: setMeta() takes any key. But only defined fields can be mass assigned or edited in a meta form, and queries and sorts know their column.

Types

Stencil field Meta type Stored in Read back as
TextInput, single Select, Radio, Hidden string (255 characters at most) value_string, indexed string
Textarea, Wysiwyg text value_text string
TextInput::numeric() float value_float, indexed float
TextInput::integer() integer value_int, indexed int
Checkbox boolean value_int (1 or 0), indexed bool
DatePicker date value_datetime at midnight, indexed Carbon
DateTimePicker datetime value_datetime, indexed Carbon
TimePicker time value_string as H:i:s, indexed string
Select::multiple(), CheckboxList json value_json array

Choose a type yourself with ->metaType():

TextInput::make('price')->integer()->metaType('float');
TextInput::make('code')->metaType('text');

TextInput::make('views')->integer() is stored as an integer on its own, and ->numeric() as a float.

Fields that save to a relationship (Select::relationship() for a BelongsToMany, or a file upload into a media collection) can't be meta fields. Defining one throws a MetaException.

Fields by type

To give a key only a type, use key => type. The type provides a plain field for it (a text input, a checkbox, a date picker, …):

MetaFields::for(Post::class, [
    'views' => 'integer',
    'rating' => 'float',
    'featured' => 'boolean',
]);

Groups

A group adds fields to some records of a model only. For example, events and news are both Posts, but only events have a start date. Define the group's fields with group:, and say which group a record is in with metaGroup():

MetaFields::for(Post::class, [TextInput::make('subtitle')]);                     // every post
MetaFields::for(Post::class, [DatePicker::make('starts_on')], group: 'event');   // events only
MetaFields::for(Post::class, [Checkbox::make('breaking')], group: 'news');       // news only
class Post extends Model
{
    use HasMeta;

    public function metaGroup(): ?string
    {
        return $this->type;
    }
}

A record's fields are the model's own fields, then its group's. A group can redefine a key of the model's own fields. Queries on the model know every group's fields: Post::whereMeta('starts_on', '>', today()). If two groups define the same key with different types, querying that key throws: give it one type.

Closures

Pass a closure to build the fields when they're needed rather than when the provider boots. Use one when the fields depend on config, the database or the current user:

MetaFields::for(Post::class, fn () => [
    Select::make('category')->options(Category::pluck('name', 'slug')->all()),
]);

Reading definitions

MetaFields::fields(Post::class);           // ['subtitle' => MetaField, …]: the model's own fields
MetaFields::fields($post);                 // the record's fields, with its group's
MetaFields::fields(Post::class, 'event');  // a group's
MetaFields::field($post, 'subtitle');      // ?MetaField
MetaFields::keys($post);                   // ['subtitle', 'starts_on']
MetaFields::groups(Post::class);           // ['event', 'news']
$post->metaFields(); $post->metaField('subtitle');

A Javaabu\Meta\Definitions\MetaField has these properties:

  • key
  • type: a MetaType
  • field: the stencil field. Each definition gets its own copy, so changing it doesn't affect other forms.
  • translatable
  • group

Definitions of a parent class apply to its subclasses. Each subclass can add its own.

Documentation
All packages

javaabu/meta

Source on GitHub