Quick Start

Quick Start Guide

Get up and running with Google Sheets Helper in under 10 minutes! This guide covers the essential concepts and shows you how to perform basic operations.

🚀 Prerequisites

Before starting, ensure you have:

• ✅ Installation completed
• ✅ Google Cloud Platform credentials set up
• ✅ Authentication token generated
• ✅ A Google Sheet to work with

📋 Basic Setup

1. Include the Library

<?php
require __DIR__ . '/vendor/autoload.php';

use reandimo\GoogleSheetsApi\Helper;

2. Configure Credentials

Option A: Environment Variables (Recommended)

// Set environment variables
putenv('credentialFilePath=' . __DIR__ . '/credentials.json');
putenv('tokenPath=' . __DIR__ . '/token.json');

// Create instance
$sheets = new Helper();

Option B: Direct File Paths

$sheets = new Helper(
    __DIR__ . '/credentials.json',
    __DIR__ . '/token.json'
);

3. Set Your Spreadsheet

// Set the spreadsheet ID (from the URL)
$sheets->setSpreadsheetId('1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms');

// Set the worksheet name
$sheets->setWorksheetName('Sheet1');

// Set the range to work with
$sheets->setSpreadsheetRange('A1:Z1000');

📖 Reading Data

Read a Range of Values

<?php
try {
    // Set up your sheet
    $sheets->setSpreadsheetId('your-spreadsheet-id');
    $sheets->setWorksheetName('Sheet1');
    $sheets->setSpreadsheetRange('A1:C10');
    
    // Get the values
    $values = $sheets->get();
    
    // Display the data
    foreach ($values as $row) {
        echo implode(' | ', $row) . "\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Read a Single Cell

<?php
try {
    $value = $sheets->getSingleCellValue('B2');
    echo "Value in B2: " . ($value ?: 'empty') . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

✍️ Writing Data

Add a Single Row

<?php
try {
    $sheets->setSpreadsheetRange('A1:C1');
    
    $newRow = ['John Doe', 'john@example.com', 'Developer'];
    $result = $sheets->appendSingleRow($newRow);
    
    if ($result >= 1) {
        echo "Row added successfully!\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Add Multiple Rows

<?php
try {
    $sheets->setSpreadsheetRange('A1:C');
    
    $newRows = [
        ['Jane Smith', 'jane@example.com', 'Designer'],
        ['Bob Johnson', 'bob@example.com', 'Manager'],
        ['Alice Brown', 'alice@example.com', 'Analyst']
    ];
    
    $rowsAdded = $sheets->append($newRows);
    echo "Added {$rowsAdded} rows!\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

🔄 Updating Data

Update a Single Cell

<?php
try {
    $update = $sheets->updateSingleCell('B5', 'Updated Value');
    
    if ($update->getUpdatedCells() >= 1) {
        echo "Cell updated successfully!\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Update a Range

<?php
try {
    $sheets->setSpreadsheetRange('A1:F5');
    
    $newData = [
        ['Header1', 'Header2', 'Header3', 'Header4', 'Header5', 'Header6'],
        ['Data1', 'Data2', 'Data3', 'Data4', 'Data5', 'Data6'],
        ['Data7', 'Data8', 'Data9', 'Data10', 'Data11', 'Data12'],
        ['Data13', 'Data14', 'Data15', 'Data16', 'Data17', 'Data18'],
        ['Data19', 'Data20', 'Data21', 'Data22', 'Data23', 'Data24']
    ];
    
    $update = $sheets->update($newData);
    echo "Updated {$update->getUpdatedCells()} cells!\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

🔍 Finding Data

Search for a Value

<?php
try {
    $sheets->setSpreadsheetRange('A1:Z100');
    
    $result = $sheets->findCellByValue('John Doe');
    
    if ($result) {
        echo "Found 'John Doe' at cell: {$result['cell']}\n";
        echo "Row: {$result['row']}, Column: {$result['column']}\n";
    } else {
        echo "Value not found.\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

📊 Worksheet Management

List All Worksheets

<?php
try {
    $worksheets = $sheets->getSpreadsheetWorksheets();
    
    foreach ($worksheets as $worksheet) {
        echo "Sheet: {$worksheet['title']} (ID: {$worksheet['id']})\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Create a New Worksheet

<?php
try {
    $newSheetId = $sheets->addWorksheet('New Sheet', 1000, 26);
    echo "Created new worksheet with ID: {$newSheetId}\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

🎨 Basic Formatting

Change Background Color

<?php
try {
    $sheets->setSpreadsheetRange('A1:Z10');
    
    // RGB values (Red, Green, Blue)
    $sheets->colorRange([142, 68, 173]); // Purple
    
    echo "Background color applied!\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Clear a Range

<?php
try {
    $sheets->setSpreadsheetRange('A1:Z100');
    
    $cleared = $sheets->clearRange();
    if ($cleared) {
        echo "Range cleared successfully!\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

📝 Complete Example

Here's a complete working example that demonstrates the basic workflow:

<?php
require __DIR__ . '/vendor/autoload.php';

use reandimo\GoogleSheetsApi\Helper;

try {
    // Setup
    putenv('credentialFilePath=' . __DIR__ . '/credentials.json');
    putenv('tokenPath=' . __DIR__ . '/token.json');
    
    $sheets = new Helper();
    $sheets->setSpreadsheetId('your-spreadsheet-id');
    $sheets->setWorksheetName('Sheet1');
    
    // Read existing data
    $sheets->setSpreadsheetRange('A1:C10');
    $existingData = $sheets->get();
    echo "Found " . count($existingData) . " rows of existing data.\n";
    
    // Add new data
    $sheets->setSpreadsheetRange('A1:C1');
    $newRow = ['New User', 'newuser@example.com', 'Tester'];
    $sheets->appendSingleRow($newRow);
    echo "Added new row.\n";
    
    // Update a cell
    $sheets->updateSingleCell('B2', 'Updated Email');
    echo "Updated cell B2.\n";
    
    // Search for data
    $sheets->setSpreadsheetRange('A1:C100');
    $found = $sheets->findCellByValue('New User');
    if ($found) {
        echo "Found 'New User' at: {$found['cell']}\n";
    }
    
    echo "✅ All operations completed successfully!\n";
    
} catch (Exception $e) {
    echo "❌ Error: " . $e->getMessage() . "\n";
}

🚨 Important Notes

Always Set Required Properties

Before any operation, ensure you've set:

$sheets->setSpreadsheetId('your-id');
$sheets->setSpreadsheetRange('A1:Z100');
$sheets->setWorksheetName('Sheet1');

Error Handling

Always wrap your code in try-catch blocks:

try {
    // Your code here
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Value Input Options

Control how values are interpreted:

// RAW = insert data as-is
$sheets->setValueInputOption('RAW');

// USER_ENTERED = parse as if user typed
$sheets->setValueInputOption('USER_ENTERED');

🔗 Next Steps

Now that you have the basics down:

1. Configuration - Learn about advanced configuration options
2. Data Operations - Deep dive into reading and writing data
3. Worksheet Management - Advanced worksheet operations
4. Examples - More complex examples and use cases
5. API Reference - Complete method documentation

💡 Tips

• Start Simple: Begin with basic operations before moving to complex ones
• Test Small: Test with small ranges before working with large datasets
• Handle Errors: Always implement proper error handling
• Use Environment Variables: Keep credentials secure with environment variables
• Check Permissions: Ensure your service account has proper access to sheets

---

Questions? Check the FAQ or open an issue on GitHub!