Easysf Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require adrianbaez/easysf-bundle
   

   Register the bundle in config/app.php under providers:

   Adrianbaez\EasySfBundle\EasySfBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Adrianbaez\EasySfBundle\EasySfBundle" --tag="config"
   

   Edit config/easysf.php to set up your Salesforce credentials (consumer key, consumer secret, callback URL, etc.).

3. First Use Case: OAuth Authentication Trigger the OAuth flow via a route or controller:

   use Adrianbaez\EasySfBundle\Facades\EasySf;
   
   // Redirect to Salesforce for auth
   return EasySf::authenticate();
   
   // Handle callback (e.g., in a route)
   $token = EasySf::handleCallback();
   

Implementation Patterns

Common Workflows

1. OAuth Flow Integration

   • Use EasySf::authenticate() in a controller to redirect users to Salesforce for authentication.
   • Capture the callback in a route (e.g., /salesforce/callback) and process it with EasySf::handleCallback().
   • Store the returned token securely (e.g., in the user session or database).

2. API Calls

   • Fetch Salesforce data via REST API:

     $accounts = EasySf::get('/services/data/vXX.X/sobjects/Account');
     

   • POST/PUT/DELETE operations:

     $newAccount = ['Name' => 'Test Account'];
     EasySf::post('/services/data/vXX.X/sobjects/Account', $newAccount);
     

3. SOQL Queries

   • Execute SOQL queries directly:

     $results = EasySf::query('SELECT Id, Name FROM Account LIMIT 10');
     

4. Bulk API (Legacy)

   • For large data operations (if supported in the package):

     $jobId = EasySf::bulkInsert('/services/data/vXX.X/jobs/ingest', 'Account', $data);
     

Integration Tips

• Middleware: Protect routes requiring Salesforce auth with middleware:

  public function handle($request, Closure $next) {
      if (!EasySf::isAuthenticated()) {
          return redirect()->route('salesforce.auth');
      }
      return $next($request);
  }
  

• Event Listeners: Extend functionality by listening to easysf.authenticated or easysf.error events.
• Caching: Cache API responses (e.g., using Laravel’s cache) to reduce Salesforce API calls.

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2018—assume no active maintenance. Test thoroughly and consider alternatives like league/oauth2-salesforce for modern Laravel (8+).
   • Workaround: Fork the repo to fix issues or extend functionality.

2. OAuth Callback Handling

   • Ensure your callback URL in config/easysf.php matches Salesforce’s registered redirect URI exactly (including http/https).
   • Debugging: Check storage/logs/laravel.log for OAuth errors (e.g., invalid_grant).

3. API Versioning

   • The package may not support newer Salesforce API versions (e.g., v56.0+). Manually override the endpoint version in EasySf::get() if needed:

     EasySf::get('/services/data/v56.0/sobjects/Account');
     

4. Token Expiry

   • Salesforce tokens expire (typically 2 hours). Implement a refresh mechanism:

     try {
         $token = EasySf::getAccessToken(); // May auto-refresh
     } catch (\Exception $e) {
         // Re-authenticate or handle refresh logic
     }
     

Debugging Tips

• Enable Logging: Set debug: true in config/easysf.php to log API requests/responses.
• HTTP Client: Inspect raw requests using Laravel’s tap:

  $response = EasySf::get('/path')->tap(function ($response) {
      \Log::info('Raw Response:', $response->getBody());
  });
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $data = EasySf::get('/path');
  } catch (\Adrianbaez\EasySfBundle\Exceptions\EasySfException $e) {
      \Log::error($e->getMessage());
      abort(500, 'Salesforce API error');
  }
  

Extension Points

1. Custom Endpoints Override the base URL in the config or extend the EasySf facade to add custom methods:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       EasySf::extend(function ($client) {
           $client->customMethod = function ($endpoint) {
               return $client->get($endpoint);
           };
       });
   }
   

2. Model Bindings Create a trait to bind Salesforce records to Eloquent models:

   use Adrianbaez\EasySfBundle\Facades\EasySf;
   
   trait SalesforceBindable {
       public static function findBySfId($sfId) {
           $response = EasySf::get("/services/data/vXX.X/sobjects/Account/{$sfId}");
           return new static((array) $response);
       }
   }
   

3. Webhook Handling If using Salesforce Platform Events, manually parse incoming webhooks and trigger Laravel events:

   // routes/web.php
   Route::post('/salesforce/webhook', function (Request $request) {
       $payload = $request->json()->all();
       event(new SalesforceWebhookReceived($payload));
   });