PHP 5 SOAP Extension Toolkit [AppExchange 7.0 API]

Instructions | API Docs | Apache Setup | PHP Setup | Unit Tests

Although this toolkit is aimed at developers who are already familiar with PHP, novices will also find it helpful in learning PHP and the salesforce API calls. The toolkit is based on PHP 5 and the included SOAP extension. PHP 5's SOAP extension being written in C has the advantage of being faster than other SOAP implementations written in PHP. This toolkit uses this extension to interface with the AppExchange API.

The toolkit supports the Partner WSDL only. You will have access to all the same objects and capabilities of the API from the Partner WSDL as you do from the Enterprise WSDL. There is no need to use the Enterprise WSDL

Included in this toolkit are the following directories:

In the soapclient directory, you will the SforcePartnerClient class which is used to make the connection and all method calls to the API. In order to create a connection, you first instantiate SforcePartnerClient and then pass in the WSDL. Once you have an instance of SforcePartnerClient, other AppExchange API method calls can be called directly on the instance. In this instance, you can login by calling login directly on $mySForceConnection. Browse the API doc to learn more about each available method call.

require_once ('soapclient/SforcePartnerClient.php');

$mySforceConnection = new SforcePartnerClient();
$mySoapClient = $mySforceConnection->createConnection("partner.wsdl.xml");
$mylogin = $mySforceConnection->login("username@mail.com", "changeme");

In the samples directory, you will find two samples, HelloWorld.php and a more in depth sample that handles login and session and can display, edit, and delete accounts. Instructions on how to run them can be found below. Additionally, a PHPUnit2 test class, SforcePartnerClientTest.php, is packaged with the example and has an example for each method call. See tests.html for information on how to run.

Results with SObjects

In the current PHP SOAP extension implementation, you will need to programmatically convert results that return sObjects. Each SObject has a fields array that will contain the fields selected during the query. For example,

...
$query = "SELECT Id, FirstName, LastName from Contact";
$queryResult = $mySforceConnection->query($query);
$records = $queryResult->records;
foreach ($records as $record) {
  $sObject = new SObject($record);
  echo "Id = ".$sObject->Id;
  echo "First Name = ".$sObject->fields->FirstName;
  echo "Last Name = ".$sObject->fields->LastName;
}

Note that the Id field is on the sObject and not part of the fields array due to the way that the current SOAP extension handles the Id field. This may change in the future.

SOAP Headers

The AppExchange API provides SOAP header options to client applications. All of these options are available in both the Enterprise and Partner WSDL files. To use these headers in an PHP client, simply include the following file:

require_once ('soapclient/SforceHeaderOptions.php');

This file contains three classes to handle AssignmentRuleHeader, MruHeader, and QueryOptions. SforcePartnerClientTest.php has examples of each.

Session Management

When a redirection occurs from one PHP page to another, the SOAP client must be reinstantiated for each page. In the first PHP page after a successful login, store the SessionID, endpoint, and WSDL reference in the session:

session_start();
$_SESSION['location'] = $mySforceConnection->getLocation();
$_SESSION['sessionId'] = $mySforceConnection->getSessionId();
$_SESSION['wsdl'] = $wsdl;

session_write_close();
header('Location: welcome.php');

On the second PHP page, reinstantiate the SOAP client by reusing the attributes that were stored in the session:

// Retrieve session attributes
session_start();
$location = $_SESSION['location'];
$sessionId = $_SESSION['sessionId'];
$wsdl = $_SESSION['wsdl'];


$mySforceConnection = new SforcePartnerClient();
$sforceSoapClient = $mySforceConnection->createConnection($wsdl);
$mySforceConnection->setEndpoint($location);
$mySforceConnection->setSessionHeader($sessionId);

SOAP COMPRESSION

Due to PHP Bug #36283, SOAP compression is turned off by default in SforceBaseClient. This bug should be fixed in the release after PHP 5.1.2. Once that happens, simply edit the createConnection($wsdl) method in SforceBaseClient.php to look as follows:

// Uncomment
$this->sforce = new SoapClient($wsdl, array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP));

// Comment out
// $this->sforce = new SoapClient($wsdl, array('trace' => 1));

Prerequisites

Before you execute the samples, please ensure that you have the following:

Build, Configure, and Deploy

Configure

Your PHP installation will need to have both SSL and SOAP enabled in order to use this toolkot. See PHP Setup for detailed instructions and tips.

Your web server will also need to be configured for PHP. For Apache, this means loading the php5_module and configuring an additional AddType. See Apache Setup for detailed instructions and tips.

A partner.wsdl.xml file is packaged with the toolkit. If for some reason you need a newer version you will need to obtain it from your ADN account. Log into your ADN account and access the setup area. Under 'Integrate' in the left-hand panel you will find the WSDL generator. Select 'Integrate' and then choose the Partner WSDL from the main window. Simply write over the existing partner.wsdl.xml that comes with this toolkit.

Deploy

Create a directory named "sforce-php" in the document root of your webserver. Copy the contents of this toolkit into this directory. See Apache Setup to locate or reconfigure the document root for Apache.

Before running, HelloWorld.php, simply edit sforce-php/samples/HelloWorld.php and replace username@mail.com and password with your ADN account username and password.

Run

To run HelloWorld.php, open a CMD window and navigate to the sforce-php directory and simply execute, "php HelloWorld.php". Be sure that you are using your ADN account username and password. Your expected output should be:

C:\Apache Group\Apache2\htdocs\sforce-php\samples> php HelloWorld.php
Nick Tran, your session id is Ng1.71derW7pIQ.Kp3Q6ccq.0jBiDpe4xFWexbAVl.7Ay1qDHN
BOuQGl0xA807xJ8P2W7ea0k6ldBfzTvFPMKmpYnKO9AsNCSeX5jsUoLXQ= 

To run the Account sample , navigate to http://localhost:[port]/sforce-php/samples/login.php where port is your http listen port. Login with your ADN account username and password. You should be presented with a table of Accounts which can be edited or deleted.

Tips / Troubleshooting

• If you run into problems with PHP header redirection in the Account sample, make sure that you have output_buffering = 4096 in your php.ini file.
• To view the SOAP headers and messages, simply call these methods on the connection.

  ...
  echo $mySforceConnection->getLastRequest;
  echo $mySforceConnection->getLastRequestHeaders;
  echo $mySforceConnection->getLastResponse;
  echo $mySforceConnection->getLastResponseHeaders;  

• Use the AppExchange Explorer to browse the schema and create and test SOQL queries.

Additional Reading

AppExchange API Calls

Support

AppExchange Developer Network

Special thanks to Park Walker who provided an initial example.