DEV Community

Olamilekan Lamidi
Olamilekan Lamidi

Posted on

Laravel Google Sheets v1.1.0: Diff Previews, Sync Methods, Dry Runs, and Retry Backoff

#laravel #php #opensource #googlesheet

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
Enter fullscreen mode Exit fullscreen mode

Publish the config:

php artisan vendor:publish --tag=google-sheets-config
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

The preview separates rows into:

  • new
  • changed
  • deleted
  • invalid
  • conflicts

Example:

[
    'new' => 1,
    'changed' => 2,
    'deleted' => 0,
    'invalid' => 1,
    'conflicts' => 0,
]
Enter fullscreen mode Exit fullscreen mode

You can also control which fields are compared:

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

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',
    ]);
Enter fullscreen mode Exit fullscreen mode

Sync from Google Sheets to Eloquent:

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

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'));
Enter fullscreen mode Exit fullscreen mode

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],
    ]);
Enter fullscreen mode Exit fullscreen mode

Push sheet data to an API:

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

Each sync returns a report:

$report->counts();
$report->created();
$report->updated();
$report->conflicts();
$report->errors();
Enter fullscreen mode Exit fullscreen mode

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',
    ]);
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'],
]);
Enter fullscreen mode Exit fullscreen mode

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');
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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',
    ],
]);
Enter fullscreen mode Exit fullscreen mode

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,
],
Enter fullscreen mode Exit fullscreen mode

Runtime control:

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

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',
]);
Enter fullscreen mode Exit fullscreen mode

Upgrade 

composer update olamilekan/laravel-google-sheets
Enter fullscreen mode Exit fullscreen mode

If you need the new config options:

php artisan vendor:publish --tag=google-sheets-config
Enter fullscreen mode Exit fullscreen mode

Links

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

Package:

composer require olamilekan/laravel-google-sheets
Enter fullscreen mode Exit fullscreen mode

Release:

composer update olamilekan/laravel-google-sheets
Enter fullscreen mode Exit fullscreen mode

Top comments (0)