Laravel Google Sheets v1.1.0: Diff Previews, Sync Methods...

Google Sheets is often where business workflows begin.

For Laravel apps, that usually means imports, exports, internal dashboards, user-managed spreadsheets, and the occasional "can we sync this automatically?" request.

olamilekan/laravel-google-sheets v1.1.0 adds several features for those real-world workflows:

Laravel 13 support
Import diff previews
Model, CSV, API, and two-way sync methods
Dry-run sync command
Human-friendly validation error sheets
Retry and exponential backoff for temporary API failures
Better testing fakes
A GitHub Actions test matrix

This is a backward-compatible feature release with 17 commits since v1.0.0.

Install

composer require olamilekan/laravel-google-sheets

Publish the config:

php artisan vendor:publish --tag=google-sheets-config

Laravel 13 support

The package now supports:

Laravel 10
Laravel 11
Laravel 12
Laravel 13

That should make it easier to use the same package across older and newer Laravel applications.

Import diff previews

You can now preview an import before writing anything.

use App\Models\User;
use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$preview = GoogleSheets::connection('users')
    ->diffAgainst(User::query(), key: 'email')
    ->rules([
        'name' => ['required', 'string'],
        'email' => ['required', 'email'],
    ])
    ->preview();

$preview->counts();

The preview separates rows into:

new
changed
deleted
invalid
conflicts

Example:

[
    'new' => 1,
    'changed' => 2,
    'deleted' => 0,
    'invalid' => 1,
    'conflicts' => 0,
]

You can also control which fields are compared:

$preview = GoogleSheets::connection('users')
    ->diffAgainst(User::query(), key: 'email')
    ->only(['name', 'role'])
    ->except(['updated_at'])
    ->preview();

This is useful when building admin import screens or approval flows.

Sync methods

v1.1.0 adds sync helpers for moving data between Google Sheets and common data sources.

Sync from Eloquent to Google Sheets:

use App\Models\User;
use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$report = GoogleSheets::connection('users')
    ->syncFromModel(User::class, keyColumn: 'email', options: [
        'columns' => ['name', 'email', 'role'],
        'conflict' => 'app_wins',
    ]);

Sync from Google Sheets to Eloquent:

$report = GoogleSheets::connection('users')
    ->syncToModel(User::class, keyColumn: 'email');

Import and export CSV files:

$report = GoogleSheets::connection('users')
    ->importCsv(storage_path('app/users.csv'), keyColumn: 'email');

$report = GoogleSheets::connection('users')
    ->exportCsv(storage_path('app/users-export.csv'));

Sync API data into a sheet:

$report = GoogleSheets::connection('orders')
    ->syncFromApi('https://api.example.com/orders', keyColumn: 'order_id', options: [
        'data_key' => 'data',
        'headers' => ['Authorization' => 'Bearer '.$token],
    ]);

Push sheet data to an API:

$report = GoogleSheets::connection('orders')
    ->syncToApi('https://api.example.com/orders/bulk');

Each sync returns a report:

$report->counts();
$report->created();
$report->updated();
$report->conflicts();
$report->errors();

Two-way sync with conflict handling

Two-way sync needs clear conflict behavior.

$report = GoogleSheets::connection('users')
    ->syncTwoWay(User::class, keyColumn: 'email', options: [
        'conflict' => 'fail',
    ]);

Supported strategies:

app_wins
sheet_wins
skip
fail

Dry-run sync command

You can preview command-line imports without writing rows:

php artisan google-sheets:sync "App\\Imports\\UsersImport" users --dry-run

Dry runs compare rows using the import class target and key, then apply validation rules when available.

Validation error sheets

Instead of only throwing validation errors, the package can write row-level issues into an error sheet.

$validRows = GoogleSheets::connection('users')->validateWithErrorSheet([
    'name' => ['required', 'string'],
    'email' => ['required', 'email'],
]);

That gives spreadsheet users a clearer place to fix bad rows.

Queue sync jobs

Longer syncs can be queued:

GoogleSheets::connection('users')
    ->queueSync('syncFromModel', [User::class, 'email'], queue: 'imports');

Audit logs and notifications

Sync activity is logged through Laravel's logger and kept in an in-process audit log:

$records = GoogleSheets::connection('users')->syncAuditLog();

You can also send notifications:

GoogleSheets::connection('users')->syncFromModel(User::class, 'email', [
    'notify' => [
        'slack_webhook' => config('services.slack.sync_webhook'),
        'mail_to' => 'ops@example.com',
    ],
]);

Retry and backoff

Temporary Google Sheets API failures are retried with exponential backoff and jitter.

// config/google-sheets.php
'retry' => [
    'enabled' => true,
    'attempts' => 3,
    'delay' => 250,
    'max_delay' => 5000,
],

Runtime control:

$rows = GoogleSheets::withRetries(attempts: 5, delay: 500)->all();
$rows = GoogleSheets::withoutRetries()->all();

This helps with rate limits, quota throttling, backend errors, and other temporary failures.

Testing fakes

You can test spreadsheet behavior without hitting the real API:

use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$fake = GoogleSheets::fake([
    'users' => [
        ['name' => 'Alice', 'email' => 'alice@example.com'],
    ],
]);

GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Bob', 'email' => 'bob@example.com'],
]);

$fake->assertAppended('users', [
    'name' => 'Bob',
    'email' => 'bob@example.com',
]);

Upgrade

composer update olamilekan/laravel-google-sheets

If you need the new config options:

php artisan vendor:publish --tag=google-sheets-config

Links

GitHub: github.com/oluwatosinolamilekan/laravel-google-sheets

Package:

composer require olamilekan/laravel-google-sheets

Release:

composer update olamilekan/laravel-google-sheets

推荐订阅源

DEV Community