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

	Feature	Description
Read	get() getSingleCellValue() findCellByValue()	Fetch ranges, single cells, or search by value
Write	appendSingleRow() append() updateSingleCell() update()	Append rows, update cells or entire ranges
Sheets	addWorksheet() duplicateWorksheet() renameWorksheet() deleteWorksheet()	Full worksheet lifecycle management
Style	colorRange() clearRange()	Color cells and clear data
Manage	create() getSpreadsheetWorksheets()	Create spreadsheets and list worksheets

---

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.

See it in action

---

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.