Product Decisions This Supports
- Build vs. buy for Salesforce connectivity. This package covers the "commodity" 80% of a Salesforce integration — authenticated SOQL reads, SOSL free-text search, and single-record sobject CRUD plus describe — so a team can skip writing and maintaining an OAuth2 token lifecycle and HTTP client from scratch. That is typically 2–4 engineer-weeks of work plus ongoing maintenance, and it is not differentiating for most products.
- Roadmap sequencing for Salesforce-adjacent features. Because reads, searches, and record writes are available on day one, features such as "show the customer's open Salesforce opportunities in our admin," "create a Case from a support form," or "let ops search Accounts/Contacts by name" become small, incremental stories rather than a platform initiative. Conversely, anything requiring bulk data movement, real-time events, or relationship-heavy query building is not enabled by this release and must be scoped separately.
- Which integrations to greenlight now vs. defer. Good fit: internal tools, back-office ops surfaces, low-to-moderate volume sync, single-tenant or per-customer-connected-org scenarios where a named integration user's credentials can be provisioned. Poor fit: customer-facing multi-tenant OAuth ("connect your Salesforce"), high-volume ETL, or event-driven sync — see the next section.
- Architecture and security sign-off. The choice of OAuth2 password grant is a product-level decision, not just a technical one: it means the product stores a Salesforce username and password (or a dedicated integration user's credentials) rather than obtaining per-user consent. That affects your security questionnaire answers, your SOC 2 / ISO 27001 evidence, your data-processing agreement scope, and enterprise deal velocity. Expect security review to push back; decide in advance whether you accept that or require the vendor to add JWT bearer / web-server flow.
- Support and reliability commitments. Cached tokens plus automatic re-authentication means token expiry and revoked-credential scenarios are handled, which reduces the "integration silently broke overnight" class of incident. But automatic re-auth also means a bad credential can retry in a loop — worth a decision on alerting and rate-limit backoff before you promise SLAs.
- Total cost of ownership comparison. If the alternative is a commercial iPaaS or a mature Salesforce ORM/query-builder package, this release is thinner: no query builder or relationship hydration, no Bulk API, no Composite API, no Platform Events/CDC, no migrations or model mapping. The decision is "narrow and cheap" vs. "broad and heavier" — this release supports choosing narrow when the use cases above are the actual roadmap.
When to Consider This Package
Consider adoption when most of the following hold:
- Your Salesforce usage is read-mostly or low-volume writes: dashboards, admin lookups, search boxes, creating a handful of records per user action — not nightly 100k-record syncs.
- You can provision a dedicated Salesforce integration user with a static username/password and the minimum permission set, ideally in a sandbox first. If your org enforces strict MFA on all interactive logins, confirm the integration-user exemption before committing — Salesforce has been tightening password-grant viability.
- You need SOQL/SOSL pass-through, not a full ORM. Teams that want
Model::where(...) ergonomics over sObjects, relationship traversal in one call, or schema migrations should look at richardkeep/eloquent-salesforce-style packages instead.
- The integration is internal-facing or single-tenant. Multi-tenant SaaS where each customer connects their own org needs the authorization-code or JWT bearer flow — this package does not offer that, so look elsewhere (or budget for a fork/upstream contribution).
- You value a small dependency surface over breadth. One class per concern, no queue workers, no service provider magic to reason about — easier to audit and to replace later.
- v1.0.0 signals API stability by semver, not maturity. There is no track record yet: no published adoption, no security disclosure process, and no evidence of a maintained test suite in the release notes. Vet the repository (CI status, issue responsiveness, release cadence, licence) before making it load-bearing. Budget for the possibility that you fork it — the surface area is small enough that this is cheap.
- Look elsewhere if you need: Bulk API 2.0 for large volumes, Composite/Composite Graph for transactional multi-object writes, Platform Events or Change Data Capture for near-real-time sync, Metadata/Tooling API for org configuration, or Salesforce API limit governance (per-org 24h request budgets, concurrent request caps) baked in. None of that is here, and API-limit exhaustion is the most common way Salesforce integrations fail in production.
How to Pitch It (Stakeholders)
For executives (one paragraph). We evaluated a Laravel package that gives us authenticated, ready-made access to Salesforce — queries, search, and standard record operations — with token caching and automatic re-authentication handled. It removes the plumbing work (roughly two to four engineer-weeks plus ongoing maintenance) that we would otherwise spend before shipping any Salesforce-adjacent feature, and it costs us only a Composer dependency. It is deliberately narrow: it is the right foundation for admin tooling, ops workflows, and search/create/update use cases, and the wrong tool for bulk data migration or real-time event sync, which would need a separate decision. The one item requiring your awareness is authentication: it uses the username/password OAuth flow against a dedicated integration user, which is simpler to operate but is being deprecated in favour of per-user consent flows. That is acceptable for internal tools where we control the integration user; it would need revisiting before we offer "connect your Salesforce" to customers.
For engineering. This is a thin, low-coupling wrapper: SOQL and SOSL pass-through, sobject find/create/update/delete/describe, OAuth2 password grant with a cached token and automatic re-auth on expiry. It is v1.0.0 with no prior assessment, so treat it as low-risk-to-try and medium-risk-to-depend-on — spike it behind an interface of our own so we can swap it for the Bulk API or a fuller ORM later without touching call sites. Two things to confirm before we build on it: (1) how it behaves on a 401 mid-flight under concurrency, so we don't get re-auth stampedes, and (2) that we surface Salesforce API-limit errors rather than swallowing them. Neither is exotic; both are the difference between a clean pilot and a 2 a.m. page.
For security and compliance. Credentials for a dedicated Salesforce integration user will live in our secret store and be read by the application; token caching means the credential is used rarely, which is good, but it also means a rotation can go unnoticed until the cache expires. We should confirm MFA exemption and IP restrictions on that integration user, log every sobject write for audit, and record the password-grant dependency as a known risk with a trigger for migration (Salesforce deprecation timeline, or the first customer-facing OAuth requirement — whichever comes first).
Recommendation. Approve a time-boxed spike (one engineer, roughly a week) against a sandbox with a non-production integration user, targeting one concrete internal workflow. Gate broader adoption on the spike plus a repository health check; gate any customer-facing use on a different auth flow.