Salesforce Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coffeebike/salesforce-bundle
   

   Add to config/bundles.php:

   CoffeeBike\SalesforceBundle\CoffeeBikeSalesforceBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference CoffeeBikeSalesforceBundle
   

   Update config/packages/coffee_bike_salesforce.yaml with your Salesforce credentials:

   coffee_bike_salesforce:
       client_id:     '%env(SF_CLIENT_ID)%'
       client_secret: '%env(SF_CLIENT_SECRET)%'
       username:      '%env(SF_USERNAME)%'
       password:      '%env(SF_PASSWORD)%'
       security_token: '%env(SF_SECURITY_TOKEN)%'
       domain:        'login' # or 'test' for sandbox
   

3. First Use Case: Querying Accounts Inject the SalesforceClient service and execute a SOQL query:

   use CoffeeBike\SalesforceBundle\Client\SalesforceClient;
   
   class AccountService {
       public function __construct(private SalesforceClient $sfClient) {}
   
       public function getAccounts(): array {
           return $this->sfClient->query('SELECT Id, Name FROM Account LIMIT 10')->getRecords();
       }
   }
   

Implementation Patterns

Common Workflows

1. Authentication & Session Management

   • The bundle handles OAuth2 authentication under the hood. Use dependency injection for the SalesforceClient to ensure sessions persist across requests.
   • For long-running processes, manually refresh the access token:

     $this->sfClient->refreshAccessToken();
     

2. CRUD Operations

   • Create: Use create() with an associative array of field-value pairs.

     $account = $this->sfClient->create('Account', [
         'Name' => 'Acme Corp',
         'Industry' => 'Technology'
     ]);
     

   • Read: Use query() for SOQL or get() for single records by ID.

     $account = $this->sfClient->get('Account', '001XXXXXXXXXXXX');
     

   • Update: Use update() with the record ID and field updates.

     $this->sfClient->update('Account', '001XXXXXXXXXXXX', ['Name' => 'Acme Inc']);
     

   • Delete: Use delete() with the record ID.

     $this->sfClient->delete('Account', '001XXXXXXXXXXXX');
     

3. Bulk Operations

   • Use bulkQuery() and bulkQueryJobResults() for large datasets:

     $jobId = $this->sfClient->bulkQuery('SELECT Id FROM Account');
     $results = $this->sfClient->bulkQueryJobResults($jobId);
     

4. Metadata API

   • Retrieve custom objects or fields dynamically:

     $objects = $this->sfClient->describe()->getSobjects();
     

Integration Tips

• Event Dispatching: Extend the bundle by listening to salesforce.before_request and salesforce.after_response events for logging or custom logic.
• Caching: Cache frequent queries or metadata using Symfony’s cache component:

  $this->sfClient->setCache($cacheItemPool);
  

• Error Handling: Wrap API calls in try-catch blocks to handle SalesforceApiException:

  try {
      $this->sfClient->query('INVALID_SOQL');
  } catch (SalesforceApiException $e) {
      // Handle error (e.g., log or retry)
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Silent failures if credentials are invalid or expired.
   • Fix: Enable debug mode and check for SalesforceApiException:

     # config/packages/monolog.yaml
     handlers:
         salesforce:
             type: stream
             path: "%kernel.logs_dir%/salesforce.log"
             level: debug
     

   • Verify tokens using:

     php bin/console debug:container coffee_bike_salesforce.client
     

2. SOQL Limitations

   • Issue: Complex queries may fail with "MalformedQuery" errors.
   • Fix: Test SOQL in the Salesforce Developer Console first.

3. Rate Limiting

   • Issue: Salesforce enforces API limits. Exceeding limits may cause QUOTA_EXCEEDED errors.
   • Fix: Implement exponential backoff in retries:

     $this->sfClient->setRetryPolicy(new ExponentialBackoffRetryPolicy());
     

4. Sandbox vs. Production

   • Issue: Forgetting to switch domains (login vs. test) can cause authentication failures.
   • Fix: Use environment variables or config overrides:

     # config/packages/coffee_bike_salesforce.yaml
     coffee_bike_salesforce:
         domain: '%env(SF_DOMAIN)%' # Set via .env
     

Debugging

• Enable Verbose Logging Set the log level to debug in config/packages/coffee_bike_salesforce.yaml:

  coffee_bike_salesforce:
      debug: true
  

• Inspect Raw Responses Use a middleware to log raw API responses:

  $this->sfClient->setEventDispatcher($dispatcher);
  $dispatcher->addListener('salesforce.after_response', function (AfterResponseEvent $event) {
      file_put_contents(
          'sf_response.log',
          print_r($event->getResponse()->getBody(), true)
      );
  });
  

Extension Points

1. Custom API Calls Override the HttpClient implementation to add headers or modify requests:

   $this->sfClient->setHttpClient($customHttpClient);
   

   Example with Guzzle:

   $client = new \GuzzleHttp\Client([
       'headers' => ['X-Custom-Header' => 'value']
   ]);
   

2. Custom Serializers Extend the SalesforceResponse class to handle custom Salesforce responses:

   $this->sfClient->setResponseFactory(new CustomSalesforceResponseFactory());
   

3. Bulk API Extensions Implement a custom BulkQueryJob class to handle large datasets with progress tracking:

   $this->sfClient->setBulkQueryJobFactory(new CustomBulkQueryJobFactory());
   

Configuration Quirks

• Security Token The security_token (often found in Salesforce under "Reset My Security Token") is required for username-password authentication. Omitting it will cause authentication failures.
• Domain Overrides The domain config must match your Salesforce instance URL (e.g., login.salesforce.com or test.salesforce.com). Incorrect values will fail authentication.
• Environment Variables Ensure .env variables are loaded:

  php bin/console cache:clear