README

A Laravel package for seamless Salesforce API integration, providing an elegant way to interact with Salesforce's REST APIs.

Features

🚀 Simple and intuitive API
🔑 Flexible authentication options
🔒 Supports custom Apex class authentication
🌐 OAuth 2.0 integration
📦 Automatic token management
🔐 Optional certificate-based authentication
⚡ Request/Response interceptors

Requirements

PHP 8.1 or higher
Laravel 10.0 or higher
Composer 2.0 or higher

Version Compatibility

Installation

Install the package via composer:

composer require antogkou/laravel-salesforce

Publish the configuration:

# Publish config file
php artisan vendor:publish --tag="salesforce-config"

# If using certificate authentication
php artisan vendor:publish --tag="salesforce-certificates"

Configuration

Required Configuration

Add these essential environment variables to your .env file:

# Required: Salesforce OAuth Credentials
SALESFORCE_CLIENT_ID=your-client-id
SALESFORCE_CLIENT_SECRET=your-client-secret
SALESFORCE_USERNAME=your-username
SALESFORCE_PASSWORD=your-password
SALESFORCE_SECURITY_TOKEN=your-security-token
SALESFORCE_APEX_URI=https://salesforce-instance.com/services/apexrest

# Optional: Default endpoints (these defaults are for sandboxes)
SALESFORCE_TOKEN_URI=https://test.salesforce.com/services/oauth2/token

Optional: Custom Apex Authentication

If your Salesforce Apex classes implement custom application-level authentication, you can configure it using:

# Optional: Custom Apex Authentication
SALESFORCE_APP_UUID=your-app-uuid
SALESFORCE_APP_KEY=your-app-key

This adds x-app-uuid and x-app-key headers to your requests, which you can validate in your Apex classes:

@RestResource(urlMapping='/your-endpoint/*')
global with sharing class YourApexClass {
    @HttpGet
    global static Response doGet() {
        // Validate application credentials
        String appUuid = RestContext.request.headers.get('x-app-uuid');
        String appKey = RestContext.request.headers.get('x-app-key');
        
        if (!YourAuthService.validateApp(appUuid, appKey)) {
            throw new CustomException('Invalid application credentials');
        }
        
        // Your endpoint logic...
    }
}

Optional: Certificate Authentication

For certificate-based authentication:

# Optional: Certificate Authentication
SALESFORCE_CERTIFICATE=cert.pem
SALESFORCE_CERTIFICATE_KEY=cert.key

Optional: Default User Context

# Optional: Default User Email
SALESFORCE_DEFAULT_USER_EMAIL=default@example.com

Basic Usage

use Antogkou\LaravelSalesforce\Facades\Salesforce;

// Basic request
$response = Salesforce::get('/endpoint');

// With custom user context
$response = Salesforce::setEmail('user@example.com')
    ->get('/endpoint');

// With custom headers
$response = Salesforce::post('/endpoint', $data, [
    'Custom-Header' => 'Value'
]);

Advanced Usage

// Set custom user email for the request
$response = Salesforce::setEmail('user@example.com')
    ->get('/endpoint');

// With query parameters
$response = Salesforce::get('/endpoint', [
    'limit' => 10,
    'offset' => 0
]);

// With custom headers
$response = Salesforce::post('/endpoint', $data, [
    'Custom-Header' => 'Value'
]);

// Handling responses
$response = Salesforce::get('/endpoint');

if ($response->successful()) {
    $data = $response->json();
    $status = $response->status();
} else {
    $error = $response->json('error');
}

Error Handling

use Antogkou\LaravelSalesforce\Exceptions\SalesforceException;
use Illuminate\Http\Client\RequestException;

try {
    $response = Salesforce::get('/endpoint');
} catch (SalesforceException $e) {
    // Handle Salesforce-specific errors
    $details = $e->getDetails(); // Array of error details
    $status = $e->getCode();     // HTTP status code
} catch (RequestException $e) {
    // Handle HTTP client errors
}

Testing

composer test

Logging

The package automatically logs all API errors and failed requests. Logs include:

Request method and URL
Request data
Response status and body
Laravel route information
Stack trace for debugging

Contributing

Fork the repository
Create your feature branch: git checkout -b feature/my-new-feature
Commit your changes: git commit -am 'Add new feature'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security-related issues, please email [your-email] instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

Please review our security policy for more information.

Credits

All Contributors

License

The MIT License (MIT). Please see License File for more information.

antogkou / laravel-salesforce

Maintainers

Details