README

PHP Google Sheets Helper

A powerful, elegant wrapper around Google Sheets API for PHP

Installation • Quick Start • API Reference • Tips • License

Stop wrestling with the verbose Google Sheets API. This library wraps the official Google APIs Client Library for PHP into a clean, fluent interface so you can read, write, and manage spreadsheets in just a few lines of code.

Features

Requirements

• PHP >= 5.4 with CLI and JSON extension
• A Google Cloud Platform project with the Sheets API enabled
• Credentials (credentials.json) from the Google Cloud Console

Installation

composer require reandimo/google-sheets-helper

Credentials Setup

The library authenticates using two files: credentials.json (from Google Cloud Console) and token.json (generated on first auth).

Generate token.json by running from your project root:

php ./vendor/reandimo/google-sheets-helper/firstauth

Follow the interactive steps — this only needs to be done once.

Quick Start

use reandimo\GoogleSheetsApi\Helper;

// Set credentials via environment (recommended)
putenv('credentialFilePath=path/to/credentials.json');
putenv('tokenPath=path/to/token.json');

// Create instance and configure
$sheet = new Helper();
$sheet->setSpreadsheetId('your-spreadsheet-id');
$sheet->setWorksheetName('Sheet1');

// Read data
$sheet->setSpreadsheetRange('A1:D10');
$data = $sheet->get();

// Write data
$sheet->appendSingleRow(['Name', 'Email', 'Role']);

// Update a cell
$sheet->updateSingleCell('B2', 'john@example.com');

You can also pass credential paths directly to the constructor:

$sheet = new Helper('path/to/credentials.json', 'path/to/token.json');

API Reference

Reading Data

get() — Get values from a range

$sheet->setSpreadsheetRange('A1:C10');
$data = $sheet->get();

getSingleCellValue(string $cell) — Get a single cell value

$value = $sheet->getSingleCellValue('B2');
echo "Value: $value\n";

findCellByValue(string $searchValue) — Search for a value

$sheet->setSpreadsheetRange('A1:Z100');
$result = $sheet->findCellByValue('searchValue');

if ($result) {
    echo "Found at {$result['cell']} (row {$result['row']}, col {$result['column']})\n";
}

Writing Data

appendSingleRow(array $row) — Append one row

$sheet->setSpreadsheetRange('A1:C1');
$inserted = $sheet->appendSingleRow(['John', 'john@doe.com', 'Admin']);

if ($inserted >= 1) {
    echo 'Row inserted.';
}

append(array $rows) — Append multiple rows

$sheet->setSpreadsheetRange('A1:C1');
$sheet->append([
    ['Alice', 'alice@example.com', 'Editor'],
    ['Bob',   'bob@example.com',   'Viewer'],
    ['Carol', 'carol@example.com', 'Admin'],
]);

updateSingleCell(string $cell, mixed $value) — Update one cell

$update = $sheet->updateSingleCell('B5', 'Updated value');

if ($update->getUpdatedCells() >= 1) {
    echo 'Cell updated.';
}

update(array $values) — Update a range

$sheet->setSpreadsheetRange('A1:C3');
$update = $sheet->update([
    ['val1', 'val2', 'val3'],
    ['val4', 'val5', 'val6'],
    ['val7', 'val8', 'val9'],
]);

if ($update->getUpdatedCells() >= 1) {
    echo 'Range updated.';
}

Worksheet Management

getSpreadsheetWorksheets() — List all worksheets

$worksheets = $sheet->getSpreadsheetWorksheets();

foreach ($worksheets as $ws) {
    echo "ID: {$ws['id']}, Title: {$ws['title']}\n";
}

addWorksheet(string $title, int $rows, int $cols) — Create a new worksheet

$newSheetId = $sheet->addWorksheet('NewSheet', 100, 10);
echo "Created worksheet ID: $newSheetId\n";

duplicateWorksheet(string $newName) — Duplicate a worksheet

$sheet->setWorksheetName('Sheet1');
$sheetId = $sheet->duplicateWorksheet('Sheet1 - Copy');

if ($sheetId) {
    echo 'Worksheet duplicated.';
}

renameWorksheet(string $oldName, string $newName) — Rename a worksheet

$sheet->renameWorksheet('OldName', 'NewName');

deleteWorksheet(string $name) — Delete a worksheet

$deleted = $sheet->deleteWorksheet('SheetToDelete');

if ($deleted) {
    echo 'Worksheet deleted.';
}

Styling & Utilities

colorRange(array $rgb) — Set background color

$sheet->setSpreadsheetRange('A1:Z10');
$sheet->colorRange([142, 68, 173]); // Purple background

clearRange() — Clear all values in a range

$sheet->setSpreadsheetRange('A1:Z100');
$sheet->clearRange();

create(string $title) — Create a new spreadsheet

$newId = $sheet->create('My New Spreadsheet');
echo "Spreadsheet ID: $newId\n";

Helper::getColumnLettersIndex(string $letters) — Column letter to index

Helper::getColumnLettersIndex('AZ'); // Returns 52

Tips

Blank cells on insert/update: Use the constant Google_Model::NULL_VALUE to represent an empty cell.

$sheet->appendSingleRow([
    'John Doe',
    'john@doe.com',
    Google_Model::NULL_VALUE, // skip this cell
    'Sagittarius',
]);

Multiple sheet instances: Create as many Helper instances as you need to work with different spreadsheets or worksheets simultaneously.

$orders = new Helper();
$orders->setSpreadsheetId('spreadsheet-a');
$orders->setWorksheetName('Orders');

$inventory = new Helper();
$inventory->setSpreadsheetId('spreadsheet-b');
$inventory->setWorksheetName('Stock');

License

MIT License. See LICENSE for details.

Questions & Issues

Found a bug or have a suggestion? Open an issue.

Author

Renan Diaz — Working with PHP since 2017 & Google's API since 2019.