Salesforce Mapper Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/salesforce-package

Publish the configuration file (if needed) and ensure your .env includes Salesforce credentials:

SALESFORCE_CLIENT_ID=your_client_id
SALESFORCE_CLIENT_SECRET=your_client_secret
SALESFORCE_USERNAME=your_username
SALESFORCE_PASSWORD=your_password+security_token
SALESFORCE_DOMAIN=login.salesforce.com  # or your custom domain

The package now enforces the new salesforce-bundle under the hood. Test basic connectivity with:

use Vendor\Salesforce\SalesforceFacade;

$connection = SalesforceFacade::connection();
$response = $connection->query("SELECT Id, Name FROM Account LIMIT 10");

Implementation Patterns

1. Forced Bundle Integration

The package now mandates the use of salesforce-bundle (likely guzzlehttp/salesforce or similar) for all connections. Update your config/salesforce.php to align with the new bundle’s requirements:

'salesforce' => [
    'bundle' => 'salesforce-bundle', // Enforced
    'client_id' => env('SALESFORCE_CLIENT_ID'),
    'client_secret' => env('SALESFORCE_CLIENT_SECRET'),
    // ... other bundle-specific configs
],

Workaround for Legacy Code: If you rely on direct Salesforce_Client instantiation, wrap it in a service provider to delegate to the new bundle:

public function register()
{
    $this->app->singleton(Salesforce_Client::class, function ($app) {
        return (new \SalesforceBundle\Client())
            ->setConfig($app['config']['salesforce']);
    });
}

2. Connection Management

Use dependency injection for connections (recommended):

public function __construct(private SalesforceFacade $salesforce) {}

public function syncAccounts()
{
    $accounts = $this->salesforce->connection()->query("SELECT Id, Name FROM Account");
    // ...
}

Dynamic Connections: For multi-tenant apps, configure named connections in config/salesforce.php:

'connections' => [
    'primary' => [...],
    'sandbox' => [
        'domain' => 'test.salesforce.com',
        // ...
    ],
],

Access via:

$sandbox = SalesforceFacade::connection('sandbox');

3. Query Builder

Leverage the query builder for type safety:

$accounts = SalesforceFacade::query()
    ->select('Id', 'Name')
    ->from('Account')
    ->where('AnnualRevenue', '>', 1000000)
    ->limit(50)
    ->get();

Gotchas and Tips

Breaking Changes

• Direct Salesforce_Client Usage: The package no longer supports direct instantiation of Salesforce_Client. All connections must route through the new bundle. Fix: Update your code to use SalesforceFacade::connection() or inject the bundle’s client.
• Deprecated Methods: Methods like SalesforceFacade::getClient() are removed. Use SalesforceFacade::connection() instead.

Debugging

• Reconnect Issues: If you encounter reconnection errors, verify:
  1. The salesforce-bundle is properly installed (composer require guzzlehttp/salesforce or equivalent).
  2. Your .env credentials match the bundle’s expected format (e.g., SALESFORCE_PASSWORD must include the security token).
  3. The domain in config matches your Salesforce instance (e.g., login.salesforce.com vs. csXX.salesforce.com).
• Logging: Enable Guzzle logging for bundle debugging:

  $connection = SalesforceFacade::connection()->withOptions([
      'debug' => true,
      'logger' => new \Monolog\Logger('salesforce'),
  ]);
  

Performance Tips

• Batch Processing: Use the bundle’s batch API for large datasets:

  $batch = $connection->newBatch();
  $batch->addQuery("SELECT Id FROM Account");
  $results = $batch->execute();
  

• Caching: Cache connection instances in a service provider to avoid repeated OAuth flows:

  $this->app->singleton(\SalesforceBundle\Client::class, function ($app) {
      return new \SalesforceBundle\Client($app['config']['salesforce']);
  });
  

Extension Points

• Custom Bundle: If you need to extend the bundle, create a decorator:

  class CustomSalesforceClient extends \SalesforceBundle\Client
  {
      public function customMethod()
      {
          // ...
      }
  }
  

  Bind it in a service provider:

  $this->app->bind(\SalesforceBundle\Client::class, function ($app) {
      return new CustomSalesforceClient($app['config']['salesforce']);
  });
  

• Events: Listen for bundle events (e.g., salesforce.bundle.authenticated):

  event(new \SalesforceBundle\Events\Authenticated($client));
  

Migration Checklist

1. Update composer.json to include the required bundle.
2. Replace Salesforce_Client with SalesforceFacade::connection().
3. Update config to match the new bundle’s schema.
4. Test OAuth flows and reconnection logic.
5. Refactor direct API calls to use the query builder or bundle methods.