Laravel Salesforce Laravel Package

Technical Evaluation

Architecture fit

• Package is a thin, config-driven API client for Salesforce (SOQL query, SOSL search, sObject find/create/update/delete/describe) — it sits as an infrastructure adapter behind a domain service, not as a full ORM-style abstraction. That is the right shape for Laravel: bind a client interface in a service provider, resolve credentials from config, and keep Salesforce DTOs out of domain code.
• Authentication is hardcoded to the OAuth2 password grant with a cached access token and automatic re-authentication on expiry. This is the single most consequential architectural decision in 1.0.0. It means the package is inherently a single-identity, system-to-system integration, not a per-user or multi-tenant one. Any requirement for "act as the logged-in Salesforce user" or per-customer org connection is out of scope and would require a fork or wrapper.
• No refresh-token flow is possible with the password grant (Salesforce does not issue refresh tokens for it), so the package's re-auth strategy is "replay username/password/security token." That is workable but fixes a long-lived privileged credential in the app's secret store with no rotation grace period.
• Token caching depends on Laravel's cache abstraction. Cache store choice (array vs. file vs. Redis) materially changes behavior across queue workers and horizontally scaled pods — a design detail that will surface as a production incident if not reviewed up front.

Integration feasibility

• Composer install plus a publishable config file is the expected Laravel ergonomics; feasibility for a first spike is low-effort (hours). Realistic effort is dominated by Salesforce-side setup, not PHP: Connected App creation, OAuth scopes (api), IP relaxation, and the org's login policy.
• Blocking dependency risk: Salesforce enforces MFA for interactive/API logins under most org policies. Password grant with a username/password/security-token is frequently blocked unless a dedicated API-only integration user is exempted from MFA and the Connected App permits the flow. Confirm this with the Salesforce admin before committing to the package.
• Credentials belong in a secrets manager (AWS Secrets Manager, Vault, Doppler) injected as env vars — not in .env committed anywhere, and not in the database. Note that the security token is appended to the password; mishandling that concatenation is a common source of invalid_grant.
• Not present in 1.0.0 and each is a real gap: query pagination (nextRecordsUrl / queryMore beyond the 2,000-record batch), Bulk API 2.0 for volume writes, Composite API for multi-object transactions, retry/backoff on 5xx and REQUEST_LIMIT_EXCEEDED, structured mapping of Salesforce error codes (INVALID_FIELD, MALFORMED_QUERY, ENTITY_IS_DELETED), and any mocking/faking helper for tests. Assume you build the test double yourself.

Technical risk

• Credential blast radius (high). A single privileged credential grants the package's full CRUD surface across every object the integration user can touch. Compromise of one app server yields broad org access. Mitigate with a least-privilege integration user, a dedicated Connected App, and object/field-level permission scoping.
• Password rotation is a breaking operational event (high). Because there is no refresh token, rotating the integration user's password invalidates the cached token and every in-flight consumer until the new secret propagates and the token cache is flushed. This must be a scripted, coordinated runbook.
• Thundering herd on re-auth (medium). With N queue workers hitting an expired token simultaneously, each may attempt a fresh password grant. Salesforce enforces concurrent session and login-rate limits; uncoordinated re-auth can produce invalid_grant / lockout noise. Needs a cache lock around token acquisition.
• API version not described (medium). If the API path is hardcoded rather than configurable, you inherit Salesforce's ~3-version retirement window and pin your upgrade cadence to the package's release cadence.
• Maturity risk (medium). 1.0.0 initial release with no prior assessment, no stated test coverage, no changelog history. Treat as unproven for production write paths; read the source before trusting delete semantics (hard delete vs. recycle bin, ALL OR NONE behavior, partial-success handling in multi-record calls).

Key questions for the maintainer/vendor

1. Which Salesforce API version is targeted, and is it configurable?
2. Does the token cache use Cache::lock/atomic operations to prevent concurrent re-auth storms?
3. How are Salesforce error responses surfaced — typed exceptions, raw response passthrough, or silent nulls?
4. Is Sforce-All-Or-None / partial-success handling supported for multi-record create/update?
5. What is the test story — is there a fake/stub client, or are tests expected to hit a sandbox?
6. Is there a roadmap for JWT bearer flow or refresh-token support (the only durable fix for the rotation problem)?
7. What is the support model — single maintainer, issue SLA, security disclosure process?

Integration Approach

Stack fit

• Laravel 9/10/11 with Guzzle/Http facade is the natural home; the package idiom (service provider + config + facade) maps cleanly to Laravel's container and should be bound to an interface (SalesforceClientInterface) so it can be swapped or faked in tests.
• Pair with queued jobs for all write operations — synchronous create/update from a web request couples user latency to Salesforce response time and API-limit headroom.
• Complementary, not competing: use this package for record-level CRUD and SOQL/SOSL reads; add a separate Bulk API 2.0 path (or a managed ETL) for anything above roughly 10k records/day.

Migration path

• Greenfield: no migration, but define the boundary now — one adapter class per Salesforce object/domain, no Sforce calls from controllers.
• If replacing hand-rolled Http:: calls, wrap the existing code behind the same interface first, then swap the implementation; keeps the change reversible.
• If a prior integration used per-user OAuth, this package is a downgrade in identity model — flag that explicitly before adopting.

Compatibility

• Confirm PHP and Laravel version constraints against the platform's supported matrix before installing.
• Confirm the target org's API version is not on Salesforce's retirement list.
• Confirm Connected App policy: IP ranges, permitted users, session timeout, and whether "Enable OAuth Settings" with password flow is allowed.
• Verify cache driver supports the TTL and locking semantics used (Redis preferred over file/array for multi-worker deployments).

Sequencing

1. Week 1 — Feasibility spike. Sandbox org, integration user, Connected App; authenticate and run one SOQL query and one create via tinker. This de-risks MFA and Connected App policy before any code lands.
2. Week 1–2 — Security review. Least-privilege profile, secret storage, token caching strategy, audit logging of outbound calls.
3. Week 2–3 — Adapter layer + fakes. Interface binding, error mapping, one vertical slice (e.g., read-only sync) in staging.
4. Week 3–4 — Write path behind queues. Create/update/delete with idempotency keys and retry policy; add nextRecordsUrl pagination if reads exceed one batch.
5. Week 4 — Operational readiness. Password-rotation runbook, API-limit monitoring, alerting on auth failures, then production with a feature flag and one non-critical object.

Operational Impact

Maintenance

• Low direct code maintenance (thin client), but perpetual credential maintenance: password rotation, security-token regeneration on IP change, Connected App certificate and policy review, and API version bumps tied to Salesforce's retirement schedule.
• Track the package's release cadence; at 1.0.0 with a single major version, expect breaking changes and pin to a minor range with a tested upgrade window.

Support

• Escalation splits three ways: package defects (maintainer), org configuration and permissions (Salesforce admin), and credential/secret plumbing (platform/DevOps). Identify all three owners before go-live; the most common production incident class here is an auth failure that no single team owns.
• Establish a support SLA expectation with the package maintainer, or budget for the two-file fork if the project becomes load-bearing.

Scaling

• Horizontal scale is fine for reads but stresses auth: more workers mean more concurrent token checks and a wider window for thundering-herd re-auth. Use Redis-backed cache with locking and a token refresh margin (e.g., re-auth at 80% of lifetime).
• Throughput ceiling is Salesforce API limits, not Laravel: 100k calls/24h for Enterprise (15k for Developer), plus concurrent long-running request caps. Instrument per-object call counts and put a hard budget on the package's usage before traffic grows into the limit.
• Large reads will hit the 2,000-record query batch; without pagination support, plan object-level reads that stay under it or add pagination in your adapter.

Failure modes to design for

• invalid_grant on password rotation or security-token mismatch → hard outage for all consumers; needs pre-rotation dual-secret support or a maintenance window.
• MFA enforcement turned on org-wide → total auth failure; monitor Salesforce trust/security advisories.
• INVALID_SESSION_ID mid-flight on org maintenance or session revocation → in-flight job failure; retries must be idempotent to avoid duplicate upserts.
• REQUEST_LIMIT_EXCEEDED → cascading queue backlog; add backoff, a circuit breaker, and a dead-letter queue rather than tight retries.
• Token cache eviction (Redis flush/restart) → mass re-auth storm; acceptable if locking is in place, otherwise a self-inflicted outage.
• Silent partial success on multi-record writes if AllOrNone is unset → data drift requiring a reconciliation job.

Ramp-up

• A Laravel developer is productive in half a day on the API surface (it is conventional query/CRUD), but safe usage requires Salesforce literacy that most PHP teams lack: SOQL syntax and relationship queries, object/field permissions, API limits, and OAuth policy. Budget for a Salesforce admin or architect as a part-time partner for the first month.
• Write a short internal runbook at adoption time covering: how to rotate credentials, how to flush the token cache, how to read an API-limit dashboard, and what to do on invalid_grant. Without it, the first auth incident consumes the team's goodwill for the package.