first commit

2026-03-22 22:06:59 +00:00
commit ad5b3fde24
12 changed files with 1081 additions and 0 deletions
@@ -0,0 +1,137 @@
+# Zoho API Integration
+
+Modular PHP integration with Zoho APIs (Projects, Desk, and more).
+
+## Features
+
+- **Modular Architecture**: Easy to add new Zoho services
+- **OAuth2 Authentication**: Secure token management with auto-refresh
+- **Multiple Export Formats**: JSON and CSV support
+- **Logging**: File-based logging for monitoring
+- **Cron-Ready**: Built for hourly automated exports
+
+## Directory Structure
+
+```
+zoho-qwen/
+├── config/
+│   └── config.php          # Configuration settings
+├── src/
+│   ├── Core/
+│   │   └── ZohoClient.php  # OAuth2 & HTTP client
+│   ├── Interfaces/
+│   │   └── ZohoServiceInterface.php
+│   ├── Services/
+│   │   ├── ProjectsService.php
+│   │   └── DeskService.php
+│   ├── Export/
+│   │   └── ExportManager.php
+│   └── Utils/
+│       └── Logger.php
+├── scripts/
+│   ├── authenticate.php    # OAuth2 setup
+│   └── export_projects.php # Export script
+├── cron/
+│   └── hourly_export.sh    # Cron wrapper
+└── storage/                # Tokens, exports, logs (auto-created)
+```
+
+## Setup
+
+### 1. Install Requirements
+
+- PHP 8.0+
+- cURL extension
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env
+# Edit .env with your Zoho credentials
+```
+
+### 3. Register Zoho Application
+
+1. Visit [Zoho API Console](https://api-console.zoho.com/)
+2. Create a new client
+3. Select "Server-based Application"
+4. Add your redirect URI
+5. Copy Client ID and Client Secret to `.env`
+
+### 4. Authenticate
+
+```bash
+# Generate authorization URL
+php scripts/authenticate.php --service=projects
+
+# Visit the URL, authorize, then exchange the code:
+php scripts/authenticate.php --service=projects --code=YOUR_CODE
+```
+
+### 5. Run Export
+
+```bash
+# Manual export
+php scripts/export_projects.php
+
+# Include task details
+php scripts/export_projects.php --include-tasks
+
+# Export as CSV
+php scripts/export_projects.php --format=csv
+```
+
+### 6. Setup Cron (Optional)
+
+```bash
+# Edit the cron script path
+nano cron/hourly_export.sh
+
+# Add to crontab (runs every hour)
+crontab -e
+# Add: 0 * * * * /path/to/cron/hourly_export.sh
+```
+
+## Adding New Zoho Services
+
+1. Add service config in `config/config.php`:
+
+```php
+'desk' => [
+    'enabled' => true,
+    'api_base' => 'https://desk.zoho.com/api/v1',
+    'scopes' => 'ZohoDesk.tickets.READ',
+],
+```
+
+2. Create service class implementing `ZohoServiceInterface`:
+
+```php
+class DeskService implements ZohoServiceInterface
+{
+    // Implement required methods
+}
+```
+
+3. Create export script for the service
+
+## Configuration
+
+Edit `config/config.php` to customize:
+
+- API domains (for EU/US data centers)
+- OAuth scopes
+- Export formats and locations
+- Log levels
+
+## Troubleshooting
+
+**Token expired errors**: Re-run authentication script
+
+**401 Unauthorized**: Check OAuth scopes in config
+
+**Export directory not writable**: `chmod 755 storage/exports`
+
+## License
+
+MIT