Skip to content

Instantly share code, notes, and snippets.

@fadlee

fadlee/Laravel-Sheets.md

Created May 2, 2025 06:33
Show Gist options
  • Save fadlee/9f4027e2d33a2b13a119b260e3348afc to your computer and use it in GitHub Desktop.
Save fadlee/9f4027e2d33a2b13a119b260e3348afc to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Laravel-Sheets.md

Laravel-Google Sheets Two-Way Synchronization (Using Google Apps Script)

This guide will help you create a bidirectional synchronization system between Laravel and Google Sheets using Google Apps Script to handle the connection, without requiring the Google Sheets API.

Overview of the Solution

  1. Google Apps Script Setup: Create a web app that exposes REST endpoints for your Laravel app to interact with the spreadsheet
  2. Laravel Project Setup: Create models, services, and controllers to handle the data
  3. Two-Way Synchronization: Set up bidirectional sync between Google Sheets and Laravel

1. Google Apps Script Setup

1.1 Create Your Google Sheet

  1. Create a new Google Sheet or use an existing one
  2. Add column headers in the first row (e.g., id, name, email, description, updated_at)
  3. Note the Sheet ID from the URL (it's the long string between /d/ and /edit)

1.2 Create Google Apps Script

  1. From your Google Sheet, go to Extensions > Apps Script
  2. Replace the default code with the following script:
// Global variables
const SHEET_ID = ''; // Your spreadsheet ID (leave empty to use the current spreadsheet)
const SHEET_NAME = 'Sheet1'; // Change to your sheet name
const API_KEY = 'your_secret_api_key'; // Create a secret key for authentication

// Get sheet by name
function getSheetByName() {
  const ss = SHEET_ID ? SpreadsheetApp.openById(SHEET_ID) : SpreadsheetApp.getActiveSpreadsheet();
  return ss.getSheetByName(SHEET_NAME);
}

// Get all data including headers
function getAllData() {
  const sheet = getSheetByName();
  const data = sheet.getDataRange().getValues();
  return data;
}

// Convert sheet data to JSON with headers as keys
function getDataAsJson() {
  const data = getAllData();
  const headers = data[0];
  const jsonData = [];
  
  // Skip header row (i=1)
  for (let i = 1; i < data.length; i++) {
    const row = data[i];
    const record = {};
    
    for (let j = 0; j < headers.length; j++) {
      record[headers[j]] = row[j];
    }
    
    // Add row index for reference
    record._rowIndex = i + 1;
    jsonData.push(record);
  }
  
  return jsonData;
}

// Find record by ID
function findRecordById(id) {
  const jsonData = getDataAsJson();
  return jsonData.find(record => record.id == id);
}

// Find row index by ID
function findRowIndexById(id) {
  const sheet = getSheetByName();
  const data = sheet.getDataRange().getValues();
  const idColumnIndex = data[0].indexOf('id');
  
  if (idColumnIndex === -1) return -1;
  
  for (let i = 1; i < data.length; i++) {
    if (data[i][idColumnIndex] == id) {
      return i + 1; // +1 because array is 0-based, but sheets are 1-based
    }
  }
  
  return -1;
}

// Update or create a record
function upsertRecord(record) {
  const sheet = getSheetByName();
  const headers = sheet.getRange(1, 1, 1, sheet.getLastColumn()).getValues()[0];
  
  // Find row by ID if it exists
  const rowIndex = record.id ? findRowIndexById(record.id) : -1;
  
  // Prepare row data based on headers
  const rowData = headers.map(header => record[header] || '');
  
  if (rowIndex > 0) {
    // Update existing record
    sheet.getRange(rowIndex, 1, 1, headers.length).setValues([rowData]);
    return { success: true, action: 'updated', rowIndex: rowIndex };
  } else {
    // Create new record
    sheet.appendRow(rowData);
    return { success: true, action: 'created', rowIndex: sheet.getLastRow() };
  }
}

// Delete a record by ID
function deleteRecord(id) {
  const rowIndex = findRowIndexById(id);
  
  if (rowIndex > 0) {
    const sheet = getSheetByName();
    sheet.deleteRow(rowIndex);
    return { success: true, action: 'deleted' };
  }
  
  return { success: false, error: 'Record not found' };
}

// Set up web app endpoints
function doGet(e) {
  // Verify API key
  if (e.parameter.key !== API_KEY) {
    return ContentService.createTextOutput(JSON.stringify({ error: 'Unauthorized' }))
      .setMimeType(ContentService.MimeType.JSON);
  }
  
  const action = e.parameter.action;
  let result;
  
  if (action === 'list') {
    // Get all records
    result = getDataAsJson();
  } else if (action === 'get') {
    // Get single record
    const id = e.parameter.id;
    result = findRecordById(id) || { error: 'Record not found' };
  } else {
    result = { error: 'Invalid action' };
  }
  
  return ContentService.createTextOutput(JSON.stringify(result))
    .setMimeType(ContentService.MimeType.JSON);
}

function doPost(e) {
  // Verify API key
  if (e.parameter.key !== API_KEY) {
    return ContentService.createTextOutput(JSON.stringify({ error: 'Unauthorized' }))
      .setMimeType(ContentService.MimeType.JSON);
  }
  
  const action = e.parameter.action;
  let result;
  
  try {
    const payload = JSON.parse(e.postData.contents);
    
    if (action === 'update' || action === 'create') {
      // Update or create record
      result = upsertRecord(payload);
    } else if (action === 'delete') {
      // Delete record
      const id = payload.id;
      result = deleteRecord(id);
    } else if (action === 'batch') {
      // Process multiple records
      const records = payload.records;
      const results = [];
      
      for (const record of records) {
        results.push(upsertRecord(record));
      }
      
      result = { success: true, results: results };
    } else {
      result = { error: 'Invalid action' };
    }
  } catch (error) {
    result = { error: error.toString() };
  }
  
  return ContentService.createTextOutput(JSON.stringify(result))
    .setMimeType(ContentService.MimeType.JSON);
}

// Track sheet changes and ping Laravel when changes occur
function onEdit(e) {
  // Get information about the edited cell
  const sheet = e.source.getActiveSheet();
  const sheetName = sheet.getName();
  
  // Only process edits on the target sheet
  if (sheetName !== SHEET_NAME) return;
  
  const row = e.range.getRow();
  const col = e.range.getColumn();
  
  // Skip header row
  if (row === 1) return;
  
  // Get row data for the edited row
  const headers = sheet.getRange(1, 1, 1, sheet.getLastColumn()).getValues()[0];
  const rowData = sheet.getRange(row, 1, 1, headers.length).getValues()[0];
  
  // Create record object
  const record = {};
  for (let i = 0; i < headers.length; i++) {
    record[headers[i]] = rowData[i];
  }
  
  // Add row index
  record._rowIndex = row;
  
  // Notify Laravel about the change (replace with your Laravel endpoint URL)
  try {
    const laravelEndpoint = 'https://your-laravel-app.com/api/sheets-webhook';
    const payload = JSON.stringify({
      source: 'sheets',
      action: 'update',
      data: record
    });
    
    const options = {
      'method': 'post',
      'contentType': 'application/json',
      'payload': payload,
      'headers': {
        'X-API-KEY': API_KEY
      },
      'muteHttpExceptions': true // Prevents the script from failing on HTTP errors
    };
    
    UrlFetchApp.fetch(laravelEndpoint, options);
  } catch (error) {
    // Log errors but don't interrupt the user
    console.error('Failed to notify Laravel: ' + error.toString());
  }
}

1.3 Deploy as Web App

  1. Click on "Deploy" > "New deployment"
  2. Select type: "Web app"
  3. Description: "Google Sheets Laravel Sync"
  4. Execute as: "Me"
  5. Who has access: "Anyone"
  6. Click "Deploy"
  7. Copy the "Web app URL" that appears - you'll need this for your Laravel application

2. Laravel Project Setup

2.1 Create a New Laravel Project (if needed)

composer create-project laravel/laravel google-sheets-sync
cd google-sheets-sync

2.2 Create Model and Migration

Create a model for the synchronized data:

php artisan make:model SyncedData -m

Edit the migration file (database/migrations/yyyy_mm_dd_create_synced_data_table.php):

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('synced_data', function (Blueprint $table) {
            $table->id();
            $table->string('name')->nullable();
            $table->string('email')->nullable();
            $table->text('description')->nullable();
            // Add any other fields you need to sync
            $table->boolean('is_dirty')->default(false);
            $table->timestamp('last_synced_at')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('synced_data');
    }
};

Edit the model (app/Models/SyncedData.php):

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class SyncedData extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'email',
        'description',
        'is_dirty',
        'last_synced_at',
    ];

    protected $casts = [
        'is_dirty' => 'boolean',
        'last_synced_at' => 'datetime',
    ];

    // Mark record as dirty when updated
    protected static function booted()
    {
        static::updated(function ($model) {
            // Only mark as dirty if actual data fields were changed (not metadata)
            if ($model->isDirty(['name', 'email', 'description'])) {
                $model->is_dirty = true;
                $model->save();
            }
        });

        static::created(function ($model) {
            $model->is_dirty = true;
            $model->save();
        });
    }
}

2.3 Create a Google Sheets Service

Create a service file (app/Services/GoogleSheetsService.php):

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Carbon\Carbon;

class GoogleSheetsService
{
    protected $appScriptUrl;
    protected $apiKey;

    public function __construct()
    {
        $this->appScriptUrl = config('services.google_sheets.app_script_url');
        $this->apiKey = config('services.google_sheets.api_key');
    }

    /**
     * Get all records from Google Sheets
     */
    public function getAllRecords()
    {
        try {
            $response = Http::get($this->appScriptUrl, [
                'action' => 'list',
                'key' => $this->apiKey
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Failed to get records from Google Sheets', [
                'status' => $response->status(),
                'body' => $response->body()
            ]);

            return null;
        } catch (\Exception $e) {
            Log::error('Error fetching records from Google Sheets: ' . $e->getMessage());
            return null;
        }
    }

    /**
     * Get a single record from Google Sheets
     */
    public function getRecord($id)
    {
        try {
            $response = Http::get($this->appScriptUrl, [
                'action' => 'get',
                'id' => $id,
                'key' => $this->apiKey
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Failed to get record from Google Sheets', [
                'id' => $id,
                'status' => $response->status(),
                'body' => $response->body()
            ]);

            return null;
        } catch (\Exception $e) {
            Log::error('Error fetching record from Google Sheets: ' . $e->getMessage());
            return null;
        }
    }

    /**
     * Create or update a record in Google Sheets
     */
    public function upsertRecord($record)
    {
        try {
            $response = Http::post($this->appScriptUrl . '?action=update&key=' . $this->apiKey, $record);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Failed to update record in Google Sheets', [
                'record' => $record,
                'status' => $response->status(),
                'body' => $response->body()
            ]);

            return null;
        } catch (\Exception $e) {
            Log::error('Error updating record in Google Sheets: ' . $e->getMessage());
            return null;
        }
    }

    /**
     * Send multiple records to Google Sheets (batch operation)
     */
    public function batchUpdate($records)
    {
        try {
            $response = Http::post($this->appScriptUrl . '?action=batch&key=' . $this->apiKey, [
                'records' => $records
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Failed to batch update records in Google Sheets', [
                'record_count' => count($records),
                'status' => $response->status(),
                'body' => $response->body()
            ]);

            return null;
        } catch (\Exception $e) {
            Log::error('Error batch updating records in Google Sheets: ' . $e->getMessage());
            return null;
        }
    }

    /**
     * Delete a record from Google Sheets
     */
    public function deleteRecord($id)
    {
        try {
            $response = Http::post($this->appScriptUrl . '?action=delete&key=' . $this->apiKey, [
                'id' => $id
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Failed to delete record from Google Sheets', [
                'id' => $id,
                'status' => $response->status(),
                'body' => $response->body()
            ]);

            return null;
        } catch (\Exception $e) {
            Log::error('Error deleting record from Google Sheets: ' . $e->getMessage());
            return null;
        }
    }
}

2.4 Create Synchronization Service

Create a service file (app/Services/SyncService.php):

<?php

namespace App\Services;

use App\Models\SyncedData;
use App\Services\GoogleSheetsService;
use Illuminate\Support\Facades\Log;
use Carbon\Carbon;

class SyncService
{
    protected $sheetsService;

    public function __construct(GoogleSheetsService $sheetsService)
    {
        $this->sheetsService = $sheetsService;
    }

    /**
     * Sync data from Google Sheets to the Laravel database
     */
    public function syncFromSheets()
    {
        try {
            // Get all records from Google Sheets
            $sheetRecords = $this->sheetsService->getAllRecords();

            if (!$sheetRecords) {
                return false;
            }

            foreach ($sheetRecords as $sheetRecord) {
                // Skip records without an ID
                if (empty($sheetRecord['id'])) {
                    continue;
                }

                // Try to find the record in the database
                $localRecord = SyncedData::find($sheetRecord['id']);

                if ($localRecord) {
                    // Skip if the local record is dirty (has pending changes)
                    if ($localRecord->is_dirty) {
                        continue;
                    }

                    // Update existing record
                    $localRecord->update([
                        'name' => $sheetRecord['name'] ?? $localRecord->name,
                        'email' => $sheetRecord['email'] ?? $localRecord->email,
                        'description' => $sheetRecord['description'] ?? $localRecord->description,
                        'last_synced_at' => now(),
                    ]);
                } else {
                    // Create new record
                    SyncedData::create([
                        'id' => $sheetRecord['id'],
                        'name' => $sheetRecord['name'] ?? null,
                        'email' => $sheetRecord['email'] ?? null,
                        'description' => $sheetRecord['description'] ?? null,
                        'is_dirty' => false,
                        'last_synced_at' => now(),
                    ]);
                }
            }

            return true;
        } catch (\Exception $e) {
            Log::error('Error syncing from sheets: ' . $e->getMessage());
            return false;
        }
    }

    /**
     * Sync data from Laravel database to Google Sheets
     */
    public function syncToSheets()
    {
        try {
            // Get all dirty records
            $dirtyRecords = SyncedData::where('is_dirty', true)->get();

            if ($dirtyRecords->isEmpty()) {
                return true; // Nothing to sync
            }

            // Prepare records for batch update
            $recordsToSync = [];
            foreach ($dirtyRecords as $record) {
                $recordsToSync[] = [
                    'id' => $record->id,
                    'name' => $record->name,
                    'email' => $record->email,
                    'description' => $record->description,
                    'updated_at' => $record->updated_at->toDateTimeString(),
                ];
            }

            // Send batch update to Google Sheets
            $result = $this->sheetsService->batchUpdate($recordsToSync);

            if (!$result || !isset($result['success']) || $result['success'] !== true) {
                return false;
            }

            // Mark records as synced
            foreach ($dirtyRecords as $record) {
                $record->update([
                    'is_dirty' => false,
                    'last_synced_at' => now(),
                ]);
            }

            return true;
        } catch (\Exception $e) {
            Log::error('Error syncing to sheets: ' . $e->getMessage());
            return false;
        }
    }

    /**
     * Handle webhook updates from Google Sheets
     */
    public function handleSheetWebhook($data)
    {
        try {
            // Validate the data
            if (!isset($data['data']) || !isset($data['data']['id'])) {
                return false;
            }

            $sheetData = $data['data'];
            $recordId = $sheetData['id'];

            // Find or create the record
            $record = SyncedData::find($recordId);

            if (!$record) {
                // Create new record
                $record = SyncedData::create([
                    'id' => $recordId,
                    'name' => $sheetData['name'] ?? null,
                    'email' => $sheetData['email'] ?? null,
                    'description' => $sheetData['description'] ?? null,
                    'is_dirty' => false,
                    'last_synced_at' => now(),
                ]);
            } else {
                // Only update if not dirty
                if (!$record->is_dirty) {
                    $record->update([
                        'name' => $sheetData['name'] ?? $record->name,
                        'email' => $sheetData['email'] ?? $record->email,
                        'description' => $sheetData['description'] ?? $record->description,
                        'is_dirty' => false,
                        'last_synced_at' => now(),
                    ]);
                }
            }

            return true;
        } catch (\Exception $e) {
            Log::error('Error handling sheet webhook: ' . $e->getMessage());
            return false;
        }
    }
}

2.5 Create Controllers

Create a webhook controller (app/Http/Controllers/WebhookController.php):

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\SyncService;
use Illuminate\Support\Facades\Log;

class WebhookController extends Controller
{
    protected $syncService;

    public function __construct(SyncService $syncService)
    {
        $this->syncService = $syncService;
    }

    /**
     * Handle incoming webhook from Google Sheets
     */
    public function handleSheetWebhook(Request $request)
    {
        // Validate API key
        if ($request->header('X-API-KEY') !== config('services.google_sheets.api_key')) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        try {
            $data = $request->all();
            
            // Process the webhook data
            $success = $this->syncService->handleSheetWebhook($data);
            
            if ($success) {
                return response()->json(['success' => true]);
            } else {
                return response()->json(['error' => 'Failed to process webhook data'], 422);
            }
        } catch (\Exception $e) {
            Log::error('Webhook processing error: ' . $e->getMessage());
            return response()->json(['error' => 'Internal server error'], 500);
        }
    }
}

Create a sync controller (app/Http/Controllers/SyncController.php):

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\SyncService;
use App\Models\SyncedData;

class SyncController extends Controller
{
    protected $syncService;

    public function __construct(SyncService $syncService)
    {
        $this->syncService = $syncService;
    }

    /**
     * Show the dashboard with data and sync status
     */
    public function dashboard()
    {
        $records = SyncedData::orderBy('id')->get();
        $dirtyCount = SyncedData::where('is_dirty', true)->count();
        
        return view('dashboard', compact('records', 'dirtyCount'));
    }

    /**
     * Synchronize from Google Sheets to database
     */
    public function syncFromSheets()
    {
        $success = $this->syncService->syncFromSheets();
        
        if ($success) {
            return redirect()->route('dashboard')->with('success', 'Successfully synced from Google Sheets');
        } else {
            return redirect()->route('dashboard')->with('error', 'Failed to sync from Google Sheets');
        }
    }

    /**
     * Synchronize from database to Google Sheets
     */
    public function syncToSheets()
    {
        $success = $this->syncService->syncToSheets();
        
        if ($success) {
            return redirect()->route('dashboard')->with('success', 'Successfully synced to Google Sheets');
        } else {
            return redirect()->route('dashboard')->with('error', 'Failed to sync to Google Sheets');
        }
    }
}

2.6 Create Command for Scheduled Sync

Create a command for scheduled sync:

php artisan make:command SyncWithGoogleSheets

Edit the command file (app/Console/Commands/SyncWithGoogleSheets.php):

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Services\SyncService;

class SyncWithGoogleSheets extends Command
{
    protected $signature = 'sync:sheets {direction=both : The sync direction (from, to, or both)}';
    protected $description = 'Synchronize data with Google Sheets';

    public function handle(SyncService $syncService)
    {
        $direction = $this->argument('direction');
        
        if ($direction === 'from' || $direction === 'both') {
            $this->info('Syncing from Google Sheets to database...');
            $result = $syncService->syncFromSheets();
            if ($result) {
                $this->info('Successfully synced from Google Sheets');
            } else {
                $this->error('Failed to sync from Google Sheets');
            }
        }
        
        if ($direction === 'to' || $direction === 'both') {
            $this->info('Syncing from database to Google Sheets...');
            $result = $syncService->syncToSheets();
            if ($result) {
                $this->info('Successfully synced to Google Sheets');
            } else {
                $this->error('Failed to sync to Google Sheets');
            }
        }
    }
}

2.7 Add Scheduled Task

Edit the kernel file (app/Console/Kernel.php):

<?php

namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    /**
     * Define the application's command schedule.
     */
    protected function schedule(Schedule $schedule): void
    {
        // Run every 5 minutes
        $schedule->command('sync:sheets')->everyFiveMinutes();
    }

    /**
     * Register the commands for the application.
     */
    protected function commands(): void
    {
        $this->load(__DIR__.'/Commands');

        require base_path('routes/console.php');
    }
}

2.8 Define Routes

Add these routes to your routes/web.php file:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\SyncController;
use App\Http\Controllers\WebhookController;

Route::get('/', [SyncController::class, 'dashboard'])->name('dashboard');
Route::get('/sync-from-sheets', [SyncController::class, 'syncFromSheets'])->name('sync.from');
Route::get('/sync-to-sheets', [SyncController::class, 'syncToSheets'])->name('sync.to');

// Webhook endpoint
Route::post('/api/sheets-webhook', [WebhookController::class, 'handleSheetWebhook']);

2.9 Configuration

Add Google Sheets configuration to your config/services.php file:

'google_sheets' => [
    'app_script_url' => env('GOOGLE_SHEETS_APP_SCRIPT_URL'),
    'api_key' => env('GOOGLE_SHEETS_API_KEY'),
],

Update your .env file:

GOOGLE_SHEETS_APP_SCRIPT_URL=https://script.google.com/macros/s/your-script-id/exec
GOOGLE_SHEETS_API_KEY=your_secret_api_key

2.10 Create a Simple Dashboard View

Create a file at resources/views/dashboard.blade.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Google Sheets Sync Dashboard</title>
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
    <div class="container mt-5">
        <h1>Google Sheets Sync Dashboard</h1>
        
        @if(session('success'))
            <div class="alert alert-success">
                {{ session('success') }}
            </div>
        @endif
        
        @if(session('error'))
            <div class="alert alert-danger">
                {{ session('error') }}
            </div>
        @endif
        
        <div class="row mb-4">
            <div class="col-md-6">
                <div class="card">
                    <div class="card-body">
                        <h5 class="card-title">Sync Status</h5>
                        <p>Records pending sync: <span class="badge bg-warning">{{ $dirtyCount }}</span></p>
                        <div class="d-flex gap-2">
                            <a href="{{ route('sync.from') }}" class="btn btn-primary">Sync From Sheets</a>
                            <a href="{{ route('sync.to') }}" class="btn btn-success">Sync To Sheets</a>
                        </div>
                    </div>
                </div>
            </div>
        </div>
        
        <div class="card">
            <div class="card-header">
                <h5>Synchronized Data</h5>
            </div>
            <div class="card-body">
                <table class="table table-striped">
                    <thead>
                        <tr>
                            <th>ID</th>
                            <th>Name</th>
                            <th>Email</th>
                            <th>Description</th>
                            <th>Last Synced</th>
                            <th>Status</th>
                        </tr>
                    </thead>
                    <tbody>
                        @foreach($records as $record)
                            <tr>
                                <td>{{ $record->id }}</td>
                                <td>{{ $record->name }}</td>
                                <td>{{ $record->email }}</td>
                                <td>{{ $record->description }}</td>
                                <td>{{ $record->last_synced_at ? $record->last_synced_at->diffForHumans() : 'Never' }}</td>
                                <td>
                                    @if($record->is_dirty)
                                        <span class="badge bg-warning">Pending Sync</span>
                                    @else
                                        <span class="badge bg-success">Synced</span>
                                    @endif
                                </td>
                            </tr>
                        @endforeach
                    </tbody>
                </table>
            </div>
        </div>
    </div>
</body>
</html>

3. How the Two-Way Sync Works

  1. From Google Sheets to Laravel:

    • When changes are made in Google Sheets, the onEdit trigger in the Apps Script sends a webhook to your Laravel application
    • The webhook controller updates the database with the changes
    • Records are only updated if they don't have pending changes (not dirty)

  2. From Laravel to Google Sheets:

    • When data is created or updated in Laravel, the model automatically marks it as "dirty"
    • The scheduled task runs periodically to send dirty records to Google Sheets
    • Manual sync can also be triggered through the dashboard
    • After successful sync, records are marked as "clean" (not dirty)

  3. Conflict Resolution:

    • The system prioritizes local changes (dirty records) over incoming sheet changes
    • This prevents data loss when changes occur on both sides between syncs

4. Testing Your Setup

4.1 Deploy Google Apps Script

  1. Make sure you've saved and deployed your Google Apps Script as a web app
  2. Copy the deployment URL to your Laravel .env file

4.2 Set Up Laravel Application

  1. Run database migrations:
php artisan migrate
  1. Start the scheduler (for development):
php artisan schedule:work
  1. Expose your local endpoint for webhook testing:
    • You can use tools like ngrok (ngrok http 8000)
    • Update the webhook URL in the Google Apps Script to your exposed endpoint

4.3 Test the Sync

  1. Make changes in Google Sheets and verify they appear in Laravel
  2. Make changes in Laravel and click "Sync to Sheets" to send them to Google Sheets
  3. Check that bidirectional sync works as expected

5. Advanced Customizations

5.1 Add Authentication to the Dashboard

For production use, it's recommended to add authentication to your dashboard:

php artisan make:auth

5.2 Add Logging and Notifications

Add detailed logging to track sync issues and add notifications for sync failures:

// In SyncService.php

use Illuminate\Support\Facades\Notification;
use App\Notifications\SyncFailed;

// Inside syncToSheets or syncFromSheets methods:
if (!$result) {
    Log::error('Sync failed', ['direction' => 'to_sheets', 'records' => count($dirtyRecords)]);
    Notification::route('mail', '[email protected]')
        ->notify(new SyncFailed('to_sheets'));
    return false;
}

5.3 Add Data Validation

Enhance data validation to ensure consistency:

// In SyncService.php

// Inside syncFromSheets method:
// Validate incoming data
if (!isset($sheetRecord['name']) || empty($sheetRecord['name'])) {
    Log::warning('Skipping record with missing name', ['record' => $sheetRecord]);
    continue;
}

6. Production Considerations

6.1 Scale the Solution

For larger datasets or high-frequency updates:

  1. Queue Sync Jobs: Use Laravel's queue system for syncing operations
  2. Batch Processing: Process records in smaller batches
  3. Selective Sync: Only sync specific fields or tables as needed

6.2 Security Best Practices

  1. API Key Rotation: Regularly rotate your API key
  2. HTTPS Only: Ensure all communication uses HTTPS
  3. IP Restrictions: Consider limiting webhook access to specific IPs

6.3 Error Handling

Implement more robust error handling:

  1. Retry Logic: Add retry logic for failed sync operations
  2. Monitoring: Set up monitoring to alert on persistent sync issues
  3. Conflict Resolution: Implement more sophisticated conflict resolution strategies

Conclusion

This solution provides a robust two-way synchronization between Laravel and Google Sheets using Google Apps Script as the connection method. The benefits include:

  1. No need for Google API credentials or complex setup
  2. Automatic real-time updates in both directions
  3. Conflict resolution that preserves data integrity
  4. Simple dashboard for monitoring and manual sync

By following this approach, your Laravel application data will stay in sync with your Google Sheets, allowing both systems to be used interchangeably while maintaining data consistency.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment