README

Eloquent Salesforce Objects

⚠️ WORK IN PROGRESS

This package is currently under active development and should be considered alpha/beta quality. While it is functional and tested, the API may change, and there may be undiscovered bugs.

Use at your own risk in production environments. We recommend thorough testing in development/staging environments before deploying to production. Please report any issues you encounter!

Eloquent Salesforce Objects is a powerful Laravel package built on top of the excellent omniphx/forrest package. It provides an Eloquent-style interface for working with Salesforce objects, allowing you to define Salesforce models just like Eloquent models and interact with your Salesforce data using familiar Laravel conventions.

Features

Eloquent-Style Models - Define Salesforce objects using familiar Laravel model syntax
CRUD Operations - Create, read, update, and delete Salesforce records
Relationships - Support for hasMany, belongsTo, and hasOne relationships
Aggregate Functions - COUNT, SUM, AVG, MIN, MAX support
Pagination - Built-in pagination with Laravel's paginator
Bulk Operations - Efficient bulk insert, update, and delete operations
Automatic Authentication - Seamless OAuth token management via omniphx/forrest
Query Caching - Intelligent caching with surgical record-level invalidation
Webhook Support - Real-time cache invalidation via Salesforce Change Data Capture
Field Mapping - Automatic conversion between Laravel and Salesforce naming conventions (optional)

Requirements

PHP 8.4 or higher
Laravel 12.0 or higher
Salesforce Account with API access enabled
omniphx/forrest - Salesforce REST API client (installed automatically as a dependency)

Quick Start

Installation

composer require daikazu/eloquent-salesforce-objects

Configuration

Before using this package, you must configure the omniphx/forrest package, which handles Salesforce authentication and API communication.

Publish the Forrest configuration:

php artisan vendor:publish --provider="Omniphx\Forrest\Providers\Laravel\ForrestServiceProvider"

Configure your Salesforce credentials in config/forrest.php and .env
See the Forrest documentation for detailed setup instructions

Optionally publish this package's configuration:

php artisan vendor:publish --tag="eloquent-salesforce-objects-config"

For complete setup instructions, see our Installation Guide.

Basic Usage

Define a Salesforce model and query data using familiar Eloquent syntax:

use Daikazu\EloquentSalesforceObjects\Models\SalesforceModel;

class Account extends SalesforceModel
{
    protected $table = 'Account';
    protected $fillable = ['Name', 'Industry', 'AnnualRevenue'];
}

// Query with familiar Eloquent syntax
$accounts = Account::where('Industry', 'Technology')
    ->orderBy('Name')
    ->get();

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

// Relationships
$account->contacts; // hasMany
$contact->account;  // belongsTo

Check out the Quickstart Guide for detailed examples and step-by-step instructions.

Installation & Configuration

For detailed installation and configuration instructions, see:

Installation Guide - Complete setup walkthrough
Configuration Reference - All configuration options
omniphx/forrest Documentation - Salesforce API client setup

Documentation

Getting Started

Installation Guide - Detailed installation and setup instructions
Configuration - Configure Salesforce connection and package options
Quickstart Guide - Get up and running in 5 minutes

Core Concepts

Models - Creating and configuring Salesforce models
Querying Data - Building SOQL queries with the query builder
CRUD Operations - Creating, reading, updating, and deleting records
Relationships - Defining and using relationships between objects

Advanced Features

Bulk Operations - Efficient bulk insert, update, and delete
Query Caching - Intelligent caching with record-level invalidation
Webhook Integration - Real-time cache invalidation with CDC
Aggregate Functions - Using COUNT, SUM, AVG, MIN, MAX
Pagination - Paginating large result sets

Reference

Configuration Reference - All configuration options explained
Troubleshooting - Common issues and solutions

Testing

Run the test suite:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

Need help? Check out the documentation or open an issue.

daikazu / eloquent-salesforce-objects

Maintainers

Details