> ## 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

> Usa Google Sheets API v4 in Laravel. Interfaccia fluente e intuitiva.

Pacchetto Laravel per Google Sheets API v4. Nasconde la complessità della libreria client PHP di Google e offre un'API con method chaining intuitiva ed espressiva.

## Caratteristiche

* **Supporto di più metodi di autenticazione** — OAuth 2.0 (accesso per singolo utente), Service Account (comunicazione server-to-server), API key (dati pubblici)
* **API fluente** — manipola i dati in modo intuitivo con method chaining
* **Integrazione con le Laravel Collection** — converte i dati di Google Sheets in Laravel Collection. Manipolazione degli array semplice
* **Estendibilità** — puoi aggiungere metodi personalizzati alla facade tramite il sistema di macro
* **Integrazione con Google Drive** — gestione ed elenco delle spreadsheet

## Casi d'uso comuni

* **Dashboard utente** — visualizza e manipola dati di Google Sheets
* **Import/Export di dati** — spostamento di grandi quantità di dati tra app Laravel e Google Sheets
* **Generazione automatica di report** — genera e aggiorna report programmaticamente
* **Applicazioni multi-utente** — ogni utente gestisce il proprio Google Sheets

## Filosofia di design

Lo scopo principale del pacchetto è **leggere dati da Google Sheets**. Invece di specificare condizioni fini prima della lettura, il design prevede di scaricare prima tutti i dati come Laravel Collection e poi elaborarli lato Laravel.

## Requisiti di sistema

* PHP >= 8.3
* Laravel >= 12.0

## Installazione

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

  <Step title="Pubblica il file di configurazione">
    ```bash theme={null}
    php artisan vendor:publish --tag="google-config"
    ```
  </Step>

  <Step title="Abilita le API Google">
    Nella [Google Cloud Console](https://console.cloud.google.com/) abilita le seguenti API:

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

  <Step title="Scegli e configura il metodo di autenticazione">
    Scegli tra 3 metodi:

    * [Service Account](/it/packages/laravel-google-sheets/service-account) — per comunicazione server-to-server e task automatici
    * [OAuth 2.0](/it/packages/laravel-google-sheets/oauth) — per accesso per singolo utente
    * API key — solo per dati pubblici
  </Step>
</Steps>

## Scelta del metodo di autenticazione

| Metodo              | Uso                           | Interazione utente | Ambito di accesso          | Difficoltà |
| ------------------- | ----------------------------- | ------------------ | -------------------------- | ---------- |
| **Service Account** | Server-to-server, automazione | Non necessaria     | Spreadsheet condivise      | Media      |
| **OAuth 2.0**       | App orientate agli utenti     | Serve il consenso  | Fogli del singolo utente   | Alta       |
| **API key**         | Solo dati pubblici            | Non necessaria     | Solo spreadsheet pubbliche | Bassa      |

## Uso base

Considera l'esempio della seguente struttura di spreadsheet.

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

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

Prendi `spreadsheetId` dall'URL.

### Service Account

Se usi l'autenticazione con Service Account, non serve impostare il token.

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

// L'autenticazione con Service Account avviene automaticamente in fase di configurazione
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]
```

### OAuth

Se usi l'autenticazione OAuth, devi impostare l'access token dell'utente.

```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() restituisce un array
$values = Sheets::setAccessToken($token)->spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name1', 'mail2']
// ]
```

### Recuperare i valori del foglio usando l'intestazione come chiave (consigliato)

La conversione in collection è semplice ed è più flessibile per l'elaborazione successiva, per cui è il metodo consigliato.

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

// get() restituisce una 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
```

### Uso della notazione A1

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

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

### Sulla notazione A1

La notazione A1 è il modo standard di specificare celle o intervalli in Google Sheets (es.: "A1", "A1:B2").

* "A1" indica la cella nella colonna A, riga 1.
* "A1:B2" indica l'intervallo (rettangolo) dalla cella A1 alla B2.
* "A:B" indica tutte le righe delle colonne A e B.

Se non hai familiarità con la notazione A1, o se l'intervallo è dinamico o complesso, spesso è più semplice recuperare tutti i dati e poi filtrare/processare con le Laravel Collection.

## Passi successivi

* [Autenticazione Service Account](/it/packages/laravel-google-sheets/service-account) — il metodo più comune
* [Autenticazione OAuth 2.0](/it/packages/laravel-google-sheets/oauth) — accesso per singolo utente
* [laravel-google-sheets](https://github.com/invokable/laravel-google-sheets)
* [Progetto demo](https://github.com/invokable/google-sheets-project) — esempi che coprono da Laravel 5.5 a 13
* [Pacchetto correlato: Google Search Console API for Laravel](https://github.com/invokable/laravel-google-searchconsole)

## Demo live

Puoi vedere il funzionamento reale nella [demo di Laravel Google Sheets](https://sheets.kawax.biz/).


## Related topics

- [Autenticazione OAuth 2.0 - Google Sheets API for Laravel](/it/packages/laravel-google-sheets/oauth.md)
- [Autenticazione Service Account - Google Sheets API for Laravel](/it/packages/laravel-google-sheets/service-account.md)
- [Laravel Console Starter](/it/packages/laravel-console-starter/index.md)
- [Laravel Socialite (autenticazione social)](/it/socialite.md)
- [Laravel Cashier (Stripe)](/it/cashier.md)