Meta Five Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin Laravel adapter (service provider + facade + config + Guzzle transport) over the MetaTrader 5 Web API — a request/response JSON API exposed by MetaQuotes' mt5api gateway. It is not a streaming client, not a trading engine, and carries no business logic.
• Correct placement in our architecture is an infrastructure adapter behind an internal Mt5Client interface. It should never be called directly from controllers or Livewire/Inertia components, because trading calls need idempotency, reconciliation, and audit logging that the package does not provide.
• It covers outbound HTTP only. Any product requirement involving real-time quotes, sub-second execution, or tick streaming is out of scope and would need a different transport (native MT5 gateway sockets or a broker-side feed).
• Fits cleanly into a modular monolith or a dedicated "trading integration" service. The latter is preferable if we ever run more than one Laravel app against the same gateway session pool.

Integration feasibility

• Mechanical install: composer require, publish config, set gateway URL/port/manager credentials in env or a secrets manager. Days, not weeks, for a happy-path connection.
• The real cost is not the package — it is standing up and licensing the MT5 Web API gateway (typically Windows-hosted, terminal-attached, egress-controlled). That component is the long pole and is entirely outside this repo.
• Coverage is unverified from the outside. With 35 stars and a single 2024-05 release, assume the wrapper covers a useful subset (auth, users, symbols/quotes, orders/positions, history) and audit it endpoint-by-endpoint against our required call list before committing.
• Auth model is stateful: an auth handshake returns a session token with a bounded lifetime, requiring refresh logic. Confirm whether the package manages re-auth or expects the caller to.

Technical risk

• Bus factor of one, minimal community, no visible commercial backing, no SLA. Treat as a convenience wrapper, not a strategic dependency.
• Unknown test coverage and unclear Laravel/PHP version bounds beyond composer.json. Verify against our pinned Laravel and PHP versions before planning.
• MetaQuotes licensing and redistribution terms for the Web API are non-trivial; confirm our deployment model is permitted before design sign-off.
• Exit cost is low-to-moderate: the API surface is small enough that an internal fork or a from-scratch Guzzle client is a contained effort (est. 1–2 engineer-weeks).

Key questions to resolve before approval

1. Which MT5 Web API endpoints do we actually need, and does the package wrap all of them?
2. Does it handle token expiry/re-auth, retries, and retcode-to-exception mapping, or do we build that?
3. What Laravel/PHP versions are tested in CI, and is there a test suite at all?
4. Who owns the MT5 gateway (Windows host, patching, monitoring) and is our use of the Web API licensed?
5. Is the maintainer reachable for a security fix, and what is our fork-and-own trigger?

Integration Approach

Stack fit

• Laravel 9/10/11 with PHP 8.1+ is the expected envelope; confirm in composer.json. It rides on Guzzle, so existing proxy, TLS, timeout, and HTTP logging conventions apply unchanged.
• Credentials are manager-level MT5 account secrets. They must go through our secrets manager and never into .env committed to a repo or into application logs.

Migration path

• If we already call the MT5 Web API via raw Guzzle, do not migrate call sites to the facade directly. Introduce an internal Mt5Client interface first, implement it once with the package, and keep a raw-Guzzle implementation behind the same interface. This makes the package a swappable detail and caps vendor risk at near zero.
• If this is greenfield, the same interface still applies — write it on day one.

Compatibility

• Verify the package's supported MT5 Web API/gateway version against whatever build we deploy. MT5 API semantics (retcodes, session behavior) change across gateway releases.
• Confirm PHP extension and cURL requirements, and whether it assumes a specific Guzzle major version that conflicts with our other dependencies.

Sequencing

1. Connectivity spike (1 week): gateway up, /api/test, auth handshake, one read call. Prove network, TLS, and credentials before writing product code.
2. Read-only integration (1–2 weeks): symbols, quotes, account/user info, history/deals. Build observability and error mapping here.
3. Contract tests: record fixtures from the live gateway so CI runs without a gateway dependency.
4. Trading operations behind a feature flag (2–3 weeks): order placement/cancellation with idempotency keys, explicit reconciliation via history lookups on timeout, and hard risk limits enforced outside the package.
5. Cutover and runbook: only after reconciliation and failure drills pass in staging.

Operational Impact

Maintenance

• Pin the version exactly. Budget ~0.1 FTE to track upstream and MT5 API changes; fork if the maintainer goes quiet. The surface is small enough that owning a fork is cheaper than owning a rewrite.
• Do not let facade calls proliferate. One adapter class, one place to patch.

Support

• No vendor support channel. Internal on-call owns both the Laravel service and the MT5 gateway host — including Windows patching, terminal restarts, and certificate renewal. Staffing this is the most commonly underestimated cost.
• Secrets rotation for the manager account needs a documented, tested procedure.

Scaling

• The gateway is stateful and terminal-bound; it does not scale horizontally like a stateless web tier. Plan for vertical scaling plus sharding by account group across multiple gateways if volume grows.
• Session tokens are per-connection; concurrent workers need either a session pool or serialized access. Watch gateway-side rate limits.
• This adapter is unsuitable as a high-frequency path. Target it at account management, reporting, and low-frequency order operations.

Failure modes to design for

• Ambiguous trading results: a timeout on order submission does not mean the order failed. Every mutating call must be reconcilable via history/order lookup before any retry. This is the single most dangerous failure mode and the package will not solve it.
• Token expiry mid-flight: expect periodic 401-equivalent retcodes; implement refresh-and-retry-once.
• Gateway down or terminal disconnected: surface as a distinct, non-retryable class so upstream flows fail fast.
• Retcode semantics: MT5 signals business errors via retcodes, not HTTP status. Map them explicitly; never treat HTTP 200 as success.
• Clock skew and partial fills: validate against gateway time and handle partial execution states in the domain layer.

Ramp-up

• A competent Laravel engineer is productive with the wrapper in 1–2 weeks.
• Reaching production reliability — reconciliation, idempotency, risk limits, runbooks — realistically takes 4–6 weeks and requires someone to learn the MT5 domain model (deals vs. orders vs. positions, account/group hierarchy, manager vs. trader permissions).
• Recommend one named owner for MT5 domain knowledge; it does not diffuse well across a team.