Eloquent Salesforce Objects Laravel Package

Getting Started

First Steps

1. Installation

   composer require daikazu/eloquent-salesforce-objects
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Daikazu\SalesforceObjects\SalesforceObjectsServiceProvider"
   

2. Configure Salesforce Connection Edit .env or config/salesforce-objects.php with your 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
   

3. Define a Salesforce Model Extend Daikazu\SalesforceObjects\Eloquent\SalesforceModel:

   use Daikazu\SalesforceObjects\Eloquent\SalesforceModel;
   
   class Account extends SalesforceModel
   {
       protected $objectName = 'Account'; // Salesforce API name
       protected $primaryKey = 'Id';       // Salesforce ID field
   }
   

4. First Query

   $accounts = Account::where('Name', 'like', 'Acme%')->get();
   

Implementation Patterns

1. Eloquent-Like CRUD

Leverage familiar Eloquent syntax for Salesforce operations:

// Create
$account = Account::create(['Name' => 'Acme Corp', 'Industry' => 'Technology']);

// Read
$account = Account::find('001XXXXXXXXXXXXXXX');
$accounts = Account::where('AnnualRevenue', '>', 1000000)->take(10)->get();

// Update
$account->update(['Industry' => 'Software']);

// Delete
$account->delete();

2. Relationships

Define relationships using Eloquent conventions (supports belongsTo, hasMany, hasOne, etc.):

class Contact extends SalesforceModel
{
    protected $objectName = 'Contact';

    public function account()
    {
        return $this->belongsTo(Account::class, 'AccountId', 'Id');
    }
}

// Usage
$contact = Contact::find('003XXXXXXXXXXXXXXX');
$account = $contact->account; // Eager-loaded if needed

3. Bulk Operations

Use chunk() or cursor() for large datasets:

Account::where('Industry', 'Technology')->chunk(200, function ($accounts) {
    foreach ($accounts as $account) {
        // Process each account
    }
});

4. Custom SOQL Queries

Execute raw SOQL via query():

$results = Account::query("SELECT Id, Name, BillingCity FROM Account WHERE Industry = 'Technology' LIMIT 100");

5. Events & Observers

Use Eloquent observers for lifecycle hooks:

// app/Observers/AccountObserver.php
class AccountObserver
{
    public function saved(Account $account)
    {
        // Post-save logic (e.g., log, notify)
    }
}

// Register in a service provider
Account::observe(AccountObserver::class);

6. API Integration

Fetch Salesforce metadata dynamically:

$fields = Account::getFields(); // Returns array of field names
$describes = Account::describe(); // Returns full Salesforce object metadata

Gotchas and Tips

1. Field Name Mappings

• Salesforce fields use camelCase (e.g., AnnualRevenue), but Eloquent defaults to snake_case.
• Override $fillable or $guarded to match Salesforce API names:

  protected $fillable = ['Name', 'AnnualRevenue']; // Not 'annual_revenue'
  

2. Primary Key Handling

• Salesforce IDs are 18-character strings (e.g., 001XXXXXXXXXXXXXXX).
• Avoid auto-increment assumptions; always use Id as the primary key.

3. Bulk API Limits

• Default queries use the REST API (200 records max per request).
• For large datasets, use chunk() or enable the Bulk API via config:

  'bulk_api' => [
      'enabled' => true,
      'batch_size' => 10000,
  ],
  

4. Relationship Pitfalls

• Circular references can cause infinite loops. Use with() for eager loading:

  $account = Account::with('contacts')->find('001XXXXXXXXXXXXXXX');
  

• Polymorphic relationships are not natively supported; use raw SOQL if needed.

5. Error Handling

• Wrap Salesforce calls in try-catch for API-specific errors:

  try {
      $account = Account::find('invalid_id');
  } catch (\Daikazu\SalesforceObjects\Exceptions\SalesforceException $e) {
      Log::error($e->getMessage());
  }
  

6. Performance Tips

• Cache metadata: Salesforce object/field descriptions are expensive to fetch repeatedly.

  $fields = Cache::remember('account.fields', now()->addHours(1), function () {
      return Account::getFields();
  });
  

• Use select() to limit fetched fields:

  $accounts = Account::select(['Id', 'Name'])->get();
  

7. Testing

• Mock Salesforce responses in tests:

  $this->mock(SalesforceClient::class, function ($mock) {
      $mock->shouldReceive('query')
           ->once()
           ->andReturn(['records' => []]);
  });
  

8. Extension Points

• Custom Query Builder: Extend Daikazu\SalesforceObjects\Eloquent\Builder for reusable logic.
• Custom Auth: Override getAuth() in your model for OAuth2 or JWT flows.
• Webhooks: Use salesforce-objects/events to listen for Salesforce platform events.