Building A Production-Ready Laravel Google Sheets Package From Import To Test Suite

Question

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' => '*Emails are not allowed*',
    ],
]);

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' => '*Emails are not allowed*'],
    ],
]);

GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Bob', 'email' => '*Emails are not allowed*'],
]);

$fake->assertAppended('users', [
    'name' => 'Bob',
    'email' => '*Emails are not allowed*',
]);

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

---