twilio / twilio-php

A PHP library for communicating with the Twilio REST API and generating TwiML.
MIT License
1.57k stars 562 forks source link

`InstanceResource` properties are `camelCase`, leading to confusion against `snake_case` API documentation #743

Open stevebauman opened 2 years ago

stevebauman commented 2 years ago

The Twilio API documentation shows PHP examples with return structures containing properties that are snake_case:

https://www.twilio.com/docs/usage/api/applications

{
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "2010-04-01",
  "date_created": "Mon, 22 Aug 2011 20:59:45 +0000",
  "date_updated": "Tue, 18 Aug 2015 16:48:57 +0000",
  "friendly_name": "Phone Me",
  "message_status_callback": "http://www.example.com/sms-status-callback",
}

Yet these properties are transformed into camelCase, leading to confusion when transforming these instances ->toArray() and expecting the same response that the API documentation displays:

https://github.com/twilio/twilio-php/blob/10c7f8b6f4719c23c6e90c9b2e28ebdb735aea48/src/Twilio/Rest/Api/V2010/Account/ApplicationInstance.php#L54-L60

// [
//     "accountSid" => "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
//     "apiVersion" => "2010-04-01",
//     "dateCreated" => "Mon, 22 Aug 2011 20:59:45 +0000",
//     "dateUpdated" => "Tue, 18 Aug 2015 16:48:57 +0000",
//     "friendlyName" => "Phone Me",
//     "messageStatusCallback" => "http://www.example.com/sms-status-callback",
// ]
$application->toArray()

Since the InstanceResource classes already use a magic __get(), could we preserve the structure of the API response in $properties and then snake the requested $property?

public function __get($property)
{
    $property = strtolower(preg_replace('/(.)(?=[A-Z])/u', '$1_', $property));

    return $this->properties[$property] ?? null;
}

This would also remove the need to parse the payload and camelCase all of their properties manually (even though this is automated via your API generation tool).

Thanks for your time!

rakatyal commented 2 years ago

This issue has been added to our internal backlog to be prioritized. Pull requests and +1s on the issue summary will help it move up the backlog.