Force Toolkit Laravel Package

Getting Started

Minimal Steps

1. Manual Installation Since the package isn't on Packagist, clone the repo and include it in your project:

   git clone https://github.com/joshiausdemwald/Force.com-Toolkit-for-PHP-5.3.git
   

   Add the src directory to your composer.json autoload:

   "autoload": {
       "psr-4": {
           "Force\\Toolkit\\": "path/to/Force.com-Toolkit-for-PHP-5.3/src"
       }
   }
   

   Run composer dump-autoload.

2. Basic Authentication Initialize the toolkit with Salesforce credentials (SOAP-based):

   use Force\Toolkit\ForceToolkit;
   
   $toolkit = new ForceToolkit(
       'https://login.salesforce.com/services/Soap/u/46.0',
       'username@example.com',
       'your_password',
       'your_security_token'
   );
   

3. First Use Case: Fetching Accounts Execute a simple SOQL query:

   $query = "SELECT Id, Name FROM Account LIMIT 5";
   $results = $toolkit->query($query);
   foreach ($results as $account) {
       echo $account->Name . "\n";
   }
   

Where to Look First

• ForceToolkit.php: Core class for all API interactions.
• README.md: Basic examples (may be outdated).
• Test Cases: Check tests/ for usage patterns (e.g., TestForceToolkit.php).

Implementation Patterns

Usage Patterns

1. SOQL Queries Use query() for standard SOQL and queryAll() for large datasets:

   // Paginated query
   $queryLocator = $toolkit->query("SELECT Id FROM Account");
   $records = $toolkit->queryMore($queryLocator);
   

2. Bulk Operations (Limited) For bulk inserts/updates, use database::batch() (if supported):

   $batch = $toolkit->database::batch();
   $batch->add($toolkit->database::create('Contact', ['FirstName' => 'Jane']));
   $batch->execute();
   

3. Metadata API Retrieve custom objects/metadata (if needed):

   $objects = $toolkit->describeGlobal();
   

Laravel Integration Tips

1. Service Container Binding Register the toolkit as a singleton in AppServiceProvider:

   public function register()
   {
       $this->app->singleton('salesforce.toolkit', function ($app) {
           return new ForceToolkit(
               config('salesforce.soap_endpoint'),
               config('salesforce.username'),
               config('salesforce.password'),
               config('salesforce.security_token')
           );
       });
   }
   

2. Facade Wrapper Create a facade for cleaner syntax:

   // app/Facades/Salesforce.php
   namespace App\Facades;
   use Illuminate\Support\Facades\Facade;
   class Salesforce extends Facade { protected static function getFacadeAccessor() { return 'salesforce.toolkit'; } }
   

   Usage:

   use App\Facades\Salesforce;
   $accounts = Salesforce::query("SELECT Id, Name FROM Account");
   

3. Jobs for Async Operations Offload long-running Salesforce operations to queues:

   // app/Jobs/SyncLeads.php
   use Illuminate\Bus\Queueable;
   use Illuminate\Queue\SerializesModels;
   class SyncLeads implements Queueable, SerializesModels {
       public function handle() {
           $toolkit = app('salesforce.toolkit');
           $toolkit->query("SELECT Id FROM Lead");
       }
   }
   

4. Config Management Store credentials in .env:

   SALESFORCE_SOAP_ENDPOINT=https://login.salesforce.com/services/Soap/u/46.0
   SALESFORCE_USERNAME=user@example.com
   SALESFORCE_PASSWORD=your_password
   SALESFORCE_SECURITY_TOKEN=your_token
   

   Load in config/salesforce.php:

   return [
       'soap_endpoint' => env('SALESFORCE_SOAP_ENDPOINT'),
       'username' => env('SALESFORCE_USERNAME'),
       'password' => env('SALESFORCE_PASSWORD'),
       'security_token' => env('SALESFORCE_SECURITY_TOKEN'),
   ];
   

Gotchas and Tips

Pitfalls

1. PHP 5.3 Dependencies

   • The package relies on PHP 5.3-specific features (e.g., stdClass for responses).
   • Workaround: Use a Docker container with PHP 5.3 or fork the package to upgrade dependencies.

2. SOAP-Only Support

   • No REST API support (Salesforce’s modern standard).
   • Workaround: Manually construct REST endpoints or use a proxy.

3. No OAuth 2.0

   • Uses username/password auth, which Salesforce restricts in production.
   • Workaround: Use a connected app with OAuth 2.0 via a custom wrapper.

4. Limited Error Handling

   • Errors return generic SOAP faults. Wrap calls in try-catch:

   try {
       $toolkit->query("INVALID_SOQL");
   } catch (\SoapFault $e) {
       Log::error("Salesforce Error: " . $e->getMessage());
   }
   

5. No Bulk API Support

   • Missing Bulk API v2.0 for large datasets.
   • Workaround: Use queryAll() with manual pagination or switch to the official SDK.

Debugging Tips

1. Enable SOAP Debugging Add this to your ForceToolkit initialization:

   $toolkit->setDebug(true); // Logs SOAP requests/responses
   

2. Inspect Raw Responses The toolkit returns stdClass objects. Use json_encode() to debug:

   $results = $toolkit->query("SELECT Id FROM Account");
   dd(json_encode($results, JSON_PRETTY_PRINT));
   

3. Governor Limits Salesforce enforces API limits. Monitor usage:

   $limits = $toolkit->getServerInfo();
   Log::info("API Calls Used: " . $limits->apiRequestsUsed);
   

Extension Points

1. Custom Response Mapping Override the toolkit’s response handling:

   $toolkit->setResponseMapper(function ($response) {
       return json_decode(json_encode($response), true);
   });
   

2. Add REST Support Fork the package and extend ForceToolkit with REST methods:

   public function restQuery($endpoint, $params) {
       $client = new \GuzzleHttp\Client();
       return $client->get($endpoint, ['query' => $params]);
   }
   

3. Laravel Eloquent Integration Create a custom Eloquent model:

   // app/Models/SalesforceAccount.php
   namespace App\Models;
   use Illuminate\Database\Eloquent\Model;
   class SalesforceAccount extends Model {
       public static function fetch() {
           $toolkit = app('salesforce.toolkit');
           $results = $toolkit->query("SELECT Id, Name FROM Account");
           return collect($results)->map(function ($item) {
               return new static((array) $item);
           });
       }
   }
   

Configuration Quirks

1. SOAP Endpoint Versioning Hardcoded to API v46.0 (outdated). Update in the constructor:

   $toolkit = new ForceToolkit(
       'https://login.salesforce.com/services/Soap/u/58.0', // Modern version
       ...
   );
   

2. Session Management The toolkit does not refresh session IDs. Manually handle:

   if ($toolkit->isSessionExpired()) {
       $toolkit->login(...); // Re-authenticate
   }
   

3. Timeouts Default SOAP timeout is short. Increase in the constructor:

   $toolkit = new ForceToolkit(..., ['trace' => 1, 'exceptions' => 1, 'connection_timeout' => 30]);