Fields / $fields

$fields->get($name)

Get a single field by name or ID.

• Arguments: get(string|int $name)
• Returns: Field|null

$field = $fields->get('title');
$field = $fields->get('body');
$field = $fields->get(123); // by ID

$fields is also directly iterable:

foreach($fields as $field) {
    echo "$field->name ($field->type->shortName): $field->label\n";
}

$fields->fieldNameExists($name)

Check whether a custom field with the given name exists. Unlike get(), this does not trigger lazy loading of the field.

• Returns: bool

if($fields->fieldNameExists('my_field')) {
    $field = $fields->get('my_field');
}

$fields->getAllNames($indexType)

Get all field names as an array.

• Arguments: getAllNames(string $indexType = '')
• Returns: array
• Pass '' (default) for a plain indexed array of names.
• Pass 'name' for an associative array where both keys and values are field names.
• Pass 'id' for an associative array keyed by field ID.

$names = $fields->getAllNames();         // ['title', 'body', 'images', ...]
$byId  = $fields->getAllNames('id');     // [1 => 'title', 2 => 'body', ...]

$fields->getAllIds()

Get all field IDs indexed by their field name.

• Returns: array — ['fieldName' => id, ...]

$ids = $fields->getAllIds(); // ['title' => 1, 'body' => 2, ...]

$fields->new($type, $name, $options)

Create, save, and return a new field. This is the recommended way to create a field programmatically.

• Arguments: new(string|array $type, string $name = '', string|array $options = [])
• Returns: Field
• Throws WireException if the fieldtype is not found or the field cannot be saved.
• $type accepts full class name ('FieldtypeText'), or short names ('Text', 'text').
• $options can be a label string, or an associative array of property/value pairs.
• Pass an array as the first argument to specify all settings at once (must include type and name keys).
• Available 3.0.258.

// Create a text field
$field = $fields->new('text', 'my_text', 'My Text Field');

// Create with options array
$field = $fields->new('textarea', 'body', [
    'label'          => 'Body',
    'textformatters' => ['TextformatterEntities'],
    'columnWidth'    => 100,
]);

// Using an array as first argument (all-in-one)
$field = $fields->new([
    'type'  => 'text',
    'name'  => 'summary',
    'label' => 'Summary',
]);

$fields->newField($type, $name, $options)

Create a new Field instance without saving it to the database. Use this when you need to configure a field further before saving, or when you want to save it yourself.

• Arguments: newField(string|array $type, string $name = '', string|array $options = [])
• Returns: Field (unsaved)
• Accepts the same arguments as $fields->new().
• Call $fields->save($field) after configuring it.

$field = $fields->newField('integer', 'sort_order', 'Sort Order');
$field->min = 0;
$field->max = 999;
$fields->save($field);

$fields->save($field)

Save a field to the database. Creates it if new, updates it if existing.

• Arguments: save(Field $field)
• Returns: bool

$field = $fields->get('body');
$field->label = 'Page Body';
$fields->save($field);

When saving a new field that has a Field::flagGlobal flag set, the field is automatically added to all existing fieldgroups that don't already contain it.

$fields->delete($field)

Delete a field from the database. Throws a WireException if the field is currently assigned to any fieldgroup, or if it is a system field.

• Arguments: delete(Field $field)
• Returns: bool

$field = $fields->get('old_field');
if($field && !$field->numFieldgroups()) {
    $fields->delete($field);
}

$fields->clone($field, $name)

Clone a field and return the clone. The clone is saved automatically.

• Arguments: clone(Field $field, string $name = '')
• Returns: Field — the new clone, or false on failure
• System, permanent, and global flags are not copied to the clone.
• If $name is omitted, a name is auto-generated (e.g. my_field_2).

$original = $fields->get('body');
$clone = $fields->clone($original, 'body_sidebar');

Template/fieldgroup context enables a field to have unique settings or overrides when in the context of a particular Fieldgroup.

$fields->saveFieldgroupContext($field, $fieldgroup, $namespace)

Save fieldgroup-specific context data for a field — the per-fieldgroup settings such as label/description/notes overrides, columnWidth, collapsed, access flags, and any other built-in or custom settings (most are supported).

• Arguments: saveFieldgroupContext(Field $field, Fieldgroup $fieldgroup, string $namespace = '')
• Returns: bool
• $field must be in fieldgroup context (i.e. retrieved via $fieldgroup->getFieldContext($field)) before this is called.

• Source files: wire/core/Fields/Fields.php (the $fields manager) and wire/core/Field/Field.php (the Field object).
• $fields->get() accepts a field name (string) or field ID (int).
• Fields created with $fields->new() are automatically saved. Use $fields->newField() if you need to configure the field further before saving.
• Deleting a field that is still assigned to a fieldgroup throws a WireException. Call $field->numFieldgroups() first to check.
• The flagGlobal flag causes a field to be automatically added to all existing fieldgroups on save, unless the fieldgroup's template has noGlobal set.
• Field tags are space-separated in the tags property; read them as an array via tagList or $field->getTags().
• $fields->getFieldtype($name) is a convenient shortcut for $fieldtypes->get($name) that also accepts abbreviated type names such as 'text' or 'image'.
• Each Fieldtype module may define additional field properties that appear on the Field object; see the individual Fieldtype's API.md for details.