# Google Drive API Setup Guide

## Overview

This guide explains how to set up Google Drive API integration to enable automatic file transfer from volunteer personal drives to shared Roles folders in Business Drive.

## Workflow

1. **Secretary** (or other volunteer) uploads files to their personal Google Drive (`secretary@elparaisogolf.com`)
2. Files are placed in an "Upload" folder in their personal drive
3. PHP script uses Google Drive API to:
   - List files in volunteer's Upload folder
   - Copy/move files to `Roles/Secretary` (or `Roles/Greens`) in Business Drive
4. Files in Roles folders are shared with all volunteers

## Prerequisites

- Google Workspace account with admin access
- PHP 7.4 or higher
- Composer installed
- Access to Google Cloud Console

## Step 1: Create Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable "Google Drive API" for the project

## Step 2: Create Service Account

1. In Google Cloud Console, go to "IAM & Admin" → "Service Accounts"
2. Click "Create Service Account"
3. Name it: "El Paraiso Drive Transfer"
4. Grant it "Editor" role (or custom role with Drive API permissions)
5. Click "Done"

## Step 3: Create and Download Credentials

1. Click on the service account you just created
2. Go to "Keys" tab
3. Click "Add Key" → "Create new key"
4. Choose "JSON" format
5. Download the JSON file
6. **IMPORTANT:** Save this file securely as `google-drive-credentials.json` in a secure location (NOT in web-accessible directory)

## Step 4: Share Google Drive Folders with Service Account

1. Get the service account email (from the JSON file, it's the `client_email` field)
2. For each volunteer's Upload folder:
   - Open the folder in Google Drive
   - Share it with the service account email
   - Give it "Editor" permissions
3. For Roles folders in Business Drive:
   - Open `Roles/Secretary` and `Roles/Greens` folders
   - Share them with the service account email
   - Give it "Editor" permissions

## Step 5: Install PHP Google API Client

```bash
cd /var/www/html/wordpress6/wordpress/EP
composer require google/apiclient
```

## Step 6: Configure Credentials Path

Update `event-drive-file-transfer.php` to point to your credentials file:

```php
$credentialsPath = '/secure/path/to/google-drive-credentials.json';
```

**Security Note:** Store credentials file outside web root or in a directory with restricted access.

## Step 7: Update Database with Folder IDs

1. Get the folder ID for each volunteer's Upload folder:
   - Open the folder in Google Drive
   - Copy the ID from URL: `https://drive.google.com/drive/folders/FOLDER_ID_HERE`
2. Update `EventVolunteerRoles` table:
   - Add a new column `upload_folder_id` (or use existing `google_drive_folder_id` for target)
   - Store the Upload folder ID for each volunteer

## Implementation Details

### Required API Scopes

The service account needs these scopes:
- `https://www.googleapis.com/auth/drive` - Full Drive access
- `https://www.googleapis.com/auth/drive.file` - Access to files created by the app

### File Transfer Process

1. Authenticate using service account credentials
2. List files in volunteer's Upload folder
3. For each file:
   - Get file metadata
   - Copy file to target Roles folder
   - Optionally delete from source (for move operation)
4. Update UI to show transfer status

### Example API Calls

```php
// Initialize client
$client = new Google_Client();
$client->setAuthConfig($credentialsPath);
$client->addScope(Google_Service_Drive::DRIVE);
$service = new Google_Service_Drive($client);

// List files in folder
$files = $service->files->listFiles([
    'q' => "'FOLDER_ID' in parents and trashed=false",
    'fields' => 'files(id, name, mimeType)'
]);

// Copy file to new location
$file = new Google_Service_Drive_DriveFile();
$file->setParents([$targetFolderId]);
$service->files->copy($sourceFileId, $file);
```

## Security Considerations

1. **Credentials Storage:**
   - Never commit credentials to version control
   - Store outside web root
   - Use environment variables if possible
   - Restrict file permissions (chmod 600)

2. **Access Control:**
   - Only volunteers can access their own transfer page
   - Service account should have minimal required permissions
   - Audit file transfers regularly

3. **Error Handling:**
   - Log all transfer attempts
   - Handle API rate limits
   - Validate file types and sizes

## Testing

1. Upload a test file to volunteer's Upload folder
2. Access the transfer page
3. Verify file appears in list
4. Transfer file
5. Verify file appears in Roles folder
6. Check permissions are correct

## Troubleshooting

### "Insufficient Permission" Error
- Verify service account has access to both source and target folders
- Check folder sharing settings

### "File Not Found" Error
- Verify folder IDs are correct in database
- Check that Upload folder exists and is named correctly

### API Rate Limits
- Google Drive API has rate limits
- Implement retry logic with exponential backoff
- Consider batching operations

## Alternative: Manual Transfer

Until API is set up, volunteers can manually transfer files:
1. Open personal Google Drive
2. Navigate to Upload folder
3. Select files
4. Right-click → "Move to" or "Add shortcut to"
5. Navigate to Business Drive → Roles → [Role Name]
6. Complete transfer

## Next Steps

1. Complete API setup following this guide
2. Update `event-drive-file-transfer.php` with API implementation
3. Test with a single volunteer
4. Roll out to all volunteers
5. Monitor and optimize

## Support

For issues or questions, refer to:
- [Google Drive API Documentation](https://developers.google.com/drive/api)
- [PHP Client Library](https://github.com/googleapis/google-api-php-client)