Download the PHP package flatmodel/laravel-csv-flatmodel without Composer

FlatModel CSV is an Eloquent-inspired data modeling system for Laravel that works with CSV files.

It provides an expressive, familiar API for reading and writing flat data sources without relying on a database.

Installation

Install with Composer into a new or existing Laravel project

Usage

A new CSV model can be made by running the artisan command which will prompt for a few details.

If instead you want to skip the prompts, the arguments can be provided instead;

Providing a primary key is optional and can be skipped with the --noprimary flag or by leaving the prompt empty when prompted for a primary key.

Once the model is generated, it can be used similarly to standard models within Laravel

The methods are returned as instances of the Illuminate\Support\Collection class that those familiar with Laravel will be comfortable with. This also means that working with the data returned is simple and straightforward.

Opt-in Features

FlatModel uses traits to provide optional functionality. Include these traits in your model as needed:

Writable

Enables write operations (insert, update, delete, upsert):

Backupable

Creates automatic timestamped backups before modifications:

AppendOnly

Restricts models to insert-only operations (no updates or deletes):

Note: AppendOnly requires the Writable trait since it restricts write operations.

HeaderAware

Enables strict header validation and provides header utility methods:

Strict mode behavior:

• Throws HeaderMismatchException if CSV headers don't exactly match $headers
• Useful for validating CSV file structure
• Requires both $headers to be defined and $strictHeaders = true

Without HeaderAware:

• Headers are still loaded/generated but not validated
• More flexible for varying CSV structures

Type Casting

CSV files store all data as strings. Use the $cast property to automatically convert values to specific types:

Supported cast types:

• int or integer - Cast to integer
• float or double - Cast to floating point number
• bool or boolean - Cast to boolean (handles "true", "false", "1", "0", etc.)
• string - Cast to string

Type casting is applied automatically when:

• Reading data with get(), first(), pluck(), etc.
• Writing data with insert(), update(), upsert()

Working with Headerless CSV Files

If your CSV file doesn't have a header row, set $hasHeaders = false:

Option 1: Provide custom column names

Option 2: Use numeric indices

Header Row vs No Header Row

Query Methods

For interacting and querying data from the model, the following are available:

• where(string $column, mixed $value) - Filter rows by column value
• first() - Get the first matching row as an array, or null if no match
• get() - Get all matching rows as a Collection
• pluck(string $column) - Get a Collection of values from a specific column
• select(string ...$columns) - Select specific columns to return
• value(string $column) - Get the first value from a column, or null if not found

The model has a series of configurable properties that will enable or disable functionality.

[!IMPORTANT] If $autoFlush is set to false (as it is by default), flush() should be manually called to persist the data to the file.

Writing, Mutating & Flushing Data

Writable models can be modified and saved back to the file using flush() or save() if $autoFlush is disabled by using false.

Updates and deletes are also possible using similarly named methods using functional filtering.

Models can also be updated using more familiar array-based syntax.

[!WARNING] Models in stream mode cannot be written back to the file and are read-only. If an attempt is made to write to a model implementing stream mode, a StreamWriteException will be thrown.

[!WARNING] If the model is in append-only mode, updates, upserts and deletes will throw an AppendOnlyViolationException exception.

Exception Handling

FlatModel uses custom exceptions to provide clear and understandable error context all extending a common base of FlatModelException.

Testing

Run tests using Composer:

Or run PHPUnit directly:

License

FlatModel is open-sourced software licensed under the MIT license.