README

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

composer require flatmodel/laravel-csv-flatmodel

Usage

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

php artisan make:csv-model CsvModel

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

php artisan make:csv-model CsvModel --path=csv\data.csv --primary=id

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

use App\Models\CsvModel

$model = (new CsvModel)
        ->where('active', true)
        ->pluck('id');

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):

use FlatModel\CsvModel\Models\Model;
use FlatModel\CsvModel\Traits\Writable;

class EditableModel extends Model
{
    use Writable;

    protected string $path = 'data/users.csv';
    protected bool $writable = true;
}

Backupable

Creates automatic timestamped backups before modifications:

use FlatModel\CsvModel\Models\Model;
use FlatModel\CsvModel\Traits\Writable;
use FlatModel\CsvModel\Traits\Backupable;

class BackedUpModel extends Model
{
    use Writable, Backupable;

    protected string $path = 'data/users.csv';
    protected bool $writable = true;
    protected bool $enableBackup = true;
}

AppendOnly

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

use FlatModel\CsvModel\Models\Model;
use FlatModel\CsvModel\Traits\Writable;
use FlatModel\CsvModel\Traits\AppendOnly;

class LogModel extends Model
{
    use Writable, AppendOnly;

    protected string $path = 'logs/activity.csv';
    protected bool $writable = true;
    protected bool $appendOnly = true;
}

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

HeaderAware

Enables strict header validation and provides header utility methods:

use FlatModel\CsvModel\Models\Model;
use FlatModel\CsvModel\Traits\HeaderAware;

class StrictHeaderModel extends Model
{
    use HeaderAware;

    protected string $path = 'data/users.csv';
    protected bool $hasHeaders = true;  // CSV has header row
    protected array $headers = ['id', 'name', 'email'];  // Expected headers
    protected bool $strictHeaders = true;  // Enforce exact match
}

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:

use FlatModel\CsvModel\Models\Model;

class Product extends Model
{
    protected string $path = 'data/products.csv';
    
    protected array $cast = [
        'id' => 'int',
        'price' => 'float',
        'in_stock' => 'bool',
        'name' => 'string',
    ];
}

// Values are automatically cast when reading
$product = (new Product())->where('id', 1)->first();
// $product['id'] is now an integer, not a string
// $product['price'] is now a float
// $product['in_stock'] is now a boolean

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

class DataModel extends Model
{
    protected string $path = 'data/raw-data.csv';
    protected bool $hasHeaders = false;
    protected array $headers = ['id', 'name', 'value'];  // Custom column names
}

// Access with your custom names
$model = new DataModel();
$model->where('name', 'John')->get();

Option 2: Use numeric indices

class NumericModel extends Model
{
    protected string $path = 'data/raw-data.csv';
    protected bool $hasHeaders = false;
    // No headers defined - will use: ['0', '1', '2', ...]
}

// Access with numeric indices
$model = new NumericModel();
$model->where('0', 'John')->get();  // First column
$model->pluck('2');                 // Third column

Header Row vs No Header Row

# WITH header row ($hasHeaders = true) - DEFAULT
id,name,email
1,John,john@example.com
2,Jane,jane@example.com

# WITHOUT header row ($hasHeaders = false)
1,John,john@example.com
2,Jane,jane@example.com

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.

$model = new CsvModel;

$model->insert(['id' => 5, 'name' => 'Alex']);
$model->flush(); // Writes changes to the file

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

$model = new CsvModel;

// Update a matching row
$model->update(
    fn($row) => $row['id'] === 5,
    fn($row) => [...$row, 'name' => 'Alexa']
);

// Upsert: update if found, insert if not
$model->upsert(
    fn($row) => $row['id'] === 10,
    fn($row) => ['id' => 10, 'name' => 'New User']
);

// Delete matching rows
$model->delete(fn($row) => $row['id'] === 2);

// Save changes to disk
$model->flush();

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

$model->update(['id' => 5], ['name' => 'Alexa']);
$model->upsert(['id' => 10], ['id' => 10, 'name' => 'New User']);
$model->delete(['id' => 2]);

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:

composer test

Or run PHPUnit directly:

vendor/bin/phpunit

License

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