Common Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require phpforce/common
   

   Add to composer.json under require if not using autoload.

2. First Use Case: Salesforce API Requests

   use Phpforce\Common\Salesforce\SalesforceConnection;
   
   $connection = new SalesforceConnection([
       'clientId' => 'YOUR_CLIENT_ID',
       'clientSecret' => 'YOUR_CLIENT_SECRET',
       'username' => 'YOUR_USERNAME',
       'password' => 'YOUR_PASSWORD+SECURITY_TOKEN',
       'loginUrl' => 'https://login.salesforce.com', // or sandbox
   ]);
   
   $response = $connection->get('/services/data/v56.0/sobjects/Account');
   $accounts = $response->getBody();
   

3. Key Classes to Explore

   • SalesforceConnection: Core connection handler.
   • SalesforceResponse: Parse API responses.
   • SalesforceException: Handle errors gracefully.
   • SalesforceRestClient: For REST API operations.

4. Where to Look First

   • Source Code (minimal but clear).
   • PhpForce Documentation (basic usage examples).
   • Test cases in tests/ for edge cases.

Implementation Patterns

Workflows

1. Authentication Flow

   $connection = new SalesforceConnection($config);
   $connection->login(); // Explicit login (optional if auto-login is enabled).
   

2. CRUD Operations

   // Create
   $response = $connection->create('/services/data/v56.0/sobjects/Account', [
       'Name' => 'Test Account',
       'Description' => 'Created via PhpForce',
   ]);
   
   // Read (Single)
   $account = $connection->get('/services/data/v56.0/sobjects/Account/001XXXXXXXXXXXXXXX');
   
   // Update
   $connection->update('/services/data/v56.0/sobjects/Account/001XXXXXXXXXXXXXXX', [
       'Description' => 'Updated description',
   ]);
   
   // Delete
   $connection->delete('/services/data/v56.0/sobjects/Account/001XXXXXXXXXXXXXXX');
   

3. Bulk API (Async Operations)

   $bulk = $connection->getBulk();
   $job = $bulk->createJob('Account');
   $job->addBatch(['Name' => 'Batch 1']);
   $job->close();
   $job->waitForCompletion();
   

4. SOQL Queries

   $query = 'SELECT Id, Name FROM Account LIMIT 10';
   $response = $connection->query($query);
   $results = $response->getBody()->getRecords();
   

Integration Tips

• Laravel Service Provider Bind the connection in AppServiceProvider:

  $this->app->singleton(SalesforceConnection::class, function ($app) {
      return new SalesforceConnection(config('services.salesforce'));
  });
  

• Configuration Store credentials in .env:

  SALESFORCE_CLIENT_ID=your_id
  SALESFORCE_CLIENT_SECRET=your_secret
  SALESFORCE_USERNAME=user@example.com
  SALESFORCE_PASSWORD=pass+token
  SALESFORCE_LOGIN_URL=https://login.salesforce.com
  

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

  try {
      $response = $connection->get('/services/data/v56.0/sobjects/Account');
  } catch (SalesforceException $e) {
      Log::error('Salesforce API Error: ' . $e->getMessage());
      return response()->json(['error' => 'Salesforce unavailable'], 500);
  }
  

• Logging Enable debug logging for troubleshooting:

  $connection->setLogger(new Monolog\Logger('salesforce'));
  

Gotchas and Tips

Pitfalls

1. Session Expiry

   • Salesforce sessions expire after 2 hours. Use login() to refresh.
   • Fix: Implement a middleware to check session validity or auto-reconnect.

2. SOQL Injection

   • Never concatenate user input into SOQL queries. Use parameterized queries or whitelist fields.
   • Fix: Validate input or use a query builder like SalesforceQueryBuilder.

3. Bulk API Limits

   • Bulk API jobs have size limits (e.g., 10,000 records per batch). Monitor job status with waitForCompletion().
   • Fix: Split large datasets into chunks.

4. Rate Limiting

   • Salesforce enforces API call limits (e.g., 15,000 requests/day for unlimited edition).
   • Fix: Implement exponential backoff for throttling errors (429 Too Many Requests).

5. Case Sensitivity

   • API endpoints and field names are case-sensitive (e.g., /services/data/v56.0 vs /services/data/V56.0).

Debugging

• Enable Verbose Logging

  $connection->setDebug(true); // Logs raw requests/responses.
  

• Common Errors

  Error Code	Cause	Solution
  INVALID_SESSION_ID	Expired session.	Call login() again.
  INVALID_FIELD	Invalid field name.	Check Salesforce schema or field API name.
  MALFORMED_QUERY	Invalid SOQL.	Validate query syntax.
  REQUIRED_FIELD_MISSING	Missing required field.	Include all required fields in payload.

Extension Points

1. Custom Response Parsing Override SalesforceResponse to handle custom response formats:

   class CustomResponse extends SalesforceResponse {
       public function getCustomData() {
           return json_decode($this->body, true)['custom_field'];
       }
   }
   

2. Mocking for Tests Use SalesforceConnectionMock (if available) or mock HTTP client:

   $mockHandler = new \Http\Mock\Handler();
   $mockHandler->append(new \Http\Mock\Response(200, [], '{"success": true}'));
   $client = new \Http\Adapter\Guzzle6\Client($mockHandler);
   $connection = new SalesforceConnection($config, $client);
   

3. Extending API Clients Create a wrapper for domain-specific logic:

   class AccountService {
       protected $connection;
   
       public function __construct(SalesforceConnection $connection) {
           $this->connection = $connection;
       }
   
       public function createAccount(array $data) {
           return $this->connection->create('/services/data/v56.0/sobjects/Account', $data);
       }
   }
   

4. Webhook Handling For Salesforce Platform Events, extend SalesforceConnection to listen to webhooks:

   $connection->subscribeToPlatformEvents('AccountChangeEvent', function ($payload) {
       // Handle event.
   });
   

Configuration Quirks

• Login URL

  • Use https://test.salesforce.com for sandbox environments.
  • For custom domains, append /services/Soap/u/XX.X (e.g., https://yourdomain.my.salesforce.com).

• OAuth vs. Username-Password

  • Prefer OAuth for production (use SalesforceOAuthConnection from phpforce/oauth).
  • Username-password flow is simpler for testing but less secure.

• API Version

  • Defaults to v56.0. Check Salesforce API Versions for compatibility.