# 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 = ''; $twiml .= ''; $twiml .= 'Hello world'; $twiml .= ''; ``` ### 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/)