Salesforce Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ddeboer/salesforce-client-bundle
   

   (Note: While deprecated, this package remains functional for legacy projects.)

2. Configuration: Add to config/bundles.php:

   return [
       // ...
       Ddeboer\SalesforceClientBundle\DdeboerSalesforceClientBundle::class => ['all' => true],
   ];
   

3. Basic Usage: Inject the client in a service:

   use Ddeboer\SalesforceClientBundle\Client\SalesforceClientInterface;
   
   class MyService {
       public function __construct(private SalesforceClientInterface $client) {}
   }
   

4. First API Call:

   $result = $this->client->query("SELECT Id, Name FROM Account LIMIT 10");
   $records = $result->getRecords();
   

Key Starting Points

• SOAP API Docs: Salesforce SOAP API Reference
• Bundle Docs: Resources/doc/ in the package
• Mapper Bundle: For ORM-like access (if needed)

Implementation Patterns

Core Workflows

1. Querying Data

// Simple query
$results = $this->client->query("SELECT Id, Name FROM Account");
$records = $results->getRecords();

// Paginated results (for large datasets)
$iterator = $this->client->createQueryIterator("SELECT Id FROM Account");
foreach ($iterator as $record) {
    // Process each record
}

2. Bulk Operations

Use BulkSaver to batch operations (avoids API limits):

$bulkSaver = $this->client->getBulkSaver();
$bulkSaver->upsert('Account', [
    ['Name' => 'Acme Corp', 'External_Id__c' => 'EXT123'],
    ['Name' => 'Globex', 'External_Id__c' => 'EXT456'],
]);
$bulkSaver->execute();

3. Timezone Handling

Automatically converts Salesforce UTC times to your local timezone:

$record = $this->client->query("SELECT Id, CreatedDate FROM Account LIMIT 1")->getRecords()[0];
$createdDate = $record->CreatedDate; // Localized datetime

4. Custom Logic via Events

Extend functionality with events (e.g., logging, error handling):

# config.yml
ddeboer_salesforce_client:
    events:
        query: ['App\EventListener\SalesforceQueryLogger']

Integration Tips

• Dependency Injection: Prefer constructor injection for the SalesforceClientInterface.
• Error Handling: Wrap API calls in try-catch:

  try {
      $this->client->query("INVALID_QUERY");
  } catch (\Ddeboer\SalesforceClientBundle\Exception\SalesforceException $e) {
      // Handle error (e.g., log, retry)
  }
  

• Configuration: Override defaults in config/packages/ddeboer_salesforce_client.yaml:

  ddeboer_salesforce_client:
      client:
          username: 'user@example.com'
          password: 'password'
          security_token: 'token'
          timezone: 'America/New_York'
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • This bundle is deprecated in favor of phpforce/salesforce-bundle. Migrate if possible.
   • If stuck with this bundle, monitor for breaking changes in Salesforce’s SOAP API.

2. SOAP Complexity:

   • Salesforce’s SOAP API has quirks (e.g., strict XML schemas). Validate queries/inputs.
   • Example: Use SOAP_VAR_ENCODING for complex types:

     $this->client->create('Account', ['Name' => 'Test'], SOAP_VAR_ENCODING);
     

3. Bulk API Limits:

   • Bulk operations (BulkSaver) have separate limits (check Salesforce Bulk API docs).
   • Monitor job status with:

     $bulkSaver->checkStatus();
     

4. Timezone Mismatches:

   • Ensure timezone in config matches your app’s timezone. Debug with:

     $this->client->getClient()->getLastRequestHeaders()['SOAPAction'];
     

Debugging

• Enable Logging:

  ddeboer_salesforce_client:
      client:
          logging: true
  

  Logs appear in var/log/salesforce_client.log.

• Inspect Raw SOAP: Use a tool like SoapUI to compare requests/responses with the bundle’s output.

• Common Errors:

  Error	Cause	Fix
  INVALID_LOGIN	Wrong credentials	Check username, password, token
  MALFORMED_QUERY	Syntax error in SOQL	Validate query in Salesforce Dev Console
  API_LIMIT_EXCEEDED	Too many calls	Use BulkSaver or implement retry logic
  FIELD_INTEGRITY_EXCEPTION	Invalid field value	Check field constraints in Salesforce

Extension Points

1. Custom Events:

   • Listen to events like query, create, or update:

     // src/EventListener/SalesforceLogger.php
     class SalesforceLogger implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'ddeboer_salesforce.query' => 'onQuery',
             ];
         }
         public function onQuery(QueryEvent $event) {
             // Log query details
         }
     }
     

2. Override Services:

   • Extend the client or bulk saver via compiler passes:

     // src/DependencyInjection/Compiler/SalesforcePass.php
     public function process(ContainerBuilder $container) {
         $definition = $container->findDefinition('ddeboer_salesforce.client');
         $definition->addMethodCall('setCustomConfig', ['key' => 'value']);
     }
     

3. Mapper Bundle Integration:

   • Use DdeboerSalesforceMapperBundle to map Salesforce objects to PHP classes:

     /** @Mapper\Entity(class="App\Entity\Account") */
     class AccountMapper {
         public function hydrate(SalesforceObject $obj, Account $entity) {
             $entity->setName($obj->Name);
         }
     }
     

Performance Tips

• Batch Queries: Use LIMIT and pagination (nextRecordsUrl) for large datasets.
• Avoid N+1: Fetch related data in a single query:

  $this->client->query("SELECT Id, (SELECT Id FROM Contacts) FROM Account");
  

• Bulk API: For >50k records, use the Salesforce Bulk API directly via the BulkSaver.