Web services with Salesforce.com using soap

https://developer.salesforce.com/page/Getting_Started_with_the_Force.com_Toolkit_for_PHP

Installing the Toolkit

Clone the PHP Toolkit code from Github with

1 git clone https://github.com/developerforce/Force.com-Toolkit-for-PHP.git

If the command above does not work, download it from https://github.com/developerforce/Force.com-Toolkit-for-PHPinstead.

Copy the soapclient directory to your PHP application’s directory – for a web application this will typically be in the web server document tree, for example /var/www/html/myphpapp.

Creating a Connection

The first step to using the PHP Toolkit is to create a connection using either SforceEnterpriseClient or SforcePartnerClient. In both cases, you must ensure that your user has API access enabled (Setup|Manage Users|Users|Select your user|Click the user’s profile|Administrative Permissions), and concatenate the password with the security token to form the second argument for the login method. Note – in this, and the other code fragments presented in this guide, error handling is omitted for clarity. The sample code includes basic error handling.

Enterprise

1 define("USERNAME", "user@example.com");
2 define("PASSWORD", "password");
3 define("SECURITY_TOKEN", "sdfhkjwrhgfwrgergp");
4
5 require_once ('soapclient/SforceEnterpriseClient.php');
6
7 $mySforceConnection = new SforceEnterpriseClient();
8 $mySforceConnection->createConnection("enterprise.wsdl.xml");
9 $mySforceConnection->login(USERNAME, PASSWORD.SECURITY_TOKEN);

Partner

1 define("USERNAME", "user@example.com");
2 define("PASSWORD", "password");
3 define("SECURITY_TOKEN", "sdfhkjwrhgfwrgergp");
4
5 require_once ('soapclient/SforcePartnerClient.php');
6
7 $mySforceConnection = new SforcePartnerClient();
8 $mySforceConnection->createConnection("partner.wsdl.xml");
9 $mySforceConnection->login(USERNAME, PASSWORD.SECURITY_TOKEN);

Executing a Query

Executing a SOQL query is straightforward with either client; the only difference are that, with the partner client, you must create a QueryResult from the query response, use it to iterate through the results, and access the fields via an intermediatefields object:

Enterprise

1 $query = "SELECT Id, FirstName, LastName, Phone from Contact";
2 $response = $mySforceConnection->query($query);
3
4 echo "Results of query '$query'<br/><br/>\n";
5 foreach ($response->records as $record) {
6     echo $record->Id . ": " . $record->FirstName . " "
7         . $record->LastName . " " . $record->Phone . "<br/>\n";
8 }

Partner

01 $query = "SELECT Id, FirstName, LastName, Phone from Contact";
02 $response = $mySforceConnection->query($query);
03 $queryResult = new QueryResult($response);
04
05 echo "Results of query '$query'<br/><br/>\n";
06 for ($queryResult->rewind(); $queryResult->pointer < $queryResult->size; $queryResult->next()) {
07     $record = $queryResult->current();
08     // Id is on the $record, but other fields are accessed via
09     // the fields object
10     echo $record->Id.": ".$record->fields->FirstName." "
11             .$record->fields->LastName." "
12             .$record->fields->Phone."<br/>\n";
13 }

Creating Records

The enterprise client’s create method accepts an array of generic PHP objects and their type, where PHP object properties correspond to record fields. The create method returns an array containing the result for each record creation:

Enterprise

01 $records = array();
02
03 $records[0] = new stdclass();
04 $records[0]->FirstName = 'John';
05 $records[0]->LastName = 'Smith';
06 $records[0]->Phone = '(510) 555-5555';
07 $records[0]->BirthDate = '1957-01-25';
08
09 $records[1] = new stdclass();
10 $records[1]->FirstName = 'Mary';
11 $records[1]->LastName = 'Jones';
12 $records[1]->Phone = '(510) 486-9969';
13 $records[1]->BirthDate = '1977-01-25';
14
15 $response = $mySforceConnection->create($records, 'Contact');
16
17 $ids = array();
18 foreach ($response as $i => $result) {
19     echo $records[$i]->FirstName . " " . $records[$i]->LastName . " "
20             . $records[$i]->Phone . " created with id " . $result->id
21             . "<br/>\n";
22     array_push($ids, $result->id);
23 }

In contrast, the partner client’s create method takes an array of SObjects, where each SObject contains an array of fields and has its type set individually:

Partner

01 $records = array();
02
03 $records[0] = new SObject();
04 $records[0]->fields = array(
05     'FirstName' => 'John',
06     'LastName' => 'Smith',
07     'Phone' => '(510) 555-5555',
08     'BirthDate' => '1957-01-25'
09 );
10 $records[0]->type = 'Contact';
11
12 $records[1] = new SObject();
13 $records[1]->fields = array(
14     'FirstName' => 'Mary',
15     'LastName' => 'Jones',
16     'Phone' => '(510) 486-9969',
17     'BirthDate' => '1977-01-25'
18 );
19 $records[1]->type = 'Contact';
20
21 $response = $mySforceConnection->create($records);
22
23 $ids = array();
24 foreach ($response as $i => $result) {
25     echo $records[$i]->fields["FirstName"] . " "
26             . $records[$i]->fields["LastName"] . " "
27             . $records[$i]->fields["Phone"] . " created with id "
28             . $result->id . "<br/>\n";
29     array_push($ids, $result->id);
30 }

Retrieving Records

The retrieve method works similarly for the enterprise and partner clients, taking a list of required fields, the record type, and an array of record id’s. The only difference between the clients is that records returned by the partner client have a fieldsobject containing the fields themselves:

Enterprise

1 // $ids is an array of record ids built in the previous step
2 $response = $mySforceConnection->retrieve('Id, FirstName, LastName, Phone',
3                 'Contact', $ids);
4 foreach ($response as $record) {
5     echo $record->Id . ": " . $record->FirstName . " "
6     . $record->LastName . " " . $record->Phone . "<br/>\n";
7 }

Partner

1 // $ids is an array of record ids built in the previous step
2 $response = $mySforceConnection->retrieve('Id, FirstName, LastName, Phone',
3                 'Contact', $ids);
4 foreach ($response as $record) {
5     echo $record->Id . ": " . $record->fields->FirstName . " "
6     . $record->fields->LastName . " " . $record->fields->Phone . "<br/>\n";
7 }

Updating Records

The update method is very similar to the create method for both clients; simply supply the fields to be updated:

Enterprise

01 $records[0] = new stdclass();
02 $records[0]->Id = $ids[0];
03 $records[0]->Phone = '(415) 555-5555';
04
05 $records[1] = new stdclass();
06 $records[1]->Id = $ids[1];
07 $records[1]->Phone = '(415) 486-9969';
08
09 $response = $mySforceConnection->update($records, 'Contact');
10 foreach ($response as $result) {
11     echo $result->id . " updated<br/>\n";
12 }

Partner

01 $records[0] = new SObject();
02 $records[0]->Id = $ids[0];
03 $records[0]->fields = array(
04     'Phone' => '(415) 555-5555',
05 );
06 $records[0]->type = 'Contact';
07
08 $records[1] = new SObject();
09 $records[1]->Id = $ids[0];
10 $records[1]->fields = array(
11     'Phone' => '(415) 486-9969',
12 );
13 $records[1]->type = 'Contact';
14
15 $response = $mySforceConnection->update($records);
16 foreach ($response as $result) {
17     echo $result->id . " updated<br/>\n";
18 }

Note that, due to the way that serialization works, setting a field to null will leave the field in place as an empty string (“”). To actually remove a field from a record, setting it to null in the database, use the fieldsToNull property as follows:

Enterprise

1 $records[0] = new stdclass();
2 $records[0]->Id = $ids[0];
3 $records[0]->fieldsToNull = 'Phone';
4
5 $records[1] = new stdclass();
6 $records[1]->Id = $ids[1];
7 $records[1]->fieldsToNull = 'Phone';
8
9 $response = $mySforceConnection->update($records, 'Contact');

Partner

01 $records[0] = new SObject();
02 $records[0]->Id = $ids[0];
03 $records[0]->fieldsToNull = 'Phone';
04 $records[0]->type = 'Contact';
05
06 $records[1] = new SObject();
07 $records[1]->Id = $ids[1];
08 $records[1]->fieldsToNull = 'Phone';
09 $records[1]->type = 'Contact';
10
11 $response = $mySforceConnection->update($records);

If you wish to remove multiple fields, pass an array in the fieldsToNull property:

1 $records[0]->fieldsToNull = array('Phone', 'Fax');

Deleting Records

The delete method takes an array of record id’s; the enterprise and partner clients implement it identically:

Enterprise/Partner

1 // $ids is an array of record ids built in a previous step
2 $response = $mySforceConnection->delete($ids);
3 foreach ($response as $result) {
4     echo $result->id . " deleted<br/>\n";
5 }

Session Management

When the user navigates from one PHP page to another, the SOAP client must be re-instantiated for each page. In the first PHP page after a successful login, store the Session ID, endpoint, and WSDL reference in the session:

1 // session_start() usually goes at the beginning of the PHP script
2 session_start();
3
4 // [Code to create the connection...]
5
6 // Now we can save the connection info for the next page
7 $_SESSION['location'] = $mySforceConnection->getLocation();
8 $_SESSION['sessionId'] = $mySforceConnection->getSessionId();
9 $_SESSION['wsdl'] = $wsdl;

On subsequent PHP pages, re-instantiate the SOAP client by retrieving the attributes that were stored in the session:

01 session_start();
02
03 // Retrieve session attributes
04 $location = $_SESSION['location'];
05 $sessionId = $_SESSION['sessionId'];
06 $wsdl = $_SESSION['wsdl'];
07
08 // Use SforceEnterpriseClient or SforcePartnerClient as appropriate
09 $mySforceConnection = new SforceEnterpriseClient();
10 $mySforceConnection->createConnection($wsdl);
11 $mySforceConnection->setEndpoint($location);
12 $mySforceConnection->setSessionHeader($sessionId);
13
14 // Now the connection is ready for use...
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s