> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets API for Laravel

> Laravel wrapper for Google Sheets API v4. Fluent and intuitive interface.

A Laravel package providing a fluent, Laravel-idiomatic interface for Google Sheets API v4. It abstracts away the complexity of the underlying Google PHP client library, letting developers read, write, update, and manage spreadsheets with expressive, chainable methods.

## Features

* **Multiple Authentication Methods** — OAuth 2.0 (user-specific), Service Account (server-to-server), and API key (public data)
* **Fluent API** — Chainable methods for intuitive data operations with natural Laravel syntax
* **Laravel Collection Integration** — Google Sheets data seamlessly converts to Laravel Collections for easy manipulation
* **Extensibility** — Macro system allows adding custom methods to the facade
* **Google Drive Integration** — Built-in support for spreadsheet management and listing

## Common Use Cases

* **User Dashboards** — Display and interact with Google Sheets data in your application
* **Data Import/Export** — Bulk operations between your Laravel app and Google Sheets
* **Automated Reporting** — Generate and update reports programmatically
* **Multi-user Applications** — Users manage their own Google Sheets with proper authentication

## Design Philosophy

This package focuses on **reading from Google Sheets**. Rather than specifying detailed conditions before reading, the design assumes you first retrieve all data as a Laravel Collection, then process it on the Laravel side.

## Requirements

* PHP >= 8.3
* Laravel >= 12.0

## Installation

<Steps>
  <Step title="Install via Composer">
    ```bash theme={null}
    composer require revolution/laravel-google-sheets
    ```
  </Step>

  <Step title="Publish Configuration">
    ```bash theme={null}
    php artisan vendor:publish --tag="google-config"
    ```
  </Step>

  <Step title="Enable Google APIs">
    Enable the following APIs in [Google Cloud Console](https://console.cloud.google.com/):

    * **Google Sheets API**
    * **Google Drive API**
  </Step>

  <Step title="Choose and Configure Authentication">
    Select one of three authentication methods:

    * [Service Account](/en/packages/laravel-google-sheets/service-account) — For server-to-server and automated tasks
    * [OAuth 2.0](/en/packages/laravel-google-sheets/oauth) — For user-specific access
    * API Key — For public data only
  </Step>
</Steps>

## Authentication Methods Comparison

| Method              | Use Case                     | User Interaction | Access Scope        | Complexity |
| ------------------- | ---------------------------- | ---------------- | ------------------- | ---------- |
| **Service Account** | Server-to-server, automation | Not required     | Shared spreadsheets | Medium     |
| **OAuth 2.0**       | User-facing apps             | Consent required | User's own sheets   | High       |
| **API Key**         | Public data only             | Not required     | Public sheets only  | Low        |

## Usage

Consider this example spreadsheet structure:

| id | name  | mail  |
| -- | ----- | ----- |
| 1  | name1 | mail1 |
| 2  | name2 | mail2 |

Spreadsheet URL: `https://docs.google.com/spreadsheets/d/{spreadsheetID}/...`

### Service Account Usage

When using Service Account authentication, no token setup is required:

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// Service account authentication is automatic when configured
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]
```

### OAuth Usage

When using OAuth authentication, you need to set the user's access token:

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

$user = $request->user();

$token = [
    'access_token'  => $user->access_token,
    'refresh_token' => $user->refresh_token,
    'expires_in'    => $user->expires_in,
    'created'       => $user->updated_at->getTimestamp(),
];

// all() returns array
$values = Sheets::setAccessToken($token)->spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name1', 'mail2']
// ]
```

### Get a sheet's values with the header as the key (Recommended)

Collection conversion is simple and subsequent processing is flexible, so this method is recommended.

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// get() returns Laravel Collection
$rows = Sheets::sheet('Sheet 1')->get();

$header = $rows->pull(0);
$values = Sheets::collection(header: $header, rows: $rows);
$values->toArray()
// [
//   ['id' => '1', 'name' => 'name1', 'mail' => 'mail1'],
//   ['id' => '2', 'name' => 'name2', 'mail' => 'mail2']
// ]
```

Blade

```php theme={null}
@foreach($values as $value)
  {{ data_get($value, 'name') }}
@endforeach
```

### Using A1 Notation

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

$values = Sheets::sheet('Sheet 1')->range('A1:B2')->all();
// [
//   ['id', 'name'],
//   ['1', 'name1'],
// ]
```

### About A1 Notation

A1 Notation is the standard way to specify a cell or range in Google Sheets (e.g., 'A1', 'A1:B2').

* 'A1' refers to the cell at column A and row 1.
* 'A1:B2' refers to the range from cell A1 to B2 (rectangle).
* 'A:B' refers to all rows in columns A and B.

If you are not familiar with A1 Notation or your range is dynamic/complicated, it is often easier to fetch all data and use Laravel Collections to process/filter it after retrieval.

## Next Steps

* [Service Account Authentication](/en/packages/laravel-google-sheets/service-account) — Most common approach
* [OAuth 2.0 Authentication](/en/packages/laravel-google-sheets/oauth) — For user-specific access
* [laravel-google-sheets](https://github.com/invokable/laravel-google-sheets)
* [Demo Project](https://github.com/invokable/google-sheets-project) — Laravel 5.5 to 13 examples
* [Related Package: Google Search Console API for Laravel](https://github.com/invokable/laravel-google-searchconsole)

## Live Demo

Try the package in action at [Laravel Google Sheets Demo](https://sheets.kawax.biz/).