Summary

This PR enhances the LOX24RequestParser to provide robust SMS delivery webhook parsing with improved validation, dual status code support (DLR codes and status codes), and better error handling for SMS delivery events.

What it does

Before: The parser had basic SMS delivery webhook handling with limited validation and error handling.

After: The parser provides enhanced SMS delivery webhook processing:

• sms.delivery &sms.delivery.dryrun - SMS delivery receipts with improved validation
• Dual status code support: DLR codes (0-16) and transmission status codes (0, 100, etc.)
• Better payload validation with detailed error messages
• Non-delivery events are handled as generic RemoteEvent objects

Example Usage

Enhanced SMS Delivery Processing:

// ✅ SMS delivery with status code$deliveryPayload = ['id' =>'webhook-123','name' =>'sms.delivery','data' => ['id' =>'123','status_code' =>100]];$deliveryEvent =$parser->parse($deliveryRequest,$secret);// Returns: SmsEvent with DELIVERED status// ✅ SMS delivery with DLR code (takes priority over status_code)$dlrPayload = ['id' =>'webhook-456','name' =>'sms.delivery','data' => ['id' =>'456','dlr_code' =>1,'status_code' =>500]];$dlrEvent =$parser->parse($dlrRequest,$secret);// Returns: SmsEvent with DELIVERED status (DLR code 1 overrides status 500)// ✅ Pending delivery (returns null)$pendingPayload = ['id' =>'webhook-789','name' =>'sms.delivery','data' => ['id' =>'789','dlr_code' =>0]];$pendingEvent =$parser->parse($pendingRequest,$secret);// Returns: null (pending delivery)// ✅ Non-delivery events handled as RemoteEvent$otherPayload = ['id' =>'webhook-000','name' =>'custom.event','data' => ['some' =>'data']];$otherEvent =$parser->parse($otherRequest,$secret);// Returns: RemoteEvent with 'custom.event' name

Key Changes

1.Improved Payload Validation

• Enhanced validation for required webhook fields:id,name,data
• Better error messages with specific missing field details
• Proper array validation for data payload

2.Smart Return Types

• SMS delivery events (sms.delivery,sms.delivery.dryrun) returnSmsEvent objects with DELIVERED/FAILED status
• Non-delivery events returnRemoteEvent objects for generic webhook handling
• Maintainsnull return for pending deliveries (status_code=0 or dlr_code=0/2/4)

3.Enhanced SMS Delivery Validation

// SMS delivery events validate required fieldscase'sms.delivery':// Requires: payload.id, data.id, and either data.status_code OR data.dlr_code// Supports both LOX24 status codes and DLR codes// DLR codes take priority when both are present

4.Dual Status Code Support

• DLR Codes: Priority support for LOX24's Delivery Report codes (0-16) with proper pending state handling
• Status Codes: Fallback to transmission status codes (0, 100, 208, 400, etc.) when DLR unavailable
• Smart Mapping: DLR codes 1→DELIVERED, 8/16→FAILED, 0/2/4→null (pending)

4.Comprehensive Testing

• Tests for SMS delivery events with success/failure scenarios
• DLR code and status code validation scenarios
• Payload validation tests for required fields
• Backward compatibility verification for existing delivery events
• Type safety assertions (SmsEvent vsRemoteEvent)

Backward Compatibility

✅Fully backward compatible - existing consumers continue working without changes:

• Samesms.delivery event handling behavior
• Same status code and DLR code mapping logic
• Same null return for pending messages (status_code=0, dlr_code=0/2/4)
• Same SmsEvent object structure and methods
• Enhanced support for both LOX24 status codes and DLR codes

Consumer Integration Example

#[AsRemoteEventConsumer('lox24_notifier')]class LOX24WebhookConsumerimplements ConsumerInterface{publicfunctionconsume(RemoteEvent$event):void    {if ($eventinstanceof SmsEvent) {match($event->getName()) {                SmsEvent::DELIVERED =>$this->handleDelivered($event),                SmsEvent::FAILED =>$this->handleFailed($event),            };        }else {// Handle other webhook events as generic RemoteEvent$this->handleGenericWebhook($event);        }    }}

Breaking Changes

⚠️Minor breaking changes (unlikely to affect most users):

• Parser return type signature changed from?SmsEvent toSmsEvent|RemoteEvent|null
• Exception messages updated with more detailed validation errors
• Requires webhook payload to includeid field (LOX24 standard)
• Non-delivery events now returnRemoteEvent instead of being rejected

Technical Implementation

• Improved Validation: Enhanced payload validation with detailed error messages for missing fields
• Factory Methods: Implemented specialized methods (createDeliveryEvent,createRemoteEvent, etc.)
• Dual Code Support: Enhanced delivery event parsing to handle both LOX24 status codes and DLR codes
• Smart Precedence: DLR codes take priority over status codes when both are present
• Error Handling: Enhanced error messages with specific validation details
• Null Handling: Proper handling of pending states (DLR codes 0/2/4, status code 0)

Testing

• ✅ All existing tests pass (backward compatibility)
• ✅ Added comprehensive test coverage for SMS delivery scenarios
• ✅ Payload validation and error handling tests
• ✅ DLR code and status code priority testing

This enhancement improves LOX24 SMS delivery webhook processing with better validation, dual status code support, and robust error handling while maintaining complete backward compatibility.