README

A fluent Laravel package for reading, writing, and managing Google Sheets with first-class support for multiple spreadsheet connections.

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13
• A Google Cloud project with the Sheets API enabled
• A service account JSON credentials file

Installation

composer require olamilekan/laravel-google-sheets

Publish the configuration file:

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

Configuration

1. Credentials

Place your service account JSON file somewhere secure (e.g. storage/app/google/service-account.json) and set the path in your .env:

GOOGLE_SHEETS_CREDENTIALS_PATH=/path/to/service-account.json

2. Spreadsheet Connections

Define as many named connections as you need in config/google-sheets.php:

'sheets' => [

    'default' => [
        'spreadsheet_id' => env('GOOGLE_SHEETS_SPREADSHEET_ID'),
        'sheet' => 'Sheet1',
    ],

    'users' => [
        'spreadsheet_id' => env('GOOGLE_SHEETS_USERS_SPREADSHEET_ID'),
        'sheet' => 'Users',
    ],

    'reports' => [
        'spreadsheet_id' => env('GOOGLE_SHEETS_REPORTS_SPREADSHEET_ID'),
        'sheet' => 'Monthly',
    ],

],

Set the default connection:

GOOGLE_SHEETS_DEFAULT_CONNECTION=default
GOOGLE_SHEETS_SPREADSHEET_ID=your-spreadsheet-id-here

Usage

Using the Facade

use Olamilekan\GoogleSheets\Facades\GoogleSheets;

Reading Data

// All rows from the default connection (first row treated as headers)
$rows = GoogleSheets::all();

// Specific range
$rows = GoogleSheets::range('A1:D10')->get();

// First row only
$row = GoogleSheets::first();

// Get column headers
$headers = GoogleSheets::headers();

// Without header mapping (raw arrays)
$rows = GoogleSheets::connection('users')->withoutHeaders()->get();

Querying Data

// Find rows where a column matches a value
$admins = GoogleSheets::find('role', 'admin');

// Where clause with operators
$highScores = GoogleSheets::where('score', '>=', 90);

// Partial text matching
$results = GoogleSheets::where('name', 'like', 'john');

Writing Data

// Append rows
GoogleSheets::append([
    ['Alice', 'alice@example.com', 'admin'],
    ['Bob', 'bob@example.com', 'user'],
]);

// Update a specific range
GoogleSheets::range('A2:C2')->update([
    ['Alice Updated', 'alice-new@example.com', 'superadmin'],
]);

// Batch update multiple ranges at once
GoogleSheets::batchUpdate([
    'A2:C2' => [['Alice', 'alice@example.com', 'admin']],
    'A3:C3' => [['Bob', 'bob@example.com', 'user']],
]);

// Clear a range
GoogleSheets::range('A2:C100')->clear();

Associative Rows, Upserts, And Validation

// Map associative arrays to the sheet's header row before appending
GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Alice', 'email' => 'alice@example.com', 'role' => 'admin'],
]);

// Update existing rows by key column and append missing rows
GoogleSheets::connection('users')->upsert('email', [
    ['name' => 'Alice Updated', 'email' => 'alice@example.com', 'role' => 'owner'],
    ['name' => 'Charlie', 'email' => 'charlie@example.com', 'role' => 'user'],
]);

// Validate imported rows with Laravel validation rules
$validRows = GoogleSheets::connection('users')->validate([
    'name' => ['required', 'string'],
    'email' => ['required', 'email'],
]);

// Write row-level validation errors to an "Import Errors" tab before failing
$validRows = GoogleSheets::connection('users')->validateWithErrorSheet([
    'name' => ['required', 'string'],
    'email' => ['required', 'email'],
]);

// Ensure required sheet headers exist
GoogleSheets::connection('users')->requireHeaders(['name', 'email', 'role']);

Import Diff Preview

Preview the impact of an import before writing anything. The preview separates new, changed, deleted, invalid, and conflict rows.

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();
// ['new' => 1, 'changed' => 2, 'deleted' => 0, 'invalid' => 1, 'conflicts' => 0]

$preview->new;       // rows in the sheet that are not in the query
$preview->changed;   // rows where sheet values differ from existing query values
$preview->deleted;   // query rows missing from the sheet
$preview->invalid;   // rows failing validation or missing the key
$preview->conflicts; // duplicate key rows in the sheet or query

By default, changed rows compare sheet columns that also exist on the query/model row, excluding the key. You may narrow the comparison:

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

Sync Methods

Sync methods return a SyncReport with created, updated, deleted, skipped, conflict, and failed counts.

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

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

// Google Sheet -> Database / Eloquent
$report = GoogleSheets::connection('users')
    ->syncToModel(User::class, keyColumn: 'email');

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

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

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

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

// Conflict-aware two-way sync
$report = GoogleSheets::connection('users')
    ->syncTwoWay(User::class, keyColumn: 'email', options: [
        'conflict' => 'fail', // app_wins, sheet_wins, skip, fail
    ]);

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

Run syncs in the queue:

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

Every sync is audit logged through Laravel's logger and kept in the in-process audit log:

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

Notify teams when a sync finishes or fails:

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

Import And Export Classes

use App\Models\User;
use Olamilekan\GoogleSheets\Imports\SheetImport;

class UsersImport extends SheetImport
{
    public function target()
    {
        return User::query();
    }

    public function key(): string
    {
        return 'email';
    }
    public ?string $errorSheet = 'Import Errors';

    public function rules(): array
    {
        return ['email' => ['required', 'email']];
    }

    public function model(array $row): User
    {
        return User::updateOrCreate(
            ['email' => $row['email']],
            ['name' => $row['name']]
        );
    }
}

GoogleSheets::import(new UsersImport(), 'users');

Preview an import from the command line without writing rows:

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

Dry-run imports compare the sheet rows against the import class target() using the column returned by key(). Validation rules are applied when the import defines rules().

use App\Models\Report;
use Olamilekan\GoogleSheets\Exports\SheetExport;

class ReportsExport extends SheetExport
{
    public bool $replace = true;

    public function headings(): array
    {
        return ['Date', 'Name', 'Total'];
    }

    public function collection()
    {
        return Report::query()
            ->latest()
            ->get()
            ->map(fn (Report $report) => [
                $report->created_at->toDateString(),
                $report->name,
                $report->total,
            ]);
    }
}

GoogleSheets::export(new ReportsExport(), 'reports');

Multiple Connections

// Switch between configured connections
$users  = GoogleSheets::connection('users')->all();
$reports = GoogleSheets::connection('reports')->all();

// Create an ad-hoc connection to any spreadsheet
$data = GoogleSheets::make('some-spreadsheet-id', 'TabName')->all();

Switching Sheets (Tabs) at Runtime

$sheet = GoogleSheets::connection('default');

$sheet1Data = $sheet->sheet('Sheet1')->all();
$sheet2Data = $sheet->sheet('Sheet2')->all();

Sheet / Tab Management

// List all sheet tabs in a spreadsheet
$tabs = GoogleSheets::listSheets();   // ['Sheet1', 'Users', 'Reports']

// Check if a tab exists
GoogleSheets::sheetExists('Users');   // true

// Create a new tab
GoogleSheets::createSheet('Archive');

// Duplicate an existing tab
GoogleSheets::duplicateSheet('Sheet1', 'Sheet1 Copy');

// Delete a tab
GoogleSheets::deleteSheet('Archive');

Caching

Enable caching in config or at runtime to reduce API calls:

// In config/google-sheets.php
'cache' => [
    'enabled' => true,
    'store'   => 'redis',
    'ttl'     => 300,  // seconds
    'prefix'  => 'google_sheets_',
],

// At runtime
$rows = GoogleSheets::enableCache(600)->all();
$rows = GoogleSheets::disableCache()->all();

Write operations now clear remembered read cache keys for the active spreadsheet, so cached ranges are refreshed after updates.

Retry And Backoff

Transient Google Sheets API failures are retried by default, including rate limits, quota throttling, and backend errors. The delay uses exponential backoff with jitter.

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

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

Chunked Processing

GoogleSheets::chunk(100, function ($chunk) {
    foreach ($chunk as $row) {
        // process each row
    }
});

GoogleSheets::lazy(500)->each(function (array $row) {
    // process one row at a time
});

Formatting, Formulas, And Named Ranges

GoogleSheets::connection('reports')
    ->sheet('Monthly')
    ->boldHeader()
    ->freezeRows(1)
    ->autoResizeColumns(1, 4);

GoogleSheets::connection('reports')->append([
    ['Total', GoogleSheets::formula('SUM(C2:C100)')],
]);

$summaryRows = GoogleSheets::connection('reports')
    ->namedRange('MonthlySummary')
    ->get();

Testing

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']);

Artisan Commands

php artisan google-sheets:list users
php artisan google-sheets:clear reports --sheet=Monthly --range=A2:D100
php artisan google-sheets:sync "App\\Imports\\UsersImport" users
php artisan google-sheets:sync "App\\Imports\\UsersImport" users --dry-run
php artisan google-sheets:sync "App\\Exports\\ReportsExport" reports

Spreadsheet Metadata

$title = GoogleSheets::getTitle();
$id    = GoogleSheets::getSpreadsheetId();

Dependency Injection

use Olamilekan\GoogleSheets\GoogleSheetsManager;

class UserImportService
{
    public function __construct(
        protected GoogleSheetsManager $sheets
    ) {}

    public function import(): void
    {
        $rows = $this->sheets->connection('users')->all();

        foreach ($rows as $row) {
            User::updateOrCreate(
                ['email' => $row['email']],
                ['name' => $row['name']]
            );
        }
    }
}

API Reference

GoogleSheetsManager

Sheet

Environment Variables

License

MIT