Getting Started

Minimal Steps

Installation Add the SDK via Composer:
```
composer require aspose/cloud-sdk-php:~1.1
```
Requires PHP 7.2+ and guzzlehttp/guzzle (automatically installed).

Authentication Initialize the SDK with your Aspose Cloud credentials:

use Aspose\Cloud\Sdk\Common\ApiClient;

$apiClient = new ApiClient();
$apiClient->setAppSID('YOUR_APP_SID');
$apiClient->setAppKey('YOUR_APP_KEY');

First Use Case: Convert a PDF to DOCX

use Aspose\Cloud\Sdk\Pdf\PdfApi;

$pdfApi = new PdfApi($apiClient);
$response = $pdfApi->convertDocument(
    'input.pdf', // File in storage
    'docx',      // Output format
    'output.docx'
);

Where to Look First

Documentation: Aspose Cloud REST API Docs (core reference).
SDK Source: src/Aspose/Cloud/Sdk for module-specific examples.
Examples: Check the examples folder for ready-to-use snippets.

Implementation Patterns

Core Workflows

File Operations (Storage Module)

Upload/Download:

use Aspose\Cloud\Sdk\Storage\StorageApi;

$storageApi = new StorageApi($apiClient);
$storageApi->uploadFile('local.pdf', 'cloud.pdf'); // Upload
$storageApi->downloadFile('cloud.pdf', 'local_copy.pdf'); // Download

List Files:

$files = $storageApi->listFiles('folder/');

Document Conversion (Pdf/Words/Slides/Cells)

Batch Processing:

$pdfApi->convertDocument('input.pdf', 'docx', 'output.docx');
$pdfApi->convertDocument('input.pdf', 'html', 'output.html');

Format-Specific Features:

PDF: Extract text, merge/split, annotate.
```
$pdfApi->extractText('file.pdf');
```

Words: Convert to HTML, extract text, apply templates.

use Aspose\Cloud\Sdk\Words\WordsApi;
$wordsApi = new WordsApi($apiClient);
$wordsApi->saveAsHtml('doc.docx', 'output.html');

Cells: Convert XLSX to CSV, manipulate spreadsheets.

use Aspose\Cloud\Sdk\Cells\CellsApi;
$cellsApi = new CellsApi($apiClient);
$cellsApi->convertXlsxToCsv('sheet.xlsx', 'output.csv');

Authentication & Rate Limiting

Use ApiClient to manage credentials and retries:

$apiClient->setAppSID('...')->setAppKey('...');
$apiClient->setTimeout(30); // Adjust timeout as needed

Integration Tips

Laravel Service Providers: Bind the SDK to Laravel’s container for dependency injection:

// app/Providers/AppServiceProvider.php
public function register() {
    $this->app->singleton(ApiClient::class, function ($app) {
        $apiClient = new ApiClient();
        $apiClient->setAppSID(config('aspose.app_sid'));
        $apiClient->setAppKey(config('aspose.app_key'));
        return $apiClient;
    });
}

Queue Jobs for Async Processing: Offload heavy conversions to Laravel queues:

use Aspose\Cloud\Sdk\Pdf\PdfApi;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class ConvertPdfJob implements ShouldQueue {
    use Queueable;

    public function handle(PdfApi $pdfApi) {
        $pdfApi->convertDocument('large.pdf', 'docx', 'output.docx');
    }
}

Error Handling: Wrap SDK calls in try-catch blocks to handle API exceptions:

try {
    $response = $pdfApi->convertDocument('file.pdf', 'docx', 'output.docx');
} catch (\Exception $e) {
    Log::error('Aspose API Error: ' . $e->getMessage());
    throw new \RuntimeException('Conversion failed', 0, $e);
}

Gotchas and Tips

Pitfalls

Authentication Issues
- Problem: 401 Unauthorized errors if App SID/Key are incorrect or expired.
- Fix: Double-check credentials in ApiClient and ensure they have the correct permissions in the Aspose Cloud Dashboard.
- Tip: Use environment variables for credentials:
```
$apiClient->setAppSID(env('ASPOSE_APP_SID'));
```
File Size Limits
- Problem: Large files (>100MB) may fail with 413 Payload Too Large.
- Fix: Split files or request a quota increase from Aspose support.
Rate Limiting
- Problem: Hitting API rate limits (e.g., 50 requests/minute for free tier).
- Fix: Implement exponential backoff in retries:
```
$apiClient->setRetryPolicy(new \GuzzleHttp\Retry\RetryPolicy(3, 100)); // Retry 3 times with 100ms delay
```
Storage Paths
- Problem: Incorrect paths in uploadFile/downloadFile cause 404 Not Found.
- Fix: Use forward slashes (/) and ensure the path exists in Aspose Storage.
Module-Specific Quirks
- PDF: Some operations (e.g., extractText) return raw text; sanitize before rendering.
- Words: Templates require .dotx files; ensure correct template paths.
- Cells: Formulas in spreadsheets may not render correctly in converted formats (e.g., CSV).

Debugging Tips

Enable SDK Logging:

$apiClient->setDebug(true); // Logs requests/responses to storage/logs/

Inspect Raw Responses:

$response = $pdfApi->convertDocument(...);
file_put_contents('debug.json', json_encode($response->getData()));

Common HTTP Errors:
- 400 Bad Request: Invalid input (e.g., unsupported format).
- 404 Not Found: File/path does not exist.
- 500 Internal Server Error: Contact Aspose support with request details.

Extension Points

Custom Headers Add headers to API requests via ApiClient:

$apiClient->setDefaultHeader('Custom-Header', 'value');

Proxy Support Configure proxy settings:

$apiClient->setProxy('http://proxy.example.com', 8080, 'user', 'pass');

Event Hooks Extend the SDK by overriding methods in a custom class:

class CustomPdfApi extends PdfApi {
    public function convertDocument($name, $format, $outPath) {
        // Pre-processing logic
        parent::convertDocument($name, $format, $outPath);
        // Post-processing logic
    }
}

Webhooks for Async Operations Use Aspose’s Webhook API to monitor long-running tasks:
```
$apiClient->setWebhookUrl('https://your-app.com/aspose/webhook');
```

Performance Optimization

Cache Responses: Store converted files locally to avoid repeated cloud calls.

Parallel Processing: Use Laravel’s parallel helper for batch conversions:

\Bus::parallel([
    new ConvertPdfJob('file1.pdf'),
    new ConvertPdfJob('file2.pdf'),
]);

Cloud Sdk Php Laravel Package