Salesforce Client Bundle Laravel Package

Technical Evaluation

Architecture fit — mismatch at the framework layer. Despite being evaluated as a Laravel/PHP package, localfr/salesforce-client-bundle is a Symfony bundle, not a Laravel package. It almost certainly extends Symfony\Component\HttpKernel\Bundle\Bundle and expects registration in config/bundles.php. Laravel has no bundle registry, no Kernel::registerBundles(), and no autoconfiguration hook for Bundle subclasses. Installing it into a Laravel app will pull Symfony's DI, config, and http-kernel components into the dependency graph without any code path that actually boots the bundle. Composer package discovery will not find a Laravel\ServiceProvider, so nothing is wired.

Integration feasibility — low via the bundle, moderate via its dependency. The pragmatic surface is the underlying client library it wraps (the localfr org publishes a PHP Salesforce API client independently). That library is framework-agnostic and can be bound as a singleton in a Laravel service provider with config in config/services.php. The bundle itself contributes: DI service definitions, a config tree (salesforce: base_uri, client_id, client_secret, username, password, ...), and possibly a console command. None of that transfers; the config schema is the only artifact worth reading before re-implementing it in Laravel style.

Technical risk — high, and concentrated in the adoption signal.

• 0 stars, 0 dependents, 0 downloads. No production evidence outside the author's own estate. This is an internal extraction, not a community library.
• Bus factor of one. Single-org maintenance with no visible contributor base.
• No security disclosure path. For a credential-handling package (client secrets, OAuth tokens), absence of a SECURITY.md and advisory history is a real governance gap.
• Version constraint collision. A bundle pinned to Symfony 5.x/6.x components may be uninstallable or partially overlapping with the Symfony 6/7 components Laravel 10–12 already ships.
• Mitigant: MIT license and a Jan 2025 release mean it is recent and forkable. If the underlying client library is small, vendoring it is viable.

Key questions for the vendor or a spike:

1. Which Salesforce surfaces are covered — REST only, or Bulk 2.0, Composite, Streaming/Pub-Sub, Metadata?
2. Which auth flows are implemented — username-password OAuth, JWT bearer, or refresh-token? JWT bearer is the only one acceptable for server-to-server in most enterprise orgs.
3. Is the underlying client a separate, independently installable package? That is the real dependency we would take.
4. PHP and Symfony version constraints vs. our target Laravel version.
5. Test coverage and whether tests run against a mocked HTTP client or a real sandbox org.
6. Is this bundle actively used inside Local.fr's own production, or an abandoned extraction?

Integration Approach

Stack fit. Treat the bundle as documentation, not a dependency. Add only the framework-agnostic client package to composer.json. Bind it in a dedicated SalesforceServiceProvider as a singleton, expose it behind a Salesforce facade, and map credentials from config/services.php to environment variables with config:cache compatibility in mind (no env() calls outside config files).

Migration path. If this is being lifted from an existing Symfony service, the work is mechanical: translate the bundle's YAML service definitions to a provider binding, translate the config tree to a config/salesforce.php file, and drop any Symfony console commands in favour of Artisan commands. Budget a few days, not weeks.

Compatibility. Pin explicitly and verify in a throwaway branch before committing:

• Confirm the client package's php constraint against our Laravel floor.
• Run composer why-not on Symfony component versions to detect conflicts before install, not after.
• Verify Guzzle major version alignment with whatever Laravel HTTP client or Guzzle version is already resolved.

Sequencing.

1. Spike (1–2 days): install the underlying client in a scratch Laravel app, authenticate against a Salesforce sandbox developer org, execute one SOQL query and one record create.
2. Wrapper (2–3 days): provider, config, facade, typed DTOs at the boundary, token caching.
3. Resilience layer (3–5 days): retry/backoff, 401 refresh-on-expiry, rate-limit handling, structured logging.
4. Async by default (3–5 days): queue jobs for all writes and bulk reads; nothing Salesforce-bound runs in a request cycle.
5. Production cutover against a full sandbox replica, with a feature flag and a read-only phase before enabling writes.

Operational Impact

Maintenance. Assume we own the code. With zero dependents there is no upgrade path being exercised by anyone else, so upstream regressions reach us first. Plan to fork the client into a private VCS repository or vendor it, and assign a named owner. Review quarterly for Salesforce API version deprecations — Salesforce retires REST API versions on a rolling ~3-year cadence, and a small package is unlikely to track that proactively.

Support. No commercial support, no community forum, no issue-triage track record. Internal documentation will have to be written from scratch. The Salesforce-side knowledge (Connected App setup, IP allowlisting, profile permissions, field-level security) is the larger support burden, not the PHP code.

Scaling. The binding constraint is Salesforce, not PHP. Every org is subject to a 24-hour rolling API request allocation (roughly 15,000 + per-user allowances on Enterprise), concurrent long-running request limits, and Bulk API batch sizing. A synchronous client will saturate these under load and, worse, fail inside user requests. Mandatory design points: queue all writes, cache reads, batch bulk operations, and instrument API call counts per day as a first-class metric with alerting at 80% of allocation.

Failure modes to design for explicitly:

• Token expiry mid-flight — sessions invalidate on password change, admin revocation, or timeout; the client must refresh and retry idempotently, and must not silently swallow the 401.
• REQUEST_LIMIT_EXCEEDED — treat as a throttle signal, back off, and surface to ops; never retry in a tight loop.
• Partial bulk failures — Bulk API returns per-record success/failure; a wrapper that reports job-level success will lose records silently. This is the highest-severity failure mode and needs explicit handling.
• Schema drift — Salesforce admins change fields and validation rules without notifying consumers. Validation failures will appear as runtime errors; treat Salesforce validation messages as user-facing and log them with the payload.
• Silent config breakage — credentials in env must be validated at boot, not at first call, so misconfiguration surfaces in deploy rather than in a customer's request.

Ramp-up. Two distinct skill sets are needed and should be planned separately: Laravel engineers for the provider/queue/observability work (days), and someone with Salesforce org familiarity for Connected App provisioning, sandbox strategy, object model, and SOQL (weeks if not already on the team). If no one on staff has Salesforce experience, add that as a hiring or contractor line item before committing to a timeline — it is the dominant schedule risk, well ahead of anything in this package.