240 lines
6.6 KiB
Markdown
240 lines
6.6 KiB
Markdown
# Twilio PHP SDK Migration Guide
|
|
|
|
This document outlines the migration of the Twilio WordPress Plugin from a custom API wrapper to the official Twilio PHP SDK v8.7.0.
|
|
|
|
## Overview
|
|
|
|
The plugin now supports both the official Twilio PHP SDK and falls back to a custom implementation when the SDK is not available. This provides better error handling, type safety, and access to the latest Twilio features while maintaining backward compatibility.
|
|
|
|
## Installation
|
|
|
|
### Option 1: Using the Installation Script (Recommended)
|
|
|
|
1. Navigate to your plugin directory
|
|
2. Run the installation script:
|
|
```bash
|
|
chmod +x install-twilio-sdk.sh
|
|
./install-twilio-sdk.sh
|
|
```
|
|
|
|
### Option 2: Manual Installation with Composer
|
|
|
|
1. Ensure Composer is installed on your system
|
|
2. Run in the plugin directory:
|
|
```bash
|
|
composer install
|
|
```
|
|
|
|
### Option 3: Manual Download
|
|
|
|
1. Download Twilio SDK v8.7.0 from: https://github.com/twilio/twilio-php/releases
|
|
2. Extract to `vendor/twilio/sdk/`
|
|
3. Create autoloader file (see installation script for reference)
|
|
|
|
## How It Works
|
|
|
|
### Auto-Detection
|
|
|
|
The plugin automatically detects if the Twilio SDK is available by:
|
|
1. Checking for `vendor/autoload.php`
|
|
2. Verifying the `Twilio\Rest\Client` class exists
|
|
3. Attempting to initialize the client
|
|
|
|
### Dual-Mode Operation
|
|
|
|
**SDK Mode (When Available):**
|
|
- Uses official Twilio PHP SDK classes
|
|
- Better error handling with specific Twilio exceptions
|
|
- Type safety and IDE support
|
|
- Automatic retries and rate limiting
|
|
- Official TwiML generation classes
|
|
|
|
**Fallback Mode (Default):**
|
|
- Uses custom WordPress HTTP API calls
|
|
- String-based TwiML generation
|
|
- Maintains all existing functionality
|
|
- No external dependencies required
|
|
|
|
## Code Changes
|
|
|
|
### API Class Updates
|
|
|
|
The `TWP_Twilio_API` class now:
|
|
- Detects SDK availability in the constructor
|
|
- Routes all methods through SDK when available
|
|
- Falls back to custom implementation seamlessly
|
|
- Maintains identical method signatures for compatibility
|
|
|
|
### TwiML Generation
|
|
|
|
**New Unified Approach:**
|
|
```php
|
|
// Works with both SDK and fallback
|
|
$api = new TWP_Twilio_API();
|
|
$response = $api->create_twiml();
|
|
$response->say('Hello world', ['voice' => 'alice']);
|
|
$response->dial('+1234567890', ['timeout' => 30]);
|
|
$twiml = $response->asXML();
|
|
```
|
|
|
|
**Old Approach (Now Deprecated):**
|
|
```php
|
|
// String concatenation - now handled automatically
|
|
$twiml = '<?xml version="1.0" encoding="UTF-8"?>';
|
|
$twiml .= '<Response>';
|
|
$twiml .= '<Say voice="alice">Hello world</Say>';
|
|
$twiml .= '</Response>';
|
|
```
|
|
|
|
### Updated Classes
|
|
|
|
1. **TWP_Twilio_API**: Core API wrapper with SDK integration
|
|
2. **TWP_Webhooks**: All webhook handlers updated to use new TwiML builder
|
|
3. **TWP_Callback_Manager**: Outbound calling and callback management
|
|
4. **TWP_Workflow**: Call flow TwiML generation
|
|
5. **TWP_Agent_Manager**: Agent call routing
|
|
|
|
## Benefits
|
|
|
|
### With SDK Available
|
|
- **Better Error Handling**: Specific exception types for different error scenarios
|
|
- **Type Safety**: IDE support and parameter validation
|
|
- **Official Support**: Direct access to latest Twilio features
|
|
- **Reliability**: Built-in retry logic and rate limiting
|
|
- **Performance**: Optimized for high-volume operations
|
|
|
|
### Without SDK (Fallback)
|
|
- **No Dependencies**: Works on any PHP installation
|
|
- **Lightweight**: Minimal memory footprint
|
|
- **Compatibility**: Works with older PHP versions
|
|
- **Reliability**: Battle-tested custom implementation
|
|
|
|
## Supported PHP Versions
|
|
|
|
- **With SDK**: PHP 8.0+ (SDK v8.7.0 supports PHP 8.4)
|
|
- **Without SDK**: PHP 7.2+ (fallback implementation)
|
|
|
|
## Feature Support
|
|
|
|
### API Operations
|
|
- ✅ Make calls
|
|
- ✅ Send SMS
|
|
- ✅ Get call details
|
|
- ✅ Update active calls
|
|
- ✅ Manage phone numbers
|
|
- ✅ Search available numbers
|
|
- ✅ Purchase/release numbers
|
|
- ✅ Configure webhooks
|
|
|
|
### TwiML Generation
|
|
- ✅ Say (text-to-speech)
|
|
- ✅ Dial (with caller ID, timeout)
|
|
- ✅ Gather (digit collection with prompts)
|
|
- ✅ Enqueue (queue management)
|
|
- ✅ Record (voicemail recording)
|
|
- ✅ Redirect (call flow control)
|
|
- ✅ Hangup
|
|
|
|
### Advanced Features
|
|
- ✅ Webhook signature validation
|
|
- ✅ Conference calling
|
|
- ✅ Queue management
|
|
- ✅ Agent group routing
|
|
- ✅ Callback requests
|
|
- ✅ Voicemail transcription
|
|
|
|
## Testing
|
|
|
|
### Verifying SDK Installation
|
|
|
|
Check the admin dashboard or logs for:
|
|
```
|
|
TWP Plugin: Twilio SDK v8.7.0 loaded successfully
|
|
```
|
|
|
|
### API Testing
|
|
|
|
Use the plugin's test call feature to verify:
|
|
1. Outbound calling works
|
|
2. TwiML generation is valid
|
|
3. Webhooks receive proper responses
|
|
4. Error handling functions correctly
|
|
|
|
### Manual Testing
|
|
|
|
1. **Test Call Flow**: Make a test call to verify TwiML generation
|
|
2. **Webhook Testing**: Use Twilio's webhook debugger
|
|
3. **Error Scenarios**: Test invalid numbers, network failures
|
|
4. **Queue Operations**: Test agent groups and callbacks
|
|
|
|
## Troubleshooting
|
|
|
|
### SDK Not Loading
|
|
|
|
**Check autoloader exists:**
|
|
```bash
|
|
ls -la vendor/autoload.php
|
|
```
|
|
|
|
**Check SDK files:**
|
|
```bash
|
|
ls -la vendor/twilio/sdk/
|
|
```
|
|
|
|
**PHP Version:**
|
|
```bash
|
|
php -v # Should be 8.0+ for SDK support
|
|
```
|
|
|
|
### Common Issues
|
|
|
|
1. **"Class 'Twilio\Rest\Client' not found"**
|
|
- SDK not properly installed
|
|
- Run installation script again
|
|
|
|
2. **"Call to undefined method"**
|
|
- Fallback mode active
|
|
- Check SDK installation
|
|
- Verify PHP version compatibility
|
|
|
|
3. **"Permission denied" on installation script**
|
|
- Run: `chmod +x install-twilio-sdk.sh`
|
|
|
|
### Fallback Mode Indicators
|
|
|
|
The plugin uses fallback mode when:
|
|
- No `vendor/autoload.php` file
|
|
- Twilio classes not available
|
|
- SDK initialization fails
|
|
- PHP version incompatibility
|
|
|
|
## Migration Timeline
|
|
|
|
- ✅ **Phase 1**: Core API wrapper updated
|
|
- ✅ **Phase 2**: Webhook classes migrated
|
|
- ✅ **Phase 3**: TwiML generation unified
|
|
- ✅ **Phase 4**: Error handling improved
|
|
- ⏳ **Phase 5**: Testing and validation
|
|
- 📋 **Phase 6**: Documentation complete
|
|
|
|
## Rollback Plan
|
|
|
|
If issues arise, the plugin automatically falls back to the custom implementation. No manual intervention required.
|
|
|
|
To completely disable SDK usage:
|
|
1. Remove or rename `vendor/` directory
|
|
2. Plugin will automatically use fallback mode
|
|
|
|
## Support
|
|
|
|
For issues related to:
|
|
- **Plugin functionality**: Check WordPress error logs
|
|
- **Twilio API errors**: Check Twilio Console debugger
|
|
- **SDK-specific issues**: Refer to [Twilio PHP SDK documentation](https://www.twilio.com/docs/libraries/reference/twilio-php/)
|
|
|
|
## Resources
|
|
|
|
- [Twilio PHP SDK GitHub](https://github.com/twilio/twilio-php)
|
|
- [Twilio API Documentation](https://www.twilio.com/docs/usage/api)
|
|
- [TwiML Reference](https://www.twilio.com/docs/voice/twiml)
|
|
- [WordPress HTTP API](https://developer.wordpress.org/reference/classes/wp_http/) |