Download the PHP package gulaandrij/google-sheets-bundle without Composer

GoogleSheetsBundle

A Symfony bundle wrapping revolution/laravel-google-sheets with a focused, Symfony-native service that handles credentials, scopes, and common Sheets operations.

The bundle exists because v7 of revolution/laravel-google-sheets turned the convenient Sheets class into a Laravel facade that requires the Laravel container to resolve. This bundle pins the underlying SheetsClient into the Symfony DI graph and adds a higher-level SheetsService on top so application code does not need to chain the fluent API or worry about thread-local state.

Documentation

• Authentication — picking and configuring API key, OAuth, or service account credentials.
• Recipes — common patterns: imports, exports, scheduled jobs, bulk updates, formulas.
• Architecture — service graph, why per-call SheetsClient instances, design decisions.
• Troubleshooting — common errors and what to do about them.
• Upgrade guide — moving between bundle versions.
• Changelog — version history.
• Contributing — local workflow and quality gates.

Requirements

• PHP 8.3+ (PHP 8.4+ required for Symfony 8)
• Symfony 6.4, 7.x, or 8.x
• google/apiclient 2.16+
• revolution/laravel-google-sheets 7.2+

Installation

If your project does not use Symfony Flex, register the bundle manually in config/bundles.php:

Configuration

The bundle follows the same shape as league/flysystem-bundle: declare one or more named spreadsheets, and the bundle wires a dedicated SheetsService instance per name that you can autowire by variable name.

Create config/packages/google_sheets.yaml:

Each entry under spreadsheets becomes:

• A service at google_sheets.sheets_service.<name> (public).
• An autowire-by-name binding SheetsService $<camelCaseName> so __construct(SheetsService $allocators) resolves automatically.
• For the default_spreadsheet entry, the bare SheetsService alias and SheetsService::class autowire target.

spreadsheets is optional — if you only need the lower-level SheetsClient / SheetsClientFactory services, omit it entirely. If you declare exactly one spreadsheet, it becomes the default automatically; with more than one you must set default_spreadsheet explicitly (the bundle fails at boot otherwise).

Spreadsheet names must contain only letters, digits, underscores, dashes, or dots, and must start with a letter or underscore so they can be camelCased into a PHP variable name. Invalid names fail at config-tree validation.

The sheet key is optional. When set, SheetsService::readRaw(), readAssoc(), firstRow(), append(), update(), clear(), and sheetProperties() may be called without a $sheetName argument and operate on the bound tab. Passing an explicit $sheetName overrides the bound default — useful when a single spreadsheet has many tabs and you want one service to cover them all.

If no scopes are set the bundle defaults to read-only access:

Choosing an auth method

The bundle will refuse to build the Google\Client if none of the three are configured, throwing Gulaandrij\GoogleSheetsBundle\Exception\MissingCredentialsException.

Usage

Each named spreadsheet has its own SheetsService instance bound to that spreadsheet ID. Type-hint SheetsService and name the constructor parameter after the spreadsheet:

Variable names with underscores or dashes in the config key become camelCase bindings: billing_data → $billingData, my-reports → $myReports.

If you need a dynamic spreadsheet ID (only known at runtime), inject SheetsClientFactory instead and drive the client directly — see Architecture.

API

SheetsService wraps every public method on the underlying Revolution\Google\Sheets\SheetsClient, grouped by intent. Every method runs against a fresh SheetsClient from the factory so selector state never leaks between calls.

Reading

$sheetName defaults to the configured sheet for the binding; pass an explicit value to target a different tab. The optional read modifiers map onto the Sheets API's majorDimension / valueRenderOption / dateTimeRenderOption query parameters. Class constants are provided for convenience: SheetsService::MAJOR_DIMENSION_ROWS|COLUMNS, VALUE_RENDER_FORMATTED|UNFORMATTED|FORMULA, DATE_TIME_RENDER_SERIAL|FORMATTED. firstRow() deliberately does not expose majorDimension — under COLUMNS it would return the first column.

Writing

Use the SheetsService::VALUE_INPUT_RAW / VALUE_INPUT_USER_ENTERED and INSERT_DATA_OVERWRITE / INSERT_DATA_INSERT_ROWS constants for the option arguments.

append() enforces row-shape consistency upfront: all rows must be positional, or all rows must be associative with the same key set — mixed shapes or divergent assoc keys throw MixedRowShapeException instead of letting the underlying client silently drop values.

Tab management

Both require the https://www.googleapis.com/auth/spreadsheets scope.

Discovery

listSpreadsheets lives on SheetsClientFactory because it's a global Drive query (fileId => title) and is independent of any spreadsheet binding. Requires a Drive read scope.

Metadata

Returned objects mirror the Sheets API's SpreadsheetProperties / SheetProperties resources (title, locale, timeZone, gridProperties, etc.).

Escape hatches

client() returns a brand-new SheetsClient per call; driveService() returns the shared Google\Service\Drive instance for Drive-level operations not covered by this service.

• readRaw returns each row as a positional array (list<list<mixed>>).
• readAssoc treats the first row as the header and yields associative rows. Short rows are padded with empty strings; overflow cells beyond the header are discarded. Duplicate header values throw DuplicateHeaderException; non-scalar header cells throw InvalidHeaderException — fall back to readRaw for non-conforming sheets.
• listSheets returns just the tab titles in a list; listSheetsWithIds returns the sheetId => title map for callers that need the stable IDs (e.g. for sheetById() lookups).
• append accepts either positional rows (list<list<mixed>>) or associative rows (list<array<string,mixed>>); rows must be uniform — mixing shapes throws MixedRowShapeException to prevent the underlying client from silently dropping data.
• update and clear target a specific A1-notation range; pass null to clear to wipe the whole sheet.
• client() returns a fresh Revolution\Google\Sheets\SheetsClient for advanced operations not covered above (batch operations, properties, drive metadata, etc.). Because every call constructs a new instance, mutating selectors like valueRenderOption() on the returned client never leaks into other callers.

State isolation

The underlying Revolution\Google\Sheets\SheetsClient keeps range, majorDimension, valueRenderOption, and dateTimeRenderOption as instance fields — and neither spreadsheet() nor sheet() reset them. To prevent cross-call leakage, this bundle wires the SheetsClient service as non-shared: each SheetsService method (and each client() call) gets a brand-new instance via SheetsClientFactory::create(). If you autowire SheetsClient directly into your own services, every constructor injection still gets its own instance; if you fetch it from the container at runtime, each get() returns a new one.

Direct access to lower-level services

Each layer is registered both under a typed alias and an explicit service ID:

All five are autowireable by class name. SheetsService is additionally autowireable by variable name as described above.

Console commands

The bundle ships four introspection commands that use the configured bindings:

doctor returns a non-zero exit code if any binding fails — wire it into your deploy pipeline to catch misconfiguration before the first runtime call.

Typed reads with DTOs

For DTOs whose property names don't match sheet headers, place #[SheetColumn] attributes and call readEntities instead of readAssoc:

Requires framework.serializer to be enabled (Symfony auto-installs it; nothing else to configure). The bundle wires the denormalizer automatically when available; without it readEntities() throws a clear LogicException.

Streaming large sheets

readAssoc() loads the whole sheet into memory — fine for thousands of rows, harsh for hundreds of thousands. readAssocIterable() yields rows one at a time, fetching them from the API in batches:

Opt-in read caching

Slowly-changing reference data (e.g. keyword tables, dictionaries) can be cached transparently. Add a cache block to the binding:

Reads (readAssoc, readRaw, firstRow, listSheets*, *Properties) are now memoised. Writes pass through unchanged. Caching is skipped when kernel.debug is true — the profiler shows real Sheets calls in dev.

Testing your code

Drop Gulaandrij\GoogleSheetsBundle\Test\InMemorySheetsService into the container in test setup to skip Google entirely:

The fake supports the full read/write surface (readRaw, readAssoc, append, update, clear, addSheet, deleteSheet, listSheets*, findSheetNameById, etc.) so most tests don't need any extra mocking.

Web Profiler

When kernel.debug is true (typically the dev environment), the bundle automatically wraps every named SheetsService with a tracing decorator and registers a Symfony Web Profiler data collector. A "Google Sheets" toolbar item shows the total call count and total time spent in Sheets calls; clicking it opens a panel listing each call (service binding, method, spreadsheet ID, sheet, range, duration, status).

There is nothing to configure — install the bundle, enable the profiler in your dev config, and the panel appears. In production (kernel.debug = false) the decorator and collector are skipped so there is zero overhead.

Testing

The package ships with PHPUnit, PHPStan (level 8), and PHP-CS-Fixer configured. Run:

License

MIT.