Salesforce Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require phpforce/salesforce-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Phpforce\SalesforceBundle\PhpforceSalesforceBundle::class => ['all' => true],
   ];
   

2. Configuration Define credentials in config/packages/phpforce_salesforce.yaml:

   phpforce_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:        '%env(SF_DOMAIN)%' # 'login' or 'test'
   

3. First Use Case Fetch a single Account record:

   use Phpforce\SalesforceBundle\Service\SalesforceService;
   
   class AccountController extends AbstractController
   {
       public function show(SalesforceService $sfService)
       {
           $account = $sfService->get('Account', '001XXXXXXXXXXXX');
           return $this->json($account);
       }
   }
   

Implementation Patterns

Common Workflows

1. CRUD Operations

   // Create
   $newAccount = $sfService->create('Account', [
       'Name' => 'Test Account',
       'Description' => 'Created via API'
   ]);
   
   // Update
   $sfService->update('Account', '001XXXXXXXXXXXX', ['Description' => 'Updated']);
   
   // Delete
   $sfService->delete('Account', '001XXXXXXXXXXXX');
   

2. Querying Data

   // SOQL Query
   $accounts = $sfService->query("SELECT Id, Name FROM Account WHERE AnnualRevenue > 1000000");
   
   // Bulk Query (for large datasets)
   $sfService->bulkQuery("SELECT Id FROM Account");
   

3. Metadata Operations

   // Describe an object
   $accountDesc = $sfService->describe('Account');
   
   // List all objects
   $objects = $sfService->getObjectDescriptions();
   

4. Bulk API Usage

   $job = $sfService->createBulkJob('AccountInsert');
   $job->addBatch(['Name' => 'Batch 1']);
   $job->close();
   

Integration Tips

• Dependency Injection: Always inject SalesforceService into controllers/services.
• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $result = $sfService->query("SELECT Id FROM NonExistentObject");
  } catch (\Phpforce\Exception\SalesforceException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Logging: Enable debug mode in config to log API calls:

  phpforce_salesforce:
      debug: true
  

• Caching: Cache frequent queries (e.g., object descriptions) in Symfony’s cache layer.

Gotchas and Tips

Pitfalls

1. Authentication Issues

   • Problem: INVALID_SESSION_ID or INVALID_LOGIN errors.
   • Fix: Verify security_token (if using password auth) and ensure credentials are correct. For OAuth, check token expiration.
   • Tip: Use the refreshToken() method if tokens expire:

     $sfService->refreshToken();
     

2. SOQL Limitations

   • Problem: Queries exceeding 2000 characters or 10,000 rows fail silently.
   • Fix: Use LIMIT clauses and paginate results:

     $query = "SELECT Id FROM Account";
     $results = $sfService->query($query, ['limit' => 1000]);
     

3. Bulk API Delays

   • Problem: Bulk jobs may take hours to process.
   • Fix: Poll job status asynchronously:

     $jobId = $sfService->createBulkJob('AccountInsert')->getJobId();
     $status = $sfService->getBulkJobStatus($jobId);
     

4. Field API Names

   • Problem: Incorrect field names (e.g., AnnualRevenue vs. AnnualRevenue__c for custom fields).
   • Fix: Use describe() to fetch correct API names:

     $fields = $sfService->describe('Account')['fields'];
     

Debugging Tips

• Enable Debug Mode: Set debug: true in config to log raw API responses.
• Check Headers: Use getLastRequest() and getLastResponse() on SalesforceService for debugging:

  $lastRequest = $sfService->getLastRequest();
  $this->addFlash('debug', print_r($lastRequest, true));
  

• Rate Limits: Monitor API usage via getApiUsage():

  $usage = $sfService->getApiUsage();
  $this->addFlash('info', sprintf('Used %d/%d API calls', $usage['numRequests'], $usage['limit']));
  

Extension Points

1. Custom Adapters Override the default SalesforceService to add custom logic:

   class CustomSalesforceService extends SalesforceService
   {
       public function customQuery(string $soql, array $options = [])
       {
           // Add custom logic (e.g., retry logic, logging)
           return parent::query($soql, $options);
       }
   }
   

2. Event Listeners Subscribe to salesforce.before_request and salesforce.after_response events in Symfony’s event dispatcher:

   # config/services.yaml
   services:
       App\EventListener\SalesforceListener:
           tags:
               - { name: kernel.event_listener, event: salesforce.before_request, method: onBeforeRequest }
   

3. Custom Metadata Extend the bundle’s metadata handling by implementing Phpforce\Metadata\MetadataInterface.

4. Async Processing Use Symfony’s Messenger component to handle long-running Bulk API jobs:

   $message = new ProcessBulkJobMessage($jobId);
   $this->messageBus->dispatch($message);