Epaybg Bundle Laravel Package

Technical Evaluation

Package context and assumption: the release notes describe a v2.0.0 that (a) moves configuration files to YAML and (b) changes the default currency to EUR. The package itself is not identified in the supplied data, so the assessment below is scoped to what these two changes imply for a Laravel/PHP package and should be re-validated once the package's domain (payments, pricing, accounting, cart, FX, invoicing) is confirmed.

Architecture fit

• The YAML change is a deliberate departure from Laravel convention. Laravel's configuration contract is PHP arrays under config/, resolved via the config() repository, populated by mergeConfigFrom(), published via vendor:publish, and precompiled by php artisan config:cache. A YAML-based config layer must be loaded by the package's own service provider and either (i) mapped into the Laravel config repository at boot, or (ii) read through a bespoke config object. Option (i) is the only version that preserves config('package.key') ergonomics; option (ii) fragments the config surface and will surprise integrators.
• Introducing YAML pulls in a parser dependency (typically symfony/yaml). That is a new transitive dependency and a new failure surface on every boot. It also means config values are no longer statically analyzable, no longer type-safe, and no longer discoverable by IDE tooling or static analysis the way PHP config arrays are.
• The currency default change is an architectural signal about where money defaults live. If EUR is now the package default, any code path that relied on the implicit default (rather than an explicit configuration) silently changes behaviour. Whether that is safe depends entirely on whether currency is used for computation, storage, or display only.

Integration feasibility

• Feasible but non-trivial. The YAML layer can be wrapped: publish .yaml, parse in the provider, config()->set('package', $parsed) before dependents resolve. This is a well-trodden pattern and low technical risk if the package documents it and ships a config:cache-compatible path.
• The blocking question is config caching. If the provider parses YAML on every boot and config:cache captures the result, fine. If the package bypasses the config repository and reads YAML files at runtime, then config:cache no longer reflects the effective configuration, and production behaviour diverges from local behaviour — a classic and expensive class of incident.
• Currency default change requires an audit of every integration that did not explicitly set a currency. Any stored monetary data written under the previous default is now semantically ambiguous.

Technical risk: High

• Two breaking changes shipped in a single major. Config format changes break deployment pipelines, container images, secret injection, and any environment where config is templated or generated by tooling (Helm, Ansible, Terraform, CI templates). Teams that generate config/payments.php now generate YAML.
• Any deployment that mounts config or injects it as environment variables must be reworked end to end.
• Silent currency shift is a data-integrity risk, not merely a behavioural one: reporting, reconciliation, and downstream finance systems can be wrong without raising an error.

Key questions

1. Is the PHP config format removed entirely, or does v2.0.0 ship a deprecated-but-functional PHP path with a defined sunset?
2. Does the package still resolve configuration through the Laravel config repository, and is it verified against php artisan config:cache in CI?
3. Which YAML parser is used, and is it declared as a hard dependency with a supported version range?
4. Is currency used in arithmetic and persistence, or only in formatting? Does the change affect stored values or defaults only?
5. Is there a migration command or shim to convert existing PHP config to YAML?
6. What is the supported Laravel and PHP version matrix for v2?
7. Are monetary values persisted without an explicit currency column anywhere in the package's own migrations?

Integration Approach

Stack fit

• Moderate fit. Laravel-first packages are expected to honour Laravel conventions; YAML config is a deviation that every integrating team will notice and question. It is defensible (readability, non-PHP stakeholders editing config, ops-friendly templating) but it is not free, and the package's own documentation must carry the explanation.
• The EUR default fits European deployments naturally and misfits everyone else by default. Teams must now set currency explicitly, which is arguably better discipline but is a mandatory action item, not an optional one.

Migration path

1. Freeze and inventory. Enumerate every service that consumes the package. For each, capture the currently effective currency and the config source of truth.
2. Pin. Do not adopt v2.0.0 until the config-caching question is answered. Stay on the v1 line if it is still receiving security fixes.
3. Transcode config. Write a one-off script that reads existing PHP config and emits equivalent YAML, then diff the parsed result against the old array to prove equivalence. Do not hand-convert; the surface is too easy to get subtly wrong (nested keys, numeric strings, booleans, nulls).
4. Set currency explicitly everywhere, including in test fixtures and seeders. Treat the default as hostile. Add a boot-time assertion that fails loudly if currency is unset.
5. Verify in a staging environment with config:cache enabled. This is the acceptance gate. Compare effective config before and after caching.
6. Backfill/annotate stored monetary data with the currency it was written under, if the package persists amounts.
7. Cut over, then remove the transcode script from the pipeline and commit the YAML as the source of truth.

Compatibility

• Confirm the Laravel version matrix explicitly. Config bootstrapping changed across Laravel majors (mergeConfigFrom behaviour, provider registration, package discovery), and a bespoke YAML loader is exactly the kind of code that breaks quietly across upgrades.
• PHP version support must cover the oldest runtime still in the fleet; a YAML parser may raise the floor.
• Third-party packages that read this package's config via config('package.*') will break if the YAML is not mapped into the repository. Identify those consumers before migrating.

Sequencing

• Config migration and currency migration should be separate change windows, not a single deploy. They fail differently (hard boot failure vs silent data error) and debugging a currency anomaly inside a config outage is unnecessarily hard.
• Order: config format first (verify boot and cache), currency second (verify totals and reports), then decommission the v1 path.

Operational Impact

Maintenance

• Net negative if the package reads YAML outside the config repository: the team now maintains a config subsystem that Laravel otherwise provides for free. Net neutral-to-positive if it is a thin parse-and-inject in the provider.
• New ownership burden: YAML schema documentation, validation (recommend shipping a JSON Schema or a php artisan package:validate-config command), and parser version tracking.
• Watch for an ongoing stream of minor releases fixing YAML edge cases (quoting, yes/no being coerced to booleans, on/off, numeric-looking currency codes like 1 — none likely here, but the general class of YAML coercion bugs is real).

Support

• Expect a spike of tickets in the first two quarters: "config not found", "config ignored after deploy", "amounts now in EUR". Pre-empt with a migration guide, a changelog entry that names both changes as breaking, and an upgrade command if the maintainers ship one.
• Support scripts and runbooks that reference config file paths must be updated. This is often overlooked and surfaces during an incident at the worst possible time.
• If the package is a dependency of internal shared libraries, the blast radius multiplies; publish internal guidance before the upgrade window.

Scaling

• YAML parse cost at boot is negligible in absolute terms but is per-request unless cached. Under config:cache it disappears; without it, it is a small constant added to every request across every pod. Not a capacity concern, but a reason to insist on caching.
• Currency change has no scaling dimension, but it does have a reporting dimension: dashboards aggregating across currencies without an explicit grouping will silently mix units. Audit analytics and finance exports.

Failure modes

• Hard: YAML parse error on boot → application down. Mitigation: validate config in CI and at container start, not lazily at first use.
• Silent: package reads YAML directly, config:cache reflects stale or empty values → wrong behaviour in production only. Highest-severity mode; must be explicitly tested.
• Silent: currency defaults to EUR for a service that expected the prior default → wrong monetary values persisted, potentially irreversibly. Mitigation: explicit currency in every config plus a startup assertion.
• Silent: config templating in CI still emits PHP → package reads nothing, falls back to internal defaults. Mitigation: fail-closed on missing config rather than defaulting.
• Latent: transitive YAML parser version skew between environments → parse differences across pods.

Ramp-up

• Engineering: low-to-moderate. YAML is familiar; the Laravel-idiom deviation is the teaching point. Budget roughly half a day per consuming service for the transcode, plus a staging verification cycle.
• Operations/SRE: moderate. Deployment manifests, config maps, and secrets injection all touch the config file extension and format.
• Finance/analytics: potentially the largest effort and the least technical. Someone must confirm the currency assumption in every report, and that is an organisational task, not a code change.
• Recommend a documented "explicit currency always" policy as a standing team convention from this point forward, independent of what the package's defaults do in future releases.