Custom Fields

Tapix supports importing data into custom (user-defined) fields through a pluggable adapter system. This is useful for applications like CRMs where end users can create their own fields beyond the standard model attributes.

The CustomFieldsAdapter Contract

To integrate custom fields, implement the CustomFieldsAdapter interface:

interface CustomFieldsAdapter
{
    public function getFields(string $modelClass): ImportFieldCollection;

    public function saveValues(Model $record, array $values, int|string|null $tenantId = null): void;

    public function getRelationshipFields(string $modelClass): ImportFieldCollection;
}

Methods

• getFields() -- Returns an ImportFieldCollection of additional field definitions for the given model class. These fields are merged with the importer's standard fields during the mapping step.
• saveValues() -- Persists custom field values to the database after the primary record has been saved. Receives the saved model instance, an associative array of custom field values, and the optional tenant ID.
• getRelationshipFields() -- Returns relationship fields defined in the custom fields system. These are automatically converted to entity links, enabling relationship linking during import.

Registration

Set the custom_fields_adapter option in the Tapix config to your adapter class:

'custom_fields_adapter' => \App\Imports\MyCustomFieldsAdapter::class,

When no adapter is configured, custom field functionality is disabled and only the importer's standard fields are used.

How It Works

Field Merging

The BaseImporter::allFields() method merges standard importer fields with any fields returned by the adapter's getFields() method. This means custom fields appear alongside standard fields in the column mapping step without any changes to your importer class.

Internal Key Prefixing

Custom field keys are prefixed with custom_fields_ internally to distinguish them from standard model attributes. This prevents naming collisions between custom fields and built-in columns.

Batch Processing

During ExecuteImportJob, custom field data is collected for each chunk of rows and flushed to the adapter in batch via saveValues(). This approach reduces the number of database operations compared to saving custom field values row by row.

Relationship Fields

Relationship fields returned by getRelationshipFields() are automatically converted to entity links. This allows custom relationship fields to participate in the same relationship linking workflow as standard entity link fields, including match resolution and record creation.

Use Case

A typical use case is a CRM application where administrators define custom fields per entity type (contacts, companies, deals). The adapter reads the field definitions from a custom_fields table and maps them to ImportField instances. During import execution, standard attributes are saved to the model directly, while custom field values are routed through the adapter's saveValues() method to a separate storage table.