Live Push: Add OAuth SOAP session support for API v67. 2026-06-21

README.md

@@ -4,3 +4,14 @@ The Force.com PHP Toolkit provides an easy-to-use wrapper for the Force.com Web
 
 See the [getting started guide](http://wiki.developerforce.com/index.php/Getting_Started_with_the_Force.com_Toolkit_for_PHP) for sample code to create, retrieve, update and delete records in the Force.com database.
 
+## OAuth SOAP sessions
+
+After obtaining an OAuth access token, create the SOAP connection with a Partner WSDL and call `setOAuthSession()` instead of `login()`:
+
+```php
+$client = new \Justia\SalesforcePhpSdk\SforcePartnerClient();
+$client->createConnection(__DIR__ . '/wsdl/partner-v67.wsdl.xml');
+$client->setOAuthSession($accessToken, $instanceUrl, '67.0');
+```
+
+`$instanceUrl` must be the HTTPS `instance_url` returned by Salesforce's OAuth token response. The bundled `wsdl/partner-v67.wsdl.xml` is the production-org Partner WSDL generated for API 67.0. The method sets the SOAP `SessionHeader` to the access token and changes the endpoint to `/services/Soap/u/67.0`; it does not call the legacy SOAP `login()` operation. Existing `login()` consumers remain supported.

src/Justia/SalesforcePhpSdk/SforceBaseClient.php

@@ -230,6 +230,50 @@ public function setEndpoint($location)
         $this->sforce->__setLocation($location);
     }
 
+    /**
+     * Starts a SOAP session with an OAuth access token instead of the SOAP
+     * login operation.
+     *
+     * The caller must create the SOAP connection before calling this method.
+     * Salesforce returns instance_url with OAuth token responses, which is used
+     * to build the versioned SOAP endpoint.
+     *
+     * @param string $accessToken OAuth access token
+     * @param string $instanceUrl Salesforce instance URL from the OAuth response
+     * @param string $apiVersion SOAP API version
+     * @param string $endpointType SOAP endpoint type, usually u for Partner API
+     * @return string SOAP endpoint
+     */
+    public function setOAuthSession($accessToken, $instanceUrl, $apiVersion = '67.0', $endpointType = 'u')
+    {
+        if (!$this->sforce) {
+            throw new Exception('Create a SOAP connection before setting an OAuth session.');
+        }
+
+        if (!is_string($accessToken) || trim($accessToken) === '') {
+            throw new Exception('An OAuth access token is required.');
+        }
+
+        if (!is_string($instanceUrl) || !preg_match('#^https://[^/]+/?$#i', $instanceUrl)) {
+            throw new Exception('A valid HTTPS Salesforce instance URL is required.');
+        }
+
+        if (!is_string($apiVersion) || !preg_match('/^[0-9]+\.[0-9]+$/', $apiVersion)) {
+            throw new Exception('A Salesforce SOAP API version in major.minor format is required.');
+        }
+
+        if (!is_string($endpointType) || !preg_match('/^[a-z]+$/i', $endpointType)) {
+            throw new Exception('A valid Salesforce SOAP endpoint type is required.');
+        }
+
+        $endpoint = rtrim($instanceUrl, '/') . '/services/Soap/' . strtolower($endpointType) . '/' . $apiVersion;
+
+        $this->setSessionHeader($accessToken);
+        $this->setEndpoint($endpoint);
+
+        return $endpoint;
+    }
+
     private function setHeaders($call = null)
     {
         $this->sforce->__setSoapHeaders(null);

tests/oauth-session-test.php

@@ -0,0 +1,47 @@
+<?php
+
+require dirname(__DIR__) . '/src/Justia/SalesforcePhpSdk/SforceBaseClient.php';
+
+class OAuthSessionTestSoapClient
+{
+    public $location;
+
+    public function __setLocation($location)
+    {
+        $this->location = $location;
+    }
+}
+
+class OAuthSessionTestClient extends \Justia\SalesforcePhpSdk\SforceBaseClient
+{
+    public function useSoapClient($client)
+    {
+        $this->sforce = $client;
+        $this->namespace = 'urn:partner.soap.sforce.com';
+    }
+
+    public function sessionIdForTest()
+    {
+        return $this->sessionId;
+    }
+}
+
+function oauthSessionAssertSame($expected, $actual, $message)
+{
+    if ($expected !== $actual) {
+        fwrite(STDERR, $message . PHP_EOL);
+        exit(1);
+    }
+}
+
+$soapClient = new OAuthSessionTestSoapClient();
+$client = new OAuthSessionTestClient();
+$client->useSoapClient($soapClient);
+
+$endpoint = $client->setOAuthSession('access-token', 'https://justia.my.salesforce.com/', '67.0');
+
+oauthSessionAssertSame('https://justia.my.salesforce.com/services/Soap/u/67.0', $endpoint, 'OAuth endpoint was not derived correctly.');
+oauthSessionAssertSame($endpoint, $soapClient->location, 'SOAP client location was not updated.');
+oauthSessionAssertSame('access-token', $client->sessionIdForTest(), 'OAuth token was not set as the session id.');
+
+echo "OAuth session test passed.\n";