byrcsc/laravel-data-sync · 1.x

Quick start.

Import a supplier CSV into an Eloquent model and inspect the recorded run.

This walkthrough imports two products from a CSV file. It assumes Laravel Data Sync is installed and its database tables are migrated.

1. Create the file and definition

Place this file at products/products-2026-07-31.csv on the incoming disk:

SKU,Description,Price,Currency
DS-1001,Anglepoise desk lamp,89.00,PHP
DS-1002,Mechanical keyboard,149.50,PHP

Generate a definition class:

php artisan make:sync ProductsSync

The command writes app/Syncs/ProductsSync.php.

2. Describe the import

Update the generated class:

namespace App\Syncs;

use App\Models\Product;
use ByRcsc\LaravelDataSync\Contracts\Reader as ReaderContract;
use ByRcsc\LaravelDataSync\Definitions\Field;
use ByRcsc\LaravelDataSync\Definitions\Reader;
use ByRcsc\LaravelDataSync\Definitions\Source;
use ByRcsc\LaravelDataSync\Definitions\SyncDefinition;

final class ProductsSync extends SyncDefinition
{
    public function source(): Source
    {
        return Source::disk('incoming')->path('products');
    }

    public function format(): ReaderContract
    {
        return Reader::csv();
    }

    public function model(): string
    {
        return Product::class;
    }

    public function fields(): array
    {
        return [
            Field::make('sku', from: 'SKU'),
            Field::make('name', from: 'Description'),
            Field::make('price_cents', from: 'Price')
                ->transform(
                    fn (string $value): int =>
                        (int) round((float) $value * 100),
                ),
            Field::make('currency')->default('PHP'),
        ];
    }

    public function matchOn(): array
    {
        return ['sku'];
    }

    public function rules(): array
    {
        return [
            'sku' => ['required', 'string', 'max:32'],
            'price_cents' => ['required', 'integer', 'min:0'],
        ];
    }
}

The definition reads CSV files from the products directory. It maps source columns to model attributes and uses sku to find an existing product.

Add a unique database index for products.sku. The health check warns when a matching column has no unique index.

3. Register and run the sync

'syncs' => [
    App\Syncs\ProductsSync::class,
],

Run the first import in the current process:

php artisan sync:run products --now

Running [products]...
  File run [01JQ8Z3M0K2N4P6R8T0V2X4Y6A] (bulk) ... 2 created, 0 updated, 0 skipped, 0 failed
[products] finished: 1 discovered, 0 skipped, 0 deferred.

ProductsSync becomes the command name products. Override name() when you need another name.

Run the command again without changing the file. The checksum is already in the ledger, so the command skips it instead of importing the rows twice.

4. Inspect the recorded run

php artisan sync:status products --limit=25

The output shows the run identifier, status, write path, and row counters:

  Run                          Sync      Status · path        C/U/S/F   Progress
  01JQ8Z3M0K2N4P6R8T0V2X4Y6A   products  completed · bulk     2/0/0/0   2 rows

Use the run identifier when you need to inspect failures or retry an attempt.

Quick start.

Import a supplier CSV into an Eloquent model and inspect the recorded run.

This walkthrough imports two products from a CSV file. It assumes Laravel Data Sync is installed and its database tables are migrated.

1. Create the file and definition

Place this file at products/products-2026-07-31.csv on the incoming disk:

SKU,Description,Price,Currency
DS-1001,Anglepoise desk lamp,89.00,PHP
DS-1002,Mechanical keyboard,149.50,PHP

Generate a definition class:

php artisan make:sync ProductsSync

The command writes app/Syncs/ProductsSync.php.

2. Describe the import

Update the generated class:

namespace App\Syncs;

use App\Models\Product;
use ByRcsc\LaravelDataSync\Contracts\Reader as ReaderContract;
use ByRcsc\LaravelDataSync\Definitions\Field;
use ByRcsc\LaravelDataSync\Definitions\Reader;
use ByRcsc\LaravelDataSync\Definitions\Source;
use ByRcsc\LaravelDataSync\Definitions\SyncDefinition;

final class ProductsSync extends SyncDefinition
{
    public function source(): Source
    {
        return Source::disk('incoming')->path('products');
    }

    public function format(): ReaderContract
    {
        return Reader::csv();
    }

    public function model(): string
    {
        return Product::class;
    }

    public function fields(): array
    {
        return [
            Field::make('sku', from: 'SKU'),
            Field::make('name', from: 'Description'),
            Field::make('price_cents', from: 'Price')
                ->transform(
                    fn (string $value): int =>
                        (int) round((float) $value * 100),
                ),
            Field::make('currency')->default('PHP'),
        ];
    }

    public function matchOn(): array
    {
        return ['sku'];
    }

    public function rules(): array
    {
        return [
            'sku' => ['required', 'string', 'max:32'],
            'price_cents' => ['required', 'integer', 'min:0'],
        ];
    }
}

The definition reads CSV files from the products directory. It maps source columns to model attributes and uses sku to find an existing product.

Add a unique database index for products.sku. The health check warns when a matching column has no unique index.

3. Register and run the sync

'syncs' => [
    App\Syncs\ProductsSync::class,
],

Run the first import in the current process:

php artisan sync:run products --now

Running [products]...
  File run [01JQ8Z3M0K2N4P6R8T0V2X4Y6A] (bulk) ... 2 created, 0 updated, 0 skipped, 0 failed
[products] finished: 1 discovered, 0 skipped, 0 deferred.

ProductsSync becomes the command name products. Override name() when you need another name.

Run the command again without changing the file. The checksum is already in the ledger, so the command skips it instead of importing the rows twice.

4. Inspect the recorded run

php artisan sync:status products --limit=25

The output shows the run identifier, status, write path, and row counters:

  Run                          Sync      Status · path        C/U/S/F   Progress
  01JQ8Z3M0K2N4P6R8T0V2X4Y6A   products  completed · bulk     2/0/0/0   2 rows

Use the run identifier when you need to inspect failures or retry an attempt.

Quick start.

1. Create the file and definition

2. Describe the import

3. Register and run the sync

4. Inspect the recorded run

What to read next

Quick start.

1. Create the file and definition

2. Describe the import

3. Register and run the sync

4. Inspect the recorded run

What to read next