The Force.com Toolkit for PHP gives developers an easy way to perform actions on a remote Salesforce.com database using the Force.com Web Services SOAP API, from directly within our self-hosted or third-party hosted PHP web sites. Using the Force.com Toolkit for PHP we can leverage the SOAP API to perform a flurry a database operations such as CRUD (create, read or query/search in this case, update/upsert, and delete), lead conversion, session management, and more. The toolkit also provides some basic Metadata API functionality in the form of object creation, object deletion, and checkStatus. Sadly this is all the toolkit provides support for by default, however there have been some efforts to extend the ability of PHP to interact with the Metadata API. For a complete list of API methods that the Force.com Toolkit for PHP supports – currently version 20.0 at the time of this writing – see the sample PHP Toolkit SOAP API calls page on developerforce.

There are a handful of PHP extensions that must be enabled in your PHP configuration in order for the Force.com Toolkit for PHP to function correctly. The key ones are:

• PHP version 5.x
• SOAP enabled
• SSL enabled
• cURL enabled
• OpenSSL enabled

If you’re not certain whether you meet all of these requirements you can always upload a phpinfo(); page to your server and review the details. Nowadays I would assume that most web hosting providers support all of these requirements by default, as my web host Media Temple does, however your mileage may vary. It certainly doesn’t hurt to send them an email with the five points above to confirm (although if you’re writing PHP and using the Force.com SOAP API you can probably figure this out ). In any event, there is a PHP Toolkit Setup site on developerforce to assist you if you don’t feel like asking questions in the comments on this post.

Now that our PHP setup is sorted we can move on to actually downloading and installing the toolkit. Salesforce has chosen to host the code on github under their developerforce username in the Force.com-Toolkit-for-PHP repository, which is located here:

• http: https://github.com/developerforce/Force.com-Toolkit-for-PHP.git
• git: git://github.com/developerforce/Force.com-Toolkit-for-PHP.git

The repo should resemble the following:

Once you’ve download the source from github upload it to your web server or place it in your web root if executing on your localhost. In my case I created a subdomain specifically for the Force.com PHP Toolkit as I am planning to build quite a bit of code to leverage it. My installation is located at sforce-php.jonholato.com. After you’ve uploaded the files navigate to the instructions.html file in the main directory (ex: yourdomain.com/ForcecomPHPToolkit/instructions.html or sforce-php.jonholato.com/instructions.html in my case) to learn about the different folders included with the package and how to setup a connection to your Salesforce.com environment.

The quickest way to setup and test a connection – though this is not the recommended way and should only be used temporarily – is to declare your Salesforce.com username and password in a separate PHP file as variables $USERNAME and $PASSWORD, respectively. Ideally we would implement a login form and leverage the session management functionality of the SOAP API to allow multi-user usage of the API features we’ll be implementing. Remember: our $PASSWORD value must be comprised of our actual Salesforce.com password concatenated with our security token because we are logging in through the API.

Here is our tempLogin.php file with our $USERNAME and $PASSWORD:

<?php 
 
$USERNAME = 'jon@jonholato.com';
// Password = Password
// Security Token = knKJBygYTF^&fUIhbUgfuGCfRdRSDAi0
$PASSWORD = 'PasswordknKJBygYTF^&fUIhbUgfuGCfRdRSDAi0';
 
?>

Lines 3 and 6 are the key ones in this file, where we define our Salesforce.com credentials (username and password (including security token).

Now that we’ve defined our credentials we’re ready to revisit the sample Force.com API calls page from the beginning of this post which has a few dozen ready made samples to help you get a feel for what you can do with the Force.com API. I’ve setup a few of the samples at my sforce-php subdomain mentioned earlier. The four that have been configured at the time of this writing are:

• GetUserInfo – GetUserInfo-Sample.php pulls information about the user making the API call from their Salesforce.com user record
• GetServerTimestamp – GetServerTimestamp-Sample.php displays current server timestamp of remote Salesforce.com server where API calls are landing
• CreateDeleteUndelete – CreateDeleteUndelete-Sample.php creates two hardcoded contacts from an array, deletes them, then undeletes them
• Search – Search-Sample.php performs hardcoded search for accounts, contacts and leads with 212 string in their phone number and returns array

Let’s take a look at the last one, Search-Sample.php, which searches our Salesforce.com Accounts, Contacts, and Leads for any records that have the New York City landline area code “212” in their phone number. Similar to the tempLogin.php page, these should not be hard-coded, but rather a search form should collect user input and search the database against a given user’s query. Let’s take a look at the temporary hard-coded Search-Sample.php:

<?php
// SOAP_CLIENT_BASEDIR - folder that contains the PHP Toolkit and your WSDL
// $USERNAME - variable that contains your Salesforce.com username (must be in the form of an email)
// $PASSWORD - variable that contains your Salesforce.com password
 
define("SOAP_CLIENT_BASEDIR", "./soapclient");
require_once (SOAP_CLIENT_BASEDIR.'/SforcePartnerClient.php');
require_once (SOAP_CLIENT_BASEDIR.'/SforceHeaderOptions.php');
 
require_once ('./misc/globalconstants.php');
 
try {
  $mySforceConnection = new SforcePartnerClient();
  $mySoapClient = $mySforceConnection->createConnection(SOAP_CLIENT_BASEDIR.'/partner.wsdl.xml');
  $mylogin = $mySforceConnection->login($USERNAME, $PASSWORD);
 
  $search = 'FIND {212*} IN PHONE FIELDS '.
        'RETURNING CONTACT(ID, PHONE, FIRSTNAME, LASTNAME), '.
        'LEAD(ID, PHONE, FIRSTNAME, LASTNAME), '.
        'ACCOUNT(ID, PHONE, NAME)';
  $searchResult = $mySforceConnection->search($search);
 
  print_r($searchResult);
} catch (Exception $e) {
  print_r($mySforceConnection->getLastRequest());
  echo $e->faultstring;
}
?>

The first few lines are just some comments about the file, the key item is line 2 which outlines the contents of the SOAP_CLIENT_BASEDIR. The $USERNAME and $PASSWORD lines were commented out in favor of moving the variables to a separate file (tempLogin.php) so that it could be reused elsewhere. Lines 6-10 are where we include our dependencies, toolkit libraries, and login details. You’ll notice that we’re including SforcePartnerClient.php, and I think now is a good time to point out that there are two versions of the WSDL included in the toolkit, Enterprise and Partner, the Enterprise WSDL only supports the default Salesforce.com objects while the Partner WSDL doesn’t have a dependency on specific object use. This is why we’re using SforcePartnerClient rather than SforceEnterpriseClient. Lines 13-15 are leveraging the built-in toolkit functions to connect to the Salesforce.com database. You’ll notice there’s no mysql_connect or mysql_query or mysql_select_db. Nope, nothing, all database connectivity functions nicely provided by Salesforce. Lines 17-21 are the SOSL query which is constructed using the Salesforce Object Search Language. This is actually the first time I’ve used SOSL over the standard SOQL, and my understanding from Salesforce is that you use SOSL when you aren’t certain exactly what or where you’re searching, and SOQL when you are. Thus, we’re using SOSL in this case to search across multiple objects for any records that meet our criteria. Finally, on line 23 we use the PHP function print_r to display the output on the page in a key => value format, and lines 24-26 are for error handling.

Here is the what our Search-Sample.php page looks like when we visit it:

I find that with the print_r function – at least with Google Chrome and Firefox – the data output looks much better when you right-click and choose view source:

And that concludes our overview of the Force.com Toolkit for PHP. In this post we learned about what the Force.com Toolkit for PHP is and some actions it can perform utilizing the SOAP and/or Metadata APIs; we learned about the server and software requirements for installation; where to download the source code from on github; how to install on your web server; and finally how to setup a connection to your Salesforce.com environment and execute a simple search against Salesforce.com Accounts, Contacts, and Leads.

Any questions or comments please let me know below. Cheers.

Read More