Fields

Fields define the columns that can be imported from a CSV file. Each field maps a CSV header to a model attribute and carries metadata for validation, display, and auto-mapping.

ImportField is an immutable value object. All builder methods return a new instance rather than mutating the original.

Creating Fields

ImportField::make(string $key)

Creates a field with the given key. The key corresponds to the model attribute name. A human-readable label is auto-generated from the key by converting underscores and dashes to spaces and applying title case.

use Tapix\Core\Fields\ImportField;

ImportField::make('first_name'); // label: "First Name"
ImportField::make('email');      // label: "Email"

ImportField::id()

A pre-configured ID field designed for record matching. It applies ULID validation and uses a fingerprint icon.

ImportField::id();

Builder Methods

->label(string $label)

Sets a custom display label for the field.

ImportField::make('dob')->label('Date of Birth');

->required(bool $required = true)

Marks the field as required. Required fields must be mapped to a CSV column and cannot be left empty.

ImportField::make('email')->required();

->rules(array $rules)

Sets Laravel validation rules as an array. These rules are applied to each cell value during the review step.

ImportField::make('email')->rules(['required', 'email', 'max:255']);

->guess(array $aliases)

Adds alternative column name aliases used during auto-mapping. When Tapix encounters a CSV header that matches any alias (after normalization), it maps that column to this field automatically.

ImportField::make('first_name')->guess(['fname', 'first', 'given name']);

->example(string $example)

Provides an example value displayed in the UI to help users understand the expected format.

ImportField::make('phone')->example('+1 (555) 123-4567');

->type(?FieldType $type)

Sets the data type for the field. Types influence validation rules, icons, and how values are parsed. See the FieldType Enum section below for available types.

use Tapix\Core\Enums\FieldType;

ImportField::make('email')->type(FieldType::Email);

->icon(?string $icon)

Overrides the default icon for the field. Accepts a Heroicon name.

ImportField::make('website')->icon('heroicon-o-globe-alt');

->sortOrder(?int $sortOrder)

Controls the display ordering of fields in the mapping and review steps.

ImportField::make('email')->sortOrder(1);
ImportField::make('phone')->sortOrder(2);

->nullable(bool $nullable = true)

Adds nullable to the field's validation rules.

ImportField::make('middle_name')->nullable();

->acceptsArbitraryValues(bool $accepts = true)

Indicates that the field accepts free-form values rather than being restricted to a predefined set. Useful for fields like email addresses, phone numbers, or tags.

ImportField::make('tags')->acceptsArbitraryValues();

->options(?array $options)

Defines the available choices for Choice or MultiChoice field types. Each option is an associative array with label and value keys.

ImportField::make('role')->options([
    ['label' => 'Admin', 'value' => 'admin'],
    ['label' => 'Editor', 'value' => 'editor'],
    ['label' => 'Viewer', 'value' => 'viewer'],
]);

->relationship(name, model, matchBy, behavior)

Configures a relationship link for the field. This is covered in detail in the Relationships documentation.

use Tapix\Core\Enums\MatchBehavior;

ImportField::make('company')
    ->relationship(
        name: 'company',
        model: Company::class,
        matchBy: ['name', 'domain'],
        behavior: MatchBehavior::MatchOrCreate,
    );

FieldType Enum

The FieldType enum defines the available data types for import fields. Each type provides default validation rules and a default icon.

Helper Methods

FieldType provides convenience methods for type checking:

• isNumeric() -- returns true for Number and Currency types.
• isDate() -- returns true for Date and DateTime types.
• isChoice() -- returns true for Choice and MultiChoice types.
• isMultiValue() -- returns true for MultiChoice.

Each type also exposes defaultRules() (the Laravel validation rules applied automatically) and defaultIcon() (the Heroicon used in the UI).

ImportFieldCollection

Fields are wrapped in an ImportFieldCollection, a typed collection that provides type-safe access to field definitions.

use Tapix\Core\Fields\ImportFieldCollection;

ImportFieldCollection::make([
    ImportField::make('name')->required(),
    ImportField::make('email')->type(FieldType::Email)->required(),
]);

Auto-Mapping

When a CSV file is uploaded, Tapix attempts to automatically map CSV headers to defined fields. The mapping algorithm normalizes both the CSV header and field keys by converting spaces, dashes, and underscores to a common format, then compares them.

The guess() method extends this behavior by adding additional aliases. For example, a field keyed first_name will auto-map to CSV headers like first_name, first name, or first-name by default. Adding ->guess(['fname', 'given name']) also matches those headers.

Full Example

use Tapix\Core\Enums\FieldType;
use Tapix\Core\Fields\ImportField;
use Tapix\Core\Fields\ImportFieldCollection;

public function fields(): ImportFieldCollection
{
    return ImportFieldCollection::make([
        ImportField::id(),
        ImportField::make('first_name')
            ->label('First Name')
            ->required()
            ->guess(['fname', 'first', 'given name']),
        ImportField::make('last_name')
            ->label('Last Name')
            ->required()
            ->guess(['lname', 'surname', 'family name']),
        ImportField::make('email')
            ->type(FieldType::Email)
            ->required()
            ->guess(['email address', 'e-mail']),
        ImportField::make('phone')
            ->type(FieldType::Phone)
            ->guess(['telephone', 'mobile', 'cell']),
        ImportField::make('birth_date')
            ->type(FieldType::Date)
            ->guess(['birthday', 'date of birth', 'dob']),
        ImportField::make('is_active')
            ->type(FieldType::Boolean)
            ->guess(['active', 'status']),
        ImportField::make('role')
            ->type(FieldType::Choice)
            ->options([
                ['label' => 'Admin', 'value' => 'admin'],
                ['label' => 'Editor', 'value' => 'editor'],
                ['label' => 'Viewer', 'value' => 'viewer'],
            ]),
    ]);
}