PHP and Salesforce

Here is part three of the series documenting the Salesforce API when used with the PHP Toolkit, where we’re going to cover the method calls under the ‘Describe Calls’ section of the API documentation. Note that this post applies to both the Enterprise and Partner WSDL formats.

Prerequisites
All examples below assume the Toolkit has been instantiated and the connection has been made:

Enterprise WSDL
$crmHandle = new SforceEnterpriseClient();
$crmHandle->createConnection(‘/path/to/enterprise.wsdl.xml’);

Partner WSDL
$crmHandle = new SforcePartnerClient();
$crmHandle->createConnection(’/path/to/partner.wsdl.xml’);

Additionally, all examples except login() assume you are logged in, using a call such as
$crmHandle->login(‘joe@example.com.sbox1′, ‘*passwordhere*’ . ‘*securitytokenhere*’);

Variable Names

• $crmHandle – reference to an instance of the Toolkit object
• $result – the result of a Salesforce method call

Notes
Date formats are in the SOAP dateTime format (ISO 8601), e.g. ‘2009-06-01T23:01:01Z’.

If you see an error like ‘INVALID_TYPE: Must send a concrete entity type’, most likely, you have forgotten to wrap your object in an array before passing it to a method.

describeGlobal()

$result = $crmHandle->describeGlobal();

describeLayout()

$result = $crmHandle->describeLayout('Lead', '*A VALID LEAD ID HERE*');

describeSObject()
NOTE: This method call is deprecated in favor of describeSObjects().

$result = $crmHandle->describeSObject('Lead');

describeSObjects()

$result = $crmHandle->describeSObjects(array('Lead'));

describeSoftphoneLayout()
NOTE: From the API docs: ‘Use only in the context of Salesforce CRM Call Center; do not call directly from client programs.’

describeTabs()

$result = $crmHandle->describeTabs();

Tweet This Post 

These posts are modeled after the EXAMPLES file that ships with the Salesforce Python Toolkit, in which I wrote snippets of code on how to use all the method calls in the Salesforce API spec. The posts will be modeled after the four sections of the Salesforce API docs; so they will be ‘Core Calls’, ‘Describe Calls’, ‘Utility Calls’, and ‘SOAP Headers’. There will be an Enterprise and Partner WSDL version of each.

NOTE: These examples are not intended to teach the Salesforce API; rather, they are here to illustrate how the PHP Toolkit implements the Salesforce API.

Prerequisites
All examples below assume the Toolkit has been instantiated and the connection has been made.

$crmHandle = new SforcePartnerClient();
$crmHandle->createConnection(‘/path/to/partner.wsdl.xml’);

Additionally, all examples except login() assume you are logged in, using a call such as
$crmHandle->login(‘joe@example.com.sbox1′, ‘*passwordhere*’ . ‘*securitytokenhere*’);

Conventions
<create lead> – implies that you copy and paste the code from create(), so you have a Lead in the variable $lead and a SaveResult in the variable $result

<create 2 leads> – same as create lead, except copy and paste the code from ‘create 2 leads’ in create()

Variable Names

• $crmHandle – reference to an instance of the Toolkit object
• $result – the result of a Salesforce method call
• $lead – a lead object

Notes
Date formats are in the SOAP dateTime format (ISO 8601), e.g. ‘2009-06-01T23:01:01Z’.

If you see an error like ‘INVALID_TYPE: Must send a concrete entity type’, most likely, you have forgotten to wrap your object in an array before passing it to a method.

convertLead()

<create lead>
$leadConvert = new SObject();
$leadConvert->leadId = $result->id;
// The possible values for convertedStatus depend on what's in the
// picklist for your org.  You can take a look at the 'Convert Lead' screen
// in the UI for your API user to see what's there
$leadConvert->convertedStatus = 'Qualified';
$leadConvert->doNotCreateOpportunity = true;
$leadConvert->overwriteLeadSource = false;
$leadConvert->sendNotificationEmail = false;
$result = $crmHandle->convertLead($leadConvert);

create()

$lead = new SObject();
$lead->fields = array('FirstName' => 'Joe',
                      'LastName' => 'Moke',
                      'Company' => 'Jamoke, Inc.',
                      'Email' => 'joe@example.com');
$lead->type = 'Lead';
$result = $crmHandle->create(array($lead), 'Lead');

delete()

<create lead>
$result = $crmHandle->delete(array($result->id));

emptyRecycleBin()

$result = $crmHandle->emptyRecycleBin(array('*ID OF A DELETED OBJECT HERE*'));

getDeleted()

// $startDate must be the later of 30 days prior and the last recycle bin purge
$result = $crmHandle->getDeleted('Lead', $startDate, $endDate);

getUpdated()

// $startDate must be later than 30 days prior
$result = $crmHandle->getUpdated('Lead', $startDate, $endDate);

invalidateSessions()
BEWARE there is a bug in versions 13.0 and earlier of the PHP Toolkit where it calls both invalidateSessions() AND logout(), generating an exception. I would strongly discourage use of either call, as they log out all concurrent sessions of the user!

You were warned…

$result = $crmHandle->invalidateSessions($crmHandle->getSessionId());

login()

$crmHandle->login('joe@example.com.sbox1', '*password*' . '*securitytoken*');

logout()
SEE NOTES FOR invalidateSessions()

$result = $crmHandle->logout();

merge()

// assume we have two IDs stored in $id and $id2

// retrieve what will be the master record
$result = $crmHandle->retrieve('FirstName, LastName, Company, Email', 'Lead', $id);
$lead = $result[0];

$mergeRequest = new SObject();
$mergeRequest->masterRecord = $lead;
$mergeRequest->recordToMergeIds = $id2;
$result = $crmHandle->merge($mergeRequest, 'Lead');

process()
The Toolkit diverges slightly from the API here, as it doesn’t implement process(), but instead implements processSubmitRequest() and processWorkitemRequest().

processSubmitRequest() (non-standard)
NOTE: The API docs for this call are currently incorrect; the ProcessSubmitRequest object takes a property ‘comments’, not ‘comment’ as stated here.

$processRequest = new SObject();
$processRequest->objectId = '*ID OF OBJECT PROCESS REQUEST AFFECTS*';
$processRequest->comments = 'This is what I think.';
$result = $crmHandle->processSubmitRequest(array($processRequest));

processWorkitemRequest() (non-standard)
NOTE: The API docs for this call are currently incorrect; the ProcessWorkitemRequest object takes a property ‘comments’, not ‘comment’ as stated here.

$processRequest = new SObject();
$processRequest->action = 'Approve';
$processRequest->workitemId = '*ID OF OBJECT PROCESS REQUEST AFFECTS*';
$processRequest->comments = 'I approved this request.';
$result = $crmHandle->processWorkitemRequest(array($processRequest));

query()

$result = $crmHandle->query('SELECT FirstName, LastName FROM Lead');

queryAll()
This method is broken in the Partner version as of version 13.1; however, there is a simple fix. Add the following method to SforcePartnerClient.php at line 158:

  public function queryAll($query) {
    return new QueryResult(parent::queryAll($query));
  }

Otherwise, for the following query:

$result = $crmHandle->queryAll('SELECT FirstName, LastName FROM Lead LIMIT 2');

the Toolkit returns

    [0]=>
    object(stdClass)#6 (3) {
      ["type"]=>
      string(4) "Lead"
      ["Id"]=>
      NULL
      ["any"]=>
      string(73) "<sf:FirstName>Joe</sf:FirstName><sf:LastName>Moke</sf:LastName>"
    }

instead of

    [0]=>
    object(SObject)#5 (2) {
      ["type"]=>
      string(4) "Lead"
      ["fields"]=>
      object(stdClass)#9 (2) {
        ["FirstName"]=>
        string(4) "Joe"
        ["LastName"]=>
        string(5) "Moke"
      }
    }

like the Enterprise version does. The working example is the query above.

queryMore()

// return a maximum of 200 results
$queryOptions = new QueryOptions(200);
$crmHandle->setQueryOptions($queryOptions);
$result = $crmHandle->query('SELECT FirstName, LastName FROM Lead');
while ($result->done === false) {
  $result = $crmHandle->queryMore($result->queryLocator);
  // do something with results
}

retrieve()
NOTE: The Partner version will return a 1-length array with the object in it for a single match, the Enterprise version will return the object itself.

$result = $crmHandle->retrieve('FirstName, LastName, Company, Email', 'Lead', $id);
$lead = $result[0];

search()
Search is currently broken in the Partner Toolkit as of version 13.1, and in order to use it, you must make a couple of modifications to SforcePartnerClient.php. Note that this is not the official implementation, but it does comply with what’s in the partner WSDL.

In the class SforcePartnerClient, after retrieve(), add the following method:

  public function search($searchString) {
    return new SearchResult(parent::search($searchString));
  }

Below the class SforcePartnerClient, add the following class:

class SearchResult {
  public $searchRecords = array();

  /**
   * SearchResult ctor
   *
   * SforceBaseClient::search() will return three different structures depending on result count,
   * distinguishable in the following way:
   * 0 results: empty stdClass object
   * 1 result: $response->searchRecords is an object, not an array
   * 2+ results: $response->searchRecords is an array
   *
   * @param stdClass $response  Response from base class
   */
  public function __construct($response) {
    if (!isset($response->searchRecords)) {
      return;
    } elseif (!is_array($response->searchRecords)) {
      $this->searchRecords[]->record = new SObject($response->searchRecords->record);
    } else {
      foreach ($response->searchRecords as $searchRecord) {
        $this->searchRecords[]->record = new SObject($searchRecord->record);
      }
    }
  }
}

You can now use the search() method in the same way as in the Enterprise client:

$result = $crmHandle->search('FIND {Joe Moke} IN Name Fields RETURNING Lead(Name, Phone)');

undelete()

$result = $crmHandle->undelete(array('*ID HERE*'));

update()
NOTE: Unlike the Enterprise version, you can set more than one field to null in an update() call. However, you must unset() each field as well, not set the field equal to null or ”.

<create lead>

$lead->Id = $result->id;
$lead->fieldsToNull = array('Email', 'Company');
unset($lead->fields['Email']);
unset($lead->fields['Company']);
$crmHandle->update(array($lead), 'Lead');

upsert()

<create lead>

$lead->Id = $result->id;
$lead->FirstName = 'Bob';
$crmHandle->upsert('Id', array($lead), 'Lead');

Tweet This Post 

These posts are modeled after the EXAMPLES file that ships with the Salesforce Python Toolkit, in which I wrote snippets of code on how to use all the method calls in the Salesforce API spec. The posts will be modeled after the four sections of the Salesforce API docs; so they will be ‘Core Calls’, ‘Describe Calls’, ‘Utility Calls’, and ‘SOAP Headers’. There will be an Enterprise and Partner WSDL version of each.

NOTE: These examples are not intended to teach the Salesforce API; rather, they are here to illustrate how the PHP Toolkit implements the Salesforce API.

Prerequisites
All examples below assume the Toolkit has been instantiated and the connection has been made.

$crmHandle = new SforceEnterpriseClient();
$crmHandle->createConnection(‘/path/to/enterprise.wsdl.xml’);

Additionally, all examples except login() assume you are logged in, using a call such as
$crmHandle->login(‘joe@example.com.sbox1′, ‘*passwordhere*’ . ‘*securitytokenhere*’);

Conventions
<create lead> – implies that you copy and paste the code from create(), so you have a Lead in the variable $lead and a SaveResult in the variable $result

<create 2 leads> – same as create lead, except copy and paste the code from ‘create 2 leads’ in create()

Variable Names

• $crmHandle – reference to an instance of the Toolkit object
• $result – the result of a Salesforce method call
• $lead – a lead object

Notes
Date formats are in the SOAP dateTime format (ISO 8601), e.g. ‘2009-06-01T23:01:01Z’.

If you see an error like ‘INVALID_TYPE: Must send a concrete entity type’, most likely, you have forgotten to wrap your object in an array before passing it to a method.

convertLead()

<create lead>
$leadConvert = new stdClass();
$leadConvert->leadId = $result->id;
// The possible values for convertedStatus depend on what's in the
// picklist for your org.  You can take a look at the 'Convert Lead' screen
// in the UI for your API user to see what's there
$leadConvert->convertedStatus = 'Qualified';
$leadConvert->doNotCreateOpportunity = true;
$leadConvert->overwriteLeadSource = false;
$leadConvert->sendNotificationEmail = false;
$result = $crmHandle->convertLead($leadConvert);

create()

$lead = new stdClass();
$lead->FirstName = 'Joe';
$lead->LastName = 'Moke';
$lead->Company = 'Jamoke, Inc.';
$lead->Email = 'joe@example.com';
$result = $crmHandle->create(array($lead), 'Lead');

delete()

<create lead>
$result = $crmHandle->delete(array($result->id));

emptyRecycleBin()

$result = $crmHandle->emptyRecycleBin(array('*ID OF A DELETED OBJECT HERE*'));

getDeleted()

// $startDate must be the later of 30 days prior and the last recycle bin purge
$result = $crmHandle->getDeleted('Lead', $startDate, $endDate);

getUpdated()

// $startDate must be later than 30 days prior
$result = $crmHandle->getUpdated('Lead', $startDate, $endDate);

invalidateSessions()
BEWARE there is a bug in versions 13.0 and earlier of the PHP Toolkit where it calls both invalidateSessions() AND logout(), generating an exception. I would strongly discourage use of either call, as they log out all concurrent sessions of the user!

You were warned…

$result = $crmHandle->invalidateSessions($crmHandle->getSessionId());

login()

$crmHandle->login('joe@example.com.sbox1', '*password*' . '*securitytoken*');

logout()
SEE NOTES FOR invalidateSessions()

$result = $crmHandle->logout();

merge()

// assume we have two IDs stored in $id and $id2

// retrieve what will be the master record
$lead = $crmHandle->retrieve('FirstName, LastName, Company, Email', 'Lead', $id);

$mergeRequest = new stdClass();
$mergeRequest->masterRecord = $lead;
$mergeRequest->recordToMergeIds = $id2;
$result = $crmHandle->merge($mergeRequest, 'Lead');

process()
The Toolkit diverges slightly from the API here, as it doesn’t implement process(), but instead implements processSubmitRequest() and processWorkitemRequest().

processSubmitRequest() (non-standard)
NOTE: The API docs for this call are currently incorrect; the ProcessSubmitRequest object takes a property ‘comments’, not ‘comment’ as stated here.

$processRequest = new stdClass();
$processRequest->objectId = '*ID OF OBJECT PROCESS REQUEST AFFECTS*';
$processRequest->comments = 'This is what I think.';
$result = $crmHandle->processSubmitRequest(array($processRequest));

processWorkitemRequest() (non-standard)
NOTE: The API docs for this call are currently incorrect; the ProcessWorkitemRequest object takes a property ‘comments’, not ‘comment’ as stated here.

$processRequest = new stdClass();
$processRequest->action = 'Approve';
$processRequest->workitemId = '*ID OF OBJECT PROCESS REQUEST AFFECTS*';
$processRequest->comments = 'I approved this request.';
$result = $crmHandle->processWorkitemRequest(array($processRequest));

query()

$result = $crmHandle->query('SELECT FirstName, LastName FROM Lead');

queryAll()
NOTE: Using the QueryOptions header in conjunction with queryAll() (not query() or queryMore()) DOES NOT WORK as of version 13.1, even though it should per the API spec. This is because the Toolkit fails to attach the SOAP header correctly, and to fix this, simply add

$call == "queryAll" ||

at line 266 in SforceBaseClient.php.

$result = $crmHandle->queryAll('SELECT FirstName, LastName FROM Lead LIMIT 2');
foreach ($result->records as $record) {
  echo $record->FirstName . ' ' . $record->LastName . "\n";
}

queryMore()

// return a maximum of 200 results
$queryOptions = new QueryOptions(200);
$crmHandle->setQueryOptions($queryOptions);
$result = $crmHandle->query('SELECT FirstName, LastName FROM Lead');
while ($result->done === false) {
  $result = $crmHandle->queryMore($result->queryLocator);
  // do something with results
}

retrieve()

$lead = $crmHandle->retrieve('FirstName, LastName, Company, Email', 'Lead', $id);

search()

$result = $crmHandle->search('FIND {Joe Moke} IN Name Fields RETURNING Lead(Name, Phone)');

undelete()

$result = $crmHandle->undelete(array('*ID HERE*'));

update()
NOTE: There is a bug in the Toolkit (as of v13.1) where when setting fields to null (using $obj->fieldsToNull()), you cannot pass an array of fields, you are only able to set one single field to null per update() call.

<create lead>

$lead->Id = $result->id;
$lead->fieldsToNull = 'Email';
$crmHandle->update(array($lead), 'Lead');

upsert()
NOTE: There is a VERY bad bug in versions 13.0 and earlier of the PHP Toolkit, it has ‘Contact’ hard-coded in the upsert() call in SforceEnterpriseClient.php (line 90). For it to be usable, it needs to take a type, so the method should be rewritten as follows (this will bring it in line with newer versions):

  public function upsert($ext_Id, $sObjects, $sObjectType) {
    $arg = new stdClass;
    $arg->externalIDFieldName = new SoapVar($ext_Id, XSD_STRING, 'string', 'http://www.w3.org/2001/XMLSchema');
    foreach ($sObjects as &$sObject) {
      $sObject = new SoapVar($sObject, SOAP_ENC_OBJECT, $sObjectType, $this->namespace);
    }
    $arg->sObjects = $sObjects;
    return parent::_upsert($arg);
  }

After you change that, you can use upsert() as follows:

<create lead>

$lead->Id = $result->id;
$lead->FirstName = 'Bob';
$crmHandle->upsert('Id', array($lead), 'Lead');

Tweet This Post