Config Reader Laravel Package

Technical Evaluation

What the package is. platformsh/config-reader is a single-purpose, dependency-free PHP helper (namespace Platformsh\ConfigReader\Config) that decodes the base64-encoded JSON blobs Platform.sh injects into the runtime environment — PLATFORM_RELATIONSHIPS, PLATFORM_ROUTES, PLATFORM_APPLICATION, PLATFORM_PROJECT, PLATFORM_ENVIRONMENT — and exposes them through typed accessors (getRelationship(), getRoutes(), getPrimaryRoute(), getApplicationName(), isValidPlatform(), and DSN-formatting helpers for PDO/Redis). It does no caching, no validation beyond decode, and no framework integration.

Architecture fit. Good for what it is: a thin environment adapter, not a framework. In a Laravel codebase the correct placement is inside config/*.php files (or a single config/platform.php shim), so that service credentials are resolved once at bootstrap and then flow through Laravel's normal config pipeline. It is not a substitute for a service container binding, a connection factory, or a multi-cloud abstraction. TPM framing: treat it as a 200-line vendor shim, not as an architectural component.

Integration feasibility. High on Platform.sh/Upsun, effectively zero elsewhere. Concrete strengths:

• Avoids Laravel's env() parsing quirks — base64 payloads with +, /, = padding and embedded JSON are read via getenv()/$_ENV superglobals rather than Dotenv's value normalization. This is the main technical reason to prefer it over hand-rolled env('PLATFORM_RELATIONSHIPS').
• Provides consistent relationship shape regardless of service type (MySQL, PostgreSQL, Redis, Solr, Elasticsearch, RabbitMQ), so config/database.php stays readable.
• MIT licensed, vendor-published, small and auditable in an afternoon.

Technical risk.

• Vendor coupling. Values only exist on Platform.sh/Upsun infrastructure. Every call site implicitly assumes that platform; unmanaged fallbacks are the team's responsibility, not the package's.
• Adoption signal. 22 stars, effectively no downstream dependents, and a single maintainer path. That is normal for a vendor utility but means near-zero external code review, and bus factor is the platform vendor's own release cadence.
• Silent failure shape. Missing relationships and malformed base64 generally surface as null/empty rather than exceptions, so misconfiguration can degrade into a confusing "database connection refused" rather than a precise bootstrap error.
• Config-cache interaction. Once php artisan config:cache has run, relationship values are frozen into the artifact. That is acceptable for immutable deploys but must be verified against the deploy lifecycle: if credentials rotate without a redeploy, the cached config is stale. This is the single highest-probability production incident vector.
• Long-running processes. Queue workers and Octane workers hold resolved config in memory; ensure workers are restarted on deploy so rotated relationship endpoints are picked up.

Key questions for the team.

1. Is Platform.sh/Upsun a committed multi-year platform choice, or a stopgap? If stopgap, quarantine the dependency behind one adapter class from day one.
2. Does the Laravel bridge (platformsh/laravel-bridge) already cover our needs, making direct use of this package redundant?
3. Do we run config:cache at build or at deploy, and are all PLATFORM_* values we consume actually populated at that phase?
4. Which PHP/Laravel versions must we support, and does the pinned release cover them?
5. Who owns the internal wrapper, and what is the exit plan (swap to plain env vars / Secrets Manager) if we migrate?

Integration Approach

Stack fit. Laravel-native in mechanics, PaaS-specific in semantics. The reader should be confined to configuration resolution:

Recommended shape. Do not scatter Config::getRelationship() calls across a dozen config files. Introduce one config/platform.php (or App\Support\PlatformRelationships) that:

• returns early with null when Config::isValidPlatform() is false, so local/Docker/CI uses ordinary .env values;
• normalizes each relationship into a plain array (host, port, database, username, password);
• throws a clear, named exception when a required relationship is absent — converting the package's silent null into a fail-fast bootstrap error;
• exposes platform.database.* etc., so application code never imports the vendor class directly.

That single decision converts an unbounded lock-in surface into a one-file swap and makes the exit plan a day of work rather than a sprint.

Migration path (sequenced).

1. Guard first. Add the wrapper and make every config file read from it; confirm local dev, Docker, and CI behave identically to today before any Platform.sh wiring exists.
2. Convert one service. Start with Redis/cache — easiest to validate and fastest to roll back.
3. Convert the database. Validate on a preview environment with the real relationship shape, not a mocked array.
4. Convert mail/object storage/search last; these have the longest feedback loop when broken.
5. Codify. Add a boot-time smoke test or deploy hook that asserts every required relationship resolves, so a missing service fails the deploy rather than the first request.
6. Cut over with a documented rollback: revert the wrapper to pure env reads.

Compatibility considerations.

• Pin an exact version in composer.json and commit composer.lock; low-traffic vendor packages do not warrant floating constraints.
• Verify PHP version support against the oldest runtime we operate (the package has historically tracked modern PHP; don't assume PHP 7.x).
• Confirm behaviour under Octane/Swoole: relationship values are read once at worker boot — fine, provided workers restart on deploy.
• Confirm config:cache timing against the platform's build-vs-deploy environment variable availability; run one deliberate test in a preview environment rather than reasoning about it.

Operational Impact

Maintenance. Low ongoing cost — the package's surface area is small and stable, and releases are infrequent (latest 2025-02-25). The real maintenance burden is not the code but the wrapper and the deploy-time validation around it, which we own regardless of whether we adopt this package.

Support. Upstream support is effectively the platform vendor's documentation and issue tracker; there is no meaningful third-party community to lean on given the adoption numbers. For a TPM this argues for: pinning, a local fork or vcs mirror if the dependency is judged critical-path, and a named internal owner for the wrapper.

Scaling. Negligible runtime cost. All reads happen during bootstrap; there is no per-request overhead, no I/O, no external call. Scaling risk is entirely environmental (relationship limits, service plan sizing), not attributable to this package.

Failure modes to design against.

• Missing or renamed relationship → silent null → confusing downstream connection error. Mitigate with the fail-fast wrapper.
• Malformed base64/JSON (truncated env var, quoting mishandling) → decode failure at bootstrap. Mitigate with the same explicit exception path and a boot smoke test.
• Stale config cache after credential rotation → auth failures that look like a platform incident. Mitigate by tying cache regeneration to the deploy hook and validating in preview.
• Long-running workers holding pre-rotation endpoints. Mitigate by restarting workers on deploy.
• Local/production drift — the wrapper's non-platform branch is the least-exercised code path. Mitigate by keeping local .env values structurally identical to the normalized relationship array.
• Accidental secret exposure — dumping the decoded relationship array into logs or a debug page. Mitigate with a lint/CI check or a #[SensitiveParameter]-style convention in the wrapper.

Ramp-up. Low. A mid-level Laravel engineer can read the whole package and wire the first service in an afternoon; the wrapper, guard, and fail-fast behaviour are a one-to-two-day task. Realistic rollout estimate: 2–4 engineering days for a typical Laravel app with database, Redis, and one additional backing service, plus half a day of preview-environment validation. No specialist platform knowledge is required beyond understanding how Platform.sh exposes relationships.

Recommendation. Adopt it — but only behind a single internal adapter, pinned, with fail-fast validation and a documented exit path. The package earns its place by solving one real problem (safe decoding of base64 relationship payloads) that hand-rolled env parsing gets wrong; it does not earn a place in application code, and the low adoption numbers make the wrapper mandatory rather than optional.