Advanced

Models & Database

Tapix database models, their properties, relationships, and table schema.

Tapix uses three Eloquent models to track the state of an import throughout its lifecycle. All database tables are prefixed with the configured table_prefix (default: tapix_).

Import

Tapix\Core\Models\Import

The primary model representing an import session. Tracks the overall status, column mappings, and row counters.

Properties

Column	Type	Description
`id`	ULID	Primary key
`tenant_id`	nullable	Tenant scoping identifier
`user_id`	string	The user who initiated the import
`importer`	string	Fully qualified class name of the importer
`file_name`	string	Original uploaded file name
`status`	ImportStatus	Current import status
`headers`	JSON array	Detected CSV column headers
`column_mappings`	JSON array	User-defined column-to-field mappings
`total_rows`	integer	Total number of rows in the CSV
`created_rows`	integer	Rows that created new records
`updated_rows`	integer	Rows that updated existing records
`skipped_rows`	integer	Rows that were skipped
`failed_rows`	integer	Rows that failed during processing
`completed_at`	timestamp	When the import finished

The status column uses the ImportStatus enum with the following values: Uploading, Mapping, Reviewing, Previewing, Importing, Completed, Failed.

Relationships

user() -- BelongsTo the user who initiated the import.
rows() -- HasMany ImportRow records.
failedRows() -- HasMany FailedImportRow records.

Key Methods

columnMappings(): Collection<ColumnData> -- Returns the column mappings as a hydrated collection of ColumnData objects.
getImporter(): Importer -- Instantiates and returns the importer class.
transitionToImporting(): bool -- Performs an atomic status transition to Importing using a cache lock to prevent race conditions.

Scopes

completed() -- Filters imports with status Completed.
failed() -- Filters imports with status Failed.

ImportRow

Tapix\Core\Models\ImportRow

Represents a single row from the CSV file. Stores the raw data, validation errors, user corrections, and processing state.

Properties

Column	Type	Description
`id`	ULID	Primary key
`import_id`	string	Foreign key to the parent import
`row_number`	integer	Position in the original CSV file
`raw_data`	JSON	Original row data from the CSV
`validation`	JSON	Validation errors per column
`corrections`	JSON	User corrections per column
`skipped`	JSON	Columns marked as skipped
`match_action`	RowMatchAction	Whether to create, update, or skip
`matched_id`	nullable	ID of the existing record (for updates)
`relationships`	JSON	Resolved relationship matches
`processed`	boolean	Whether the row has been processed

Key Methods

getFinalValue(string $column) -- Returns the corrected value if one exists, the raw value otherwise, or null if the column is skipped or has errors.
getFinalData(): array -- Returns merged raw data with corrections applied.
hasErrors(): bool -- Whether the row has any validation errors.
hasCorrections(): bool -- Whether the row has any user corrections.
isCreate(), isUpdate(), isSkip() -- Check the row's match action.

Scopes

withErrors($column) -- Rows with validation errors on a specific column.
valid() -- Rows without validation errors.
toCreate() -- Rows with Create match action.
toUpdate() -- Rows with Update match action.
toSkip() -- Rows with Skip match action.
uniqueValuesFor($column) -- Distinct values for a given column.
searchValue($column, $search) -- Search rows by column value.
forFilter(ReviewFilter, $column) -- Apply a review filter for a specific column.

FailedImportRow

Tapix\Core\Models\FailedImportRow

Records rows that failed during the execution phase. Uses Laravel's MassPrunable trait for automatic cleanup.

Properties

Column	Type	Description
`id`	ULID	Primary key
`import_id`	string	Foreign key to the parent import
`data`	JSON	The row data that failed processing
`validation_error`	string	The error message

The MassPrunable trait defines a prunable query that removes rows older than the cleanup_after_days config value. Run php artisan model:prune to clean them up.

Database Tables

Three tables are created by Tapix migrations:

tapix_imports -- Main import records.
tapix_import_rows -- Individual row state during import.
tapix_failed_import_rows -- Rows that failed processing.

All table names are prefixed with the value of the table_prefix config option (default: tapix_). Each model reads the prefix dynamically via getTable(), so changing the config value is all that is needed to use a custom prefix.

Artisan Commands

CLI commands for scaffolding importers and cleaning up old import data.

Testing

Patterns for testing Tapix importers, models, events, and queue jobs with Pest.