Merge branch 'main' into PHP8.4Take2

Author: tiwarishubham635

.github/workflows/test-and-deploy.yml

@@ -57,6 +57,12 @@ jobs:
           TWILIO_API_SECRET: ${{ secrets.TWILIO_CLUSTER_TEST_API_KEY_SECRET }}
           TWILIO_FROM_NUMBER: ${{ secrets.TWILIO_FROM_NUMBER }}
           TWILIO_TO_NUMBER: ${{ secrets.TWILIO_TO_NUMBER }}
+          TWILIO_ORGS_CLIENT_ID: ${{ secrets.TWILIO_ORGS_CLIENT_ID }}
+          TWILIO_ORGS_CLIENT_SECRET: ${{ secrets.TWILIO_ORGS_CLIENT_SECRET }}
+          TWILIO_ORG_SID: ${{ secrets.TWILIO_ORG_SID }}
+          TWILIO_CLIENT_ID: ${{ secrets.TWILIO_CLIENT_ID }}
+          TWILIO_CLIENT_SECRET: ${{ secrets.TWILIO_CLIENT_SECRET }}
+          TWILIO_MESSAGE_SID: ${{ secrets.TWILIO_MESSAGE_SID }}
         run: make cluster-test
 
       - name: Install SonarCloud scanner and run analysis

CHANGES.md

@@ -1,6 +1,18 @@
 twilio-php Changelog
 ====================
 
+[2025-04-07] Version 8.5.0
+--------------------------
+**Library - Docs**
+- [PR #862](https://github.com/twilio/twilio-php/pull/862): update readme for oauth feature. Thanks to [@tiwarishubham635](https://github.com/tiwarishubham635)!
+
+**Library - Feature**
+- [PR #854](https://github.com/twilio/twilio-php/pull/854): merge OAuth support into main. Thanks to [@manisha1997](https://github.com/manisha1997)!
+
+**Studio**
+- Add documentation for parent_step_sid field in Step resource
+
+
 [2025-03-20] Version 8.4.1
 --------------------------
 **Library - Chore**

README.md

@@ -96,6 +96,13 @@ $client->messages->create(
 );
 ```
 
+## OAuth Feature for Twilio APIs
+We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.
+
+API examples [here](https://github.com/twilio/twilio-php/blob/main/example/public_oauth_example.php)
+
+Organisation API examples [here](https://github.com/twilio/twilio-php/blob/main/example/orgs_api_example.php)
+
 ## Usage
 
 ### Make a Call

example/orgs_api_example.php

@@ -0,0 +1,20 @@
+<?php
+require(__DIR__.'/../src/Twilio/autoload.php');
+
+use Twilio\Rest\Client;
+use Twilio\CredentialProvider\OrgsCredentialProviderBuilder;
+
+$clientId = getenv('ORGS_CLIENT_ID');
+$clientSecret = getenv('ORGS_CLIENT_SECRET');
+$orgSid = getenv('ORG_SID');
+
+$orgsCredentialProvider = (new OrgsCredentialProviderBuilder())->setClientId($clientId)->setClientSecret($clientSecret)->build();
+
+$client = new Client();
+$client->setCredentialProvider($orgsCredentialProvider);
+
+//list users
+$users = $client->previewIam->organization($orgSid)->users->read();
+foreach ($users as $user) {
+    printf("User SID: %s\n", $user->id);
+}

example/public_oauth_example.php

@@ -0,0 +1,22 @@
+<?php
+require(__DIR__.'/../src/Twilio/autoload.php');
+
+use Twilio\Rest\Client;
+use Twilio\CredentialProvider\ClientCredentialProviderBuilder;
+
+$accountSid = getenv('TWILIO_ACCOUNT_SID');
+$token = getenv('TWILIO_AUTH_TOKEN');
+
+$clientId = getenv('OAUTH_CLIENT_ID');
+$clientSecret = getenv('OAUTH_CLIENT_SECRET');
+
+$clientCredentialProvider = (new ClientCredentialProviderBuilder())->setClientId($clientId)->setClientSecret($clientSecret)->build();
+
+$client = new Client();
+$client->setCredentialProvider($clientCredentialProvider);
+$client->setAccountSid($accountSid);
+
+$messageList = $client->messages->read([],10);
+foreach ($messageList as $msg) {
+    print("ID:: ". $msg->sid . " | " . "From:: " . $msg->from . " | " . "TO:: " . $msg->to . " | "  .  " Status:: " . $msg->status . " | " . " Body:: ". $msg->body ."\n");
+}

src/Twilio/AuthStrategy/AuthStrategy.php

@@ -0,0 +1,27 @@
+<?php
+namespace Twilio\AuthStrategy;
+
+/**
+ * Class AuthStrategy
+ * Abstract parent class for all authentication strategies - Basic, Bearer Token, NoAuth etc.
+ * @property string $authType The type of authentication strategy
+ */
+
+abstract class AuthStrategy {
+    private $authType;
+
+    public function __construct(string $authType) {
+        $this->authType = $authType;
+    }
+
+    public function getAuthType(): string {
+        return $this->authType;
+    }
+
+    /**
+     * Returns the value to be set in the authentication header
+     *
+     * @return string the authentication string
+     */
+    abstract public function getAuthString(): string;
+}

src/Twilio/AuthStrategy/BasicAuthStrategy.php

@@ -0,0 +1,29 @@
+<?php
+namespace Twilio\AuthStrategy;
+
+/**
+ * Class BasicAuthStrategy
+ * Implementation of the AuthStrategy for Basic authentication
+ * @property string $username
+ * @property string $password
+ */
+
+class BasicAuthStrategy extends AuthStrategy {
+    private $username;
+    private $password;
+
+    public function __construct(string $username, string $password) {
+        parent::__construct("basic");
+        $this->username = $username;
+        $this->password = $password;
+    }
+
+    /**
+     * Returns the base64 encoded string concatenating the username and password
+     *
+     * @return string the base64 encoded string
+     */
+    public function getAuthString(): string {
+        return base64_encode($this->username . ':' . $this->password);
+    }
+}

src/Twilio/AuthStrategy/NoAuthStrategy.php

@@ -0,0 +1,23 @@
+<?php
+namespace Twilio\AuthStrategy;
+
+/**
+ * Class NoAuthStrategy
+ * Implementation of the AuthStrategy for No Authentication
+ */
+
+class NoAuthStrategy extends AuthStrategy {
+
+    public function __construct() {
+        parent::__construct("noauth");
+    }
+
+    /**
+     * Returns an empty string since no authentication is required
+     *
+     * @return string an empty string
+     */
+    public function getAuthString(): string {
+        return "";
+    }
+}

src/Twilio/AuthStrategy/TokenAuthStrategy.php

@@ -0,0 +1,69 @@
+<?php
+namespace Twilio\AuthStrategy;
+
+use Twilio\Rest\Client;
+use Twilio\Http\BearerToken\TokenManager;
+/**
+ * Class TokenAuthStrategy
+ * Implementation of the AuthStrategy for Bearer Token Authentication
+ * @property string $token The bearer token
+ * @property TokenManager $tokenManager The manager for the bearer token
+ */
+
+class TokenAuthStrategy extends AuthStrategy {
+    private $token;
+    private $tokenManager;
+
+    public function __construct(TokenManager $tokenManager) {
+        parent::__construct("token");
+        $this->tokenManager = $tokenManager;
+    }
+
+    /**
+     * Checks if the token is expired or not
+     *
+     * @param string $token the token to be checked
+     *
+     * @return bool whether the token is expired or not
+     */
+    public function isTokenExpired(string $token): bool {
+        // Decode the JWT token
+        $decodedToken = json_decode(base64_decode(str_replace('_', '/', str_replace('-','+',explode('.', $token)[1]))), true);
+
+        $expireField = $decodedToken['exp'];
+
+        // If the token doesn't have an expiration, consider it expired
+        if ($decodedToken === null || $expireField === null) {
+            return false;
+        }
+
+        // Calculate the expiration time with a buffer of 30 seconds
+        $expiresAt = $expireField * 1000;
+        $bufferMilliseconds = 30 * 1000;
+        $bufferExpiresAt = $expiresAt - $bufferMilliseconds;
+
+        // Return true if the current time is after the expiration time with buffer
+        return round(microtime(true)*1000) > $bufferExpiresAt;
+    }
+
+    /**
+     * Fetches the bearer token
+     *
+     * @return string the bearer token
+     */
+    public function fetchToken(?Client $client = null): string {
+        if (empty($this->token) || $this->isTokenExpired($this->token)) {
+            $this->token = $this->tokenManager->fetchToken($client);
+        }
+        return $this->token;
+    }
+
+    /**
+     * Returns the bearer token authentication string
+     *
+     * @return string the bearer token authentication string
+     */
+    public function getAuthString(?Client $client = null): string {
+        return "Bearer " . $this->fetchToken($client);
+    }
+}

src/Twilio/Base/BaseClient.php

@@ -1,6 +1,8 @@
 <?php
 namespace Twilio\Base;
 
+use Twilio\AuthStrategy\AuthStrategy;
+use Twilio\CredentialProvider\CredentialProvider;
 use Twilio\Exceptions\ConfigurationException;
 use Twilio\Exceptions\TwilioException;
 use Twilio\Http\Client as HttpClient;
@@ -24,6 +26,7 @@ class BaseClient
 
     protected $username;
     protected $password;
+    protected $credentialProvider;
     protected $accountSid;
     protected $region;
     protected $edge;
@@ -46,7 +49,6 @@ class BaseClient
      * @param mixed[] $environment Environment to look for auth details, defaults
      *                             to $_ENV
      * @param string[] $userAgentExtensions Additions to the user agent string
-     * @throws ConfigurationException If valid authentication is not present
      */
     public function __construct(
         ?string $username = null,
@@ -59,18 +61,15 @@ public function __construct(
     ) {
         $this->environment = $environment ?: \getenv();
 
-        $this->username = $this->getArg($username, self::ENV_ACCOUNT_SID);
-        $this->password = $this->getArg($password, self::ENV_AUTH_TOKEN);
+        $this->setUsername($this->getArg($username, self::ENV_ACCOUNT_SID));
+        $this->setPassword($this->getArg($password, self::ENV_AUTH_TOKEN));
         $this->region = $this->getArg($region, self::ENV_REGION);
         $this->edge = $this->getArg(null, self::ENV_EDGE);
         $this->logLevel = $this->getArg(null, self::ENV_LOG);
         $this->userAgentExtensions = $userAgentExtensions ?: [];
 
-        if (!$this->username || !$this->password) {
-            throw new ConfigurationException('Credentials are required to create a Client');
-        }
-
-        $this->accountSid = $accountSid ?: $this->username;
+        $this->invalidateOAuth();
+        $this->setAccountSid($accountSid ?: $this->username);
 
         if ($httpClient) {
             $this->httpClient = $httpClient;
@@ -79,6 +78,36 @@ public function __construct(
         }
     }
 
+    public function setUsername(?string $username): void {
+        $this->username = $username;
+    }
+
+    public function setPassword(?string $password): void {
+        $this->password = $password;
+    }
+
+    public function setAccountSid(?string $accountSid): void {
+        $this->accountSid = $accountSid;
+    }
+
+    private function _setCredentialProvider($credentialProvider): void {
+        $this->credentialProvider = $credentialProvider;
+    }
+
+    public function setCredentialProvider(CredentialProvider $credentialProvider): void {
+        $this->_setCredentialProvider($credentialProvider);
+        $this->invalidateBasicAuth();
+    }
+
+    public function invalidateBasicAuth(): void {
+        $this->setUsername("");
+        $this->setPassword("");
+    }
+
+    public function invalidateOAuth(): void {
+        $this->_setCredentialProvider(null);
+    }
+
     /**
      * Determines argument value accounting for environment variables.
      *
@@ -111,7 +140,9 @@ public function getArg(?string $arg, string $envVar): ?string
      * @param string $username User for Authentication
      * @param string $password Password for Authentication
      * @param int $timeout Timeout in seconds
+     * @param AuthStrategy $authStrategy AuthStrategy for Authentication
      * @return \Twilio\Http\Response Response from the Twilio API
+     * @throws TwilioException
      */
     public function request(
         string $method,
@@ -121,10 +152,26 @@ public function request(
         array $headers = [],
         ?string $username = null,
         ?string $password = null,
-        ?int $timeout = null
+        ?int $timeout = null,
+        ?AuthStrategy $authStrategy = null
     ): \Twilio\Http\Response{
         $username = $username ?: $this->username;
         $password = $password ?: $this->password;
+        $authStrategy = $authStrategy ?: null;
+        if ($this->credentialProvider) {
+            $authStrategy = $this->credentialProvider->toAuthStrategy();
+        }
+
+        if (!$authStrategy) {
+            if (!$username) {
+                throw new ConfigurationException('username is required');
+            }
+
+            if (!$password) {
+                throw new ConfigurationException("password is required");
+            }
+        }
+
         $logLevel = (getenv('DEBUG_HTTP_TRAFFIC') === 'true' ? 'debug' : $this->getLogLevel());
 
         $headers['User-Agent'] = 'twilio-php/' . VersionInfo::string() .
@@ -136,7 +183,8 @@ public function request(
             $headers['User-Agent'] .= ' ' . implode(' ', $this->userAgentExtensions);
         }
 
-        if (!\array_key_exists('Accept', $headers)) {
+        // skip adding Accept header in case of delete operation
+        if ($method !== "DELETE" && !\array_key_exists('Accept', $headers)) {
             $headers['Accept'] = 'application/json';
         }
 
@@ -169,7 +217,8 @@ public function request(
             $headers,
             $username,
             $password,
-            $timeout
+            $timeout,
+            $authStrategy
         );
 
         if ($logLevel === 'debug') {