Eloquent Sales Force Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rob-lester-jr04/eloquent-sales-force
   

   Publish the config file:

   php artisan vendor:publish --provider="RobLester\ElSF\ElSFServiceProvider" --tag="config"
   

2. Configure .env: Add Salesforce credentials to your .env:

   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 sandbox
   

3. First Use Case: Define a model extending RobLester\ElSF\ElSFModel:

   use RobLester\ElSF\ElSFModel;
   
   class Account extends ElSFModel
   {
       protected $objectName = 'Account'; // Salesforce object name
   }
   

   Query Salesforce data like Eloquent:

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

Implementation Patterns

Core Workflows

1. CRUD Operations: Use Eloquent syntax for Salesforce records:

   // Create
   $account = Account::create(['Name' => 'Acme Corp']);
   
   // Read
   $account = Account::find('001XXXXXXXXXXXX');
   
   // Update
   $account->update(['Industry' => 'Technology']);
   
   // Delete
   $account->delete();
   

2. Relationships: Define polymorphic relationships (Salesforce doesn’t support traditional Eloquent relationships):

   class Contact extends ElSFModel
   {
       protected $objectName = 'Contact';
   
       public function account()
       {
           return $this->belongsTo(Account::class, 'AccountId');
       }
   }
   

3. Bulk Operations: Use chunk() for large datasets to avoid API limits:

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

4. Custom Fields: Map custom fields via $fillable or $attributes:

   class CustomObject extends ElSFModel
   {
       protected $objectName = 'Custom_Object__c';
       protected $fillable = ['Custom_Field__c', 'Another_Field__c'];
   }
   

5. SOQL Queries: Use raw SOQL for complex queries:

   $results = Account::query()->from("SELECT Id, Name FROM Account WHERE AnnualRevenue > 1000000");
   

Integration Tips

• Authentication: Use OAuth2 via ElSFServiceProvider (configured in .env).
• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $account = Account::find('001XXXXXXXXXXXX');
  } catch (\RobLester\ElSF\Exceptions\SalesforceException $e) {
      Log::error($e->getMessage());
  }
  

• Caching: Leverage Laravel’s cache for frequent queries:

  $accounts = Cache::remember('accounts', 3600, function () {
      return Account::all();
  });
  

Gotchas and Tips

Pitfalls

1. API Limits:

   • Salesforce enforces governor limits. Use chunk() or cursor() for large datasets.
   • Example:

     Account::cursor()->each(function ($account) {
         // Process one record at a time
     });
     

2. Field Naming:

   • Salesforce fields use __c suffix for custom fields (e.g., Custom_Field__c). Ensure your model’s $fillable matches this.
   • Fix: Validate field names against Salesforce schema:

     $fields = Account::getFields(); // Returns array of valid fields
     

3. Timeouts:

   • Long-running queries may timeout. Use setConnectionTimeout():

     Account::setConnectionTimeout(60); // 60 seconds
     

4. Soft Deletes:

   • Salesforce doesn’t support soft deletes natively. Use a custom scope:

     class Account extends ElSFModel
     {
         public function scopeActive($query)
         {
             return $query->where('IsDeleted', false);
         }
     }
     

5. Data Type Mismatches:

   • Salesforce and Laravel may interpret data types differently (e.g., Date vs. string). Cast fields explicitly:

     protected $casts = [
         'CreatedDate' => 'datetime',
         'AnnualRevenue' => 'float',
     ];
     

Debugging

• Enable Logging: Add to .env:

  SALESFORCE_LOG_LEVEL=debug
  

  Logs will appear in storage/logs/laravel.log.

• SOQL Debugging: Use toSql() to inspect generated SOQL:

  $query = Account::where('Industry', 'Technology');
  dd($query->toSql());
  

• Token Refresh: If you get INVALID_SESSION_ID, refresh the OAuth token:

  $this->app['RobLester\ElSF\ElSFServiceProvider']->refreshToken();
  

Extension Points

1. Custom Adapters: Extend RobLester\ElSF\Adapters\SalesforceAdapter for custom API logic.

2. Event Listeners: Listen to Salesforce events (e.g., created, updated):

   Account::created(function ($account) {
       // Post-create logic
   });
   

3. Custom Queries: Override newQuery() for object-specific behavior:

   class Account extends ElSFModel
   {
       public function newQuery()
       {
           $query = parent::newQuery();
           $query->with(['customScope']);
           return $query;
       }
   }
   

4. Bulk API: For high-volume operations, use the Salesforce Bulk API:

   Account::bulk()->insert($accounts);