Ecologi Laravel Package

Technical Evaluation

Architecture fit

Classify this as a thin vendor adapter, not a platform component. It owns authentication, request construction, and response hydration against the Ecologi REST API — no persistence, no retry policy, no spend controls, no business rules. That is a favorable shape for a program: the blast radius is small, and behind an internal ClimateImpactService interface it becomes replaceable without touching domain code.

The TPM-relevant nuance is that the write endpoints (plant trees, purchase offsets) cross a financial transaction boundary. Every successful call spends real money, making this a payments-adjacent dependency wearing the costume of an ordinary HTTP client. Program plans must budget for spend authorization, idempotency, audit logging, and reconciliation as named workstreams on our side, not as things that arrive "for free" with the library. Read paths (impact totals, community statistics) carry none of that weight and are the correct starting point.

Also scope explicitly: Ecologi is a vendor selection, not a library selection. composer require implicitly chooses our climate-action partner — pricing, project portfolio, certification standards, and disclosure posture all follow. That decision deserves its own review with procurement and legal, and it should not arrive as a side effect of adopting a convenient dependency.

Integration feasibility

High and cheap. Composer install, publish config, set an API key, resolve the facade — hours for read paths, a few days for a hardened write path. The narrow surface is a program-level asset because it makes both fallbacks realistic and costable in days rather than sprints: fork the code into the org, or reimplement against Guzzle/PSR-18 directly. Being wrong is cheap, which is itself sufficient justification to proceed.

The binding constraints are prerequisites, not engineering effort: an Ecologi account, a funded balance, API credentials scoped with a spend limit, a named owner for that key, and a commercial decision that Ecologi is the vendor we intend to represent to customers. Those are TPM-owned gates and should run in parallel with, never after, the technical spike.

Technical risk

Dominant risk is lifecycle and supply chain, not complexity. Zero dependents, no meaningful star count, single maintainer — assume we are the first serious adopter and plan to own a fork from day one. Read the score tension precisely: the capability is valuable, the code is not the moat. The moat is the Ecologi account, API access, and commercial relationship.

Key questions

1. Are the pricing, rate limits, and commercial terms at our expected volume acceptable, and who signs that off?
2. Do the purchase endpoints support idempotency keys — or do we own double-spend prevention entirely?
3. What is the package's PHP/Illuminate support matrix versus our runtime, and does the targeted API version match Ecologi's current API?
4. Who authorizes spend, and what caps and approval workflow apply per environment?
5. Is the license permissive, and what is our internal disclosure path for a fork we maintain?
6. What must we persist ourselves so reporting survives an exit from Ecologi as a vendor?

Integration Approach

Stack fit

Composer plus Laravel auto-discovery fits a monolith or a dedicated sustainability service equally well; non-Laravel PHP services consume the underlying client without the facade. Do not bridge languages for an HTTP wrapper — if we are not on PHP, call the REST API directly and this package is irrelevant to the decision.

Scope insertion points as separate deliverables, not one "sustainability" epic: post-purchase tree-planting hooks, customer-facing impact widgets (receipts, offset badges, profile counters), ESG/CSR reporting jobs, and internal admin tooling for spend and totals. Each is independently shippable, independently flaggable, and independently abortable — which is the whole point of a cheap adapter.

Migration path

There is no installed base anywhere, so no migration debt to inherit and no organizational lock-in to negotiate. Greenfield adoption should route through an internal interface with this package as the first adapter. If Ecologi is already being called via raw cURL somewhere, migrate endpoint-by-endpoint starting with reads, and hold writes until the ledger exists.

Compatibility

This is the gate before committing engineering time: confirm the PHP version constraint against our runtime, the Illuminate support matrix, Guzzle/PSR-18 versions, and that the targeted API version still matches Ecologi's current API. A stale constraint is acceptable — fork it — but it must be known before it enters a release plan. Discovering it mid-framework-upgrade converts a routine task into a blocked migration and an inflated estimate.

Sequencing

1. Discovery spike (1–2 days). Sandbox install, authenticate, reads only. Deliverable: confirmation the API is live and the client runs on our stack, plus a coverage map of available versus needed endpoints.
2. Vendor and commercial review (parallel, TPM-owned). Pricing, project mix, certification claims, contract terms, exit plan. Reads may proceed; write-path funding should not commit until this clears.
3. Fork to org. Vendor the code, add CI, pin versions, write a minimal contract-test suite, name an owner. Do this up front, not after an incident.
4. Internal interface plus observability. Wrap behind ClimateImpactService; log requests, latency, error classes. Publish the seam so no call site touches the package directly.
5. Harden write paths. Idempotency ledger, spend caps, approval workflow, dead-letter queue, reconciliation job, fail-soft contract. Nothing customer-facing spends money before this ships.
6. One product, one market. Ship a single experiment behind a flag with a measurement plan, then decide on breadth.

Operational Impact

Maintenance

Assume we own this permanently. The upstream is a single maintainer with no adoption signal; treat the dependency as reference code we happen to install. Pinning, vendoring, and a named owner are the cost of entry — realistically a fraction of an engineer per quarter once the fork is stable, plus unbudgeted time if Ecologi changes its API. Budget half a day to read the source: at this size that is cheaper than any other form of evaluation.

Support

There is no vendor-backed support, SLA, or security disclosure path for the client. Ecologi may support its API commercially — that is a separate contract term to negotiate and confirm, and it does not extend to the wrapper. Internal support burden lands on whoever owns the fork; make that a named role, not a collective assumption.

Scaling

Throughput is not the constraint; money is. Scale means more write calls, which means larger spend, more partial failures, and more reconciliation surface. Practical safeguards: queue spend off the request path, batch where the API permits, enforce per-environment and per-period caps, and alarm on spend-rate anomalies rather than on request volume. Read paths scale trivially and can be cached aggressively for dashboards and receipts.

Failure modes

The genuinely dangerous one is not an outage — it is a successful call whose response we lose, producing an untracked tree or an orphaned charge. Also plan for: Ecologi 5xx during checkout (must fail soft), exhausted balance causing silent write failures, revoked or expired credentials, rate limiting under batch jobs, and schema drift breaking response hydration. Each needs a defined behavior, an alert, and an owner before the write path goes live. Persisting our own impact records is non-negotiable — reporting that depends on the vendor's dashboard is reporting we do not control.

Ramp-up

Engineering ramp is trivial; domain ramp is not. The real learning curve is tCO₂e units, the distinction between tree planting and carbon offset products, Ecologi's reporting semantics, and what we are comfortable publishing publicly. Once a number appears in an annual report or investor deck it carries disclosure risk, and the caveats outlive the figure. Schedule that as product work with legal review, not as a footnote to the integration ticket.

Bottom line for the program: adopt it, but adopt it as a replaceable adapter behind our own interface, with the vendor decision made deliberately and separately. The package collapses build cost to near zero, which reframes the question from "can we afford to test whether customers care?" to "do we believe they do?" — answer that with a prototype, not a business case.