Pos Bundle Laravel Package

Technical Evaluation

Architecture fit — This is a major-version wrapper bump (mews/pos ^1.x → ^2.0) that realigns the package with upstream namespace and configuration conventions rather than changing the underlying integration model. The gateway-per-provider abstraction still fits a Laravel service-provider + published-config pattern, and the package remains a good fit for applications that treat payment provider access as an infrastructure concern behind a service/repository boundary. The addition of gateway_configs.lang as a single, uniform setting and the consolidation of IyzicoPos, Param3DHostPos, and PayTrPos under one gateway namespace improves conceptual consistency: one gateway class per provider, one config block per gateway. Teams that already isolate gateway instantiation behind their own adapter will see a cleaner fit; teams that call Mews\Pos\Gateways\* classes directly from controllers or jobs will see the fit degrade until those call sites are reworked.

Integration feasibility — Feasible but not a drop-in. Every breaking change is configuration- or namespace-shaped, both of which are greppable and mechanical:

• Namespace move Mews\Pos\Gateways\* → Mews\Pos\Gateway\* — a project-wide find/replace plus import-order cleanup.
• Class renames EstPos/EstV3Pos → AssecoPos, PosNet → PosNetPos — affects any explicitly referenced provider, config values that name a gateway class, and persisted gateway identifiers if they were stored.
• Account model move Mews\Pos\Entity\Account\PayForAccount → Mews\Pos\Model\Account\PayForPosAccount — affects type hints, factories, and any serialized account payloads.
• Config key enc_key → secret_key — a secret-naming change with real operational consequences (see Operational Impact).
• Removals: payment_model, bank-level lang, bank-level test_mode, gateway_endpoints.payment_api_2, and the bundle AccountFactory class.

The removal of AccountFactory is the one item that is not a rename: any code that constructed accounts through it needs a replacement path, and the release notes do not describe one. That must be resolved against docs/UPGRADE-2.0.md before estimating.

Technical risk — Rated high, concentrated in three areas:

1. Runtime floor changes. PHP >=8.0 and Symfony >=5.4 remove the ability to run mixed-fleet PHP 7.4 workers. In a Laravel context this is mostly an application-wide upgrade gate, not a package-specific one, but it means the package cannot be adopted incrementally on a partially upgraded fleet.
2. Silent test-mode regressions. Bank-level test_mode (deprecated since 1.2.0) is now fully removed in favor of gateway_configs.test_mode. Unmigrated configs that previously resolved to sandbox behavior may now fall through to a default — and the dangerous default in a payments library is production. This is the single highest-severity risk in the release and deserves a dedicated pre-deploy assertion.
3. Credential key rename. enc_key → secret_key is a security-adjacent rename. Any environment file, secrets manager entry, or config cache still keyed on enc_key will be silently ignored rather than erroring loudly in every case, and the failure surfaces as an authentication error against a live endpoint.

Lower-severity risk: payment_api_2 removal and the gateway_3d de-requirement change endpoint resolution semantics for KuveytPos/VakifKatilimPos/PayFlexCPV4Pos. Since v2 derives gateway_3d from payment_api, any config that relied on an explicit gateway_3d override should be re-validated against expected 3D Secure routing.

Key questions

• Which PHP and Symfony/Laravel versions are in production and CI today, and is the PHP 8.0 floor already satisfied across all workers, queue consumers, and scheduled jobs?
• Does any application code reference Mews\Pos\Gateways\*, EstPos, EstV3Pos, PosNet, or PayForAccount directly, or is all access already behind an internal adapter? (Determines whether this is a config migration or a code migration.)
• What replaces the removed bundle AccountFactory — is there a documented successor in UPGRADE-2.0.md, or must we own a replacement?
• Are gateway identifiers or account objects persisted anywhere (DB columns, cache keys, queued job payloads)? If so, the renames are a data migration, not just a deploy.
• Is test_mode set at the bank level anywhere in current configs, and what is the effective default when it is absent in v2?
• Does the team currently use any provider whose endpoint resolution changes (KuveytPos, VakifKatilimPos, PayFlexCPV4Pos), and are explicit gateway_3d values present?
• Is there appetite to adopt any of the three new gateways (IyzicoPos, Param3DHostPos, PayTrPos) now, or should they be deferred to keep the upgrade scoped to parity?

Integration Approach

Stack fit — Fits a standard Laravel integration: published config file under config/, provider registration via a service provider, and gateway resolution by identifier. The move from bank-level to gateway-scoped settings (lang, test_mode) actually maps better onto Laravel's config-cache model, since per-gateway keys are more cache-friendly than per-bank overrides. The removal of Symfony v4 keeps the dependency tree aligned with modern Laravel releases. Confirming that the "bundle" naming in the notes refers to a Symfony-style bundle with a Laravel service-provider equivalent — and that the equivalent is unaffected by the AccountFactory removal — is the first integration checkpoint.

Migration path — Treat this as a config-first, code-second migration in a branch, not a rolling change:

1. Pin the application to the v2 line and read docs/UPGRADE-2.0.md end to end; extract the account-construction replacement before touching code.
2. Rewrite published config: enc_key → secret_key, delete payment_model, move lang under each gateway_configs entry, move test_mode under each gateway_configs entry, remove payment_api_2, and re-derive or drop explicit gateway_3d for the three affected providers.
3. Update secrets: add secret_key to every environment (local, CI, staging, production) before removing enc_key, so no environment is left with an unset credential at any point.
4. Namespace and class sweep in application code: Gateways\ → Gateway\, EstPos/EstV3Pos → AssecoPos, PosNet → PosNetPos, PayForAccount → PayForPosAccount, and replace AccountFactory usage.
5. Add a boot-time or pre-flight validation that fails loudly if any gateway config lacks an explicit test_mode, so the sandbox-to-production fallback cannot happen silently.
6. Only after parity is proven, consider the new IyzicoPos / Param3DHostPos / PayTrPos gateways as a separate, smaller change.

Compatibility — Hard requirements: PHP 8.0+, Symfony 5.4+. Any Laravel version still resolving Symfony 4 components (or a PHP 7.4 runtime) blocks adoption outright. Downstream, expect breakage in application code only at the enumerated renames; there is no reported change to the payment request/response flow itself, so business logic around transactions should be unaffected. Third-party code that typed against Mews\Pos\Gateways\* or PayForAccount will break and needs the same sweep. Existing persisted gateway identifiers remain valid only if they matched the new class names.

Sequencing — Recommend shipping in this order: (1) PHP 8.0 / Symfony 5.4 platform upgrade, independent of this package; (2) config migration in a non-production environment with an explicit test-mode assertion, validated against sandbox for every provider in use; (3) namespace/class/account code sweep; (4) production rollout with a canary on the lowest-volume provider first; (5) new-gateway adoption as a distinct initiative. Do not bundle the platform upgrade and the payment library upgrade into one release — if something breaks in production payments, you want to know which change caused it.

Operational Impact

Maintenance — Net positive medium-term: consolidating gateway names and moving lang/test_mode into a single gateway_configs structure reduces the number of per-bank special cases the team has to remember. Short-term cost is real — the team absorbs a full config rewrite plus a code sweep, and must own whatever replaces AccountFactory if upstream provides no successor. Budget ongoing effort for tracking upstream mews/pos 2.x minors, since this release establishes v2 as the supported line and v1 will presumably stop receiving fixes.

Support — Support burden shifts from "why does this gateway behave differently" toward "why is this credential missing." Expect a spike in environment-related tickets immediately after rollout: secret_key unset in one environment, test_mode missing under a gateway_configs entry, or a stale config cache serving v1-shaped keys. The payment_api_2 removal will generate support load specifically for Param 3D Host payments, which now require routing to Param3DHostPos — any integration that used the removed endpoint needs a documented redirect path, and support documentation should be updated in the same release, not after.

Scaling — No scaling regression indicated; the change is structural, not throughput-related. The gateway-per-provider model continues to scale horizontally, and per-gateway config makes it easier to enable or disable a provider per environment without touching bank-level blocks. One scaling-adjacent consideration: if the account model change (PayForAccount → PayForPosAccount) alters serialization, any horizontally scaled workers with in-flight queued jobs during deploy will fail to deserialize old payloads. Drain queues before deploying.

Failure modes — In rough order of severity:

• Sandbox-to-production leakage from the removed bank-level test_mode defaulting unexpectedly. Highest severity; mitigate with an explicit startup assertion.
• Credential resolution failure from enc_key/secret_key mismatch, presenting as provider authentication errors rather than config errors — slow to diagnose under incident pressure.
• Class-not-found fatals from missed namespace or rename sweeps, surfacing at the worst moment: first transaction through an untested gateway path.
• 3D Secure routing changes for KuveytPos / VakifKatilimPos / PayFlexCPV4Pos where gateway_3d was previously pinned and is now derived from payment_api — a wrong derivation may still "succeed" at the API level while producing the wrong authentication flow.
• payment_api_2 callers failing outright until migrated to Param3DHostPos.
• Queued-job deserialization failures across a rolling deploy if account objects are in payloads.

Ramp-up — Modest for developers, meaningful for whoever owns configuration and secrets. A developer needs to internalize one namespace move, two gateway renames, and one account-class move — an afternoon of work plus review. The heavier lift is on the operator side: auditing every environment for enc_key, bank-level test_mode, lang, payment_model, and payment_api_2, and confirming gateway_configs is complete for every active provider. Recommend a short written runbook (config diff, secrets checklist, test-mode assertion, canary provider order) and a single owner for the production cutover. Given this is a payments path, plan the rollout for a low-traffic window with a tested rollback to the v1 line held in reserve — noting that rollback requires the old config to still be recoverable, so do not delete enc_key or v1 config from source control until the canary has run clean for a full business cycle.