Yandex Market Laravel Package

Technical Evaluation

Architecture fit

• Correct the label before planning. This is a Symfony-first bundle, not a Laravel package. Evidence: bin/console for asset installation, Symfony Messenger transports and retry strategies expressed as Messenger options, and a shared baks-dev framework layer implied by baks:assets:install. A TPM should size integration as "Symfony bundle consumed inside a Laravel app," which is roughly one sprint more than adopting a Laravel-native client. Roadmap dates built on the "Laravel package" assumption are wrong and should be re-baselined.
• The async-first shape is directionally right for marketplace work. Per-token queue isolation with independent retry/delay/multiplier settings is the one genuinely differentiated capability. It maps to a real operational problem: one seller token returning 429/401 storms should not stall another seller's catalog sync. This directly supports a multi-seller (many-credential) channel strategy and is much weaker justification for a single-account integration.
• Unresolved framework coupling is the pivotal unknown. If baks-dev/yandex-market requires a baks-dev core (kernel, shared abstractions, or persistence), we would be adopting a framework, not an API client. That changes the decision from "cheap wrapper" to "second application substrate inside our app," with a correspondingly larger maintenance and upgrade obligation. This must be resolved by dependency inspection before any commitment.
• Persistence ownership is unspecified. Symfony bundles commonly ship Doctrine entities and migrations for token/profile storage. Laravel has no Doctrine. If the package owns schema, we either reproduce it by hand or run a parallel persistence model — a durable architectural wart that raises the cost of every future change.
• Absence of webhooks caps the value proposition. The package is async/poll-oriented. Real-time order status and price-indexing signals require a second, separately built integration surface. Any business case that credits this package with "full Yandex.Market integration" is overstated and should be scoped down to bulk/batch workloads (catalog upload, price updates, inventory sync).

Integration feasibility

• Feasible only behind an application-owned boundary. The defensible posture is ports-and-adapters: define our own MarketplaceClient, CatalogSync, and OrderFeed interfaces, implement them by delegating to this package. Controllers, jobs, and domain services never import package namespaces. This is what makes a zero-star dependency an acceptable risk rather than an unmanaged one, and it is the cheapest insurance we can buy.
• A queue bridge is required, and it is a real cost. Two paths: (a) run Symfony Messenger consumers under Supervisor alongside Horizon — fastest to stand up, but saddles us with two queue runtimes in production; (b) translate package work into native Laravel jobs — cleaner long-term ops, but requires wrapping each call site. Recommend (b) as the target state and (a) only as a spike convenience. Choosing (a) permanently doubles on-call surface for a single channel.
• PHP 8.4 floor is an infrastructure prerequisite, not a package detail. It implies Laravel 11+ and likely drags PHP runtime, CI images, and dependency upgrades across the estate. This should be tracked as its own workstream with its own owner, because it can consume the pilot budget on its own.
• Effort framing for planning. Expect roughly: 1 week dependency/provenance spike, 1–2 weeks adapter layer and queue bridge, 2–3 weeks first working sync path against sandbox, plus unknown time for documentation debt and contract-test authoring. Treat anything under 6 weeks as optimistic.

Technical risk

Key questions

1. In a clean Laravel 11 app, what exactly does composer require baks-dev/yandex-market pull in — a Symfony kernel, Doctrine, a baks-dev core? This single answer determines whether the package is a wrapper or a framework.
2. Does the package own database tables for tokens/profiles, and if so, what is the schema and who migrates it?
3. Which Yandex Market API version is targeted, and which endpoint families are actually implemented (catalog, prices, orders, reports, returns)?
4. Are API calls idempotent, or is retry safety entirely on the caller?
5. Who maintains this, what is their responsiveness, and can we obtain a written 12-month statement of intent?
6. Does a test suite exist beyond the --group=yandex-market flag — does it run in CI, and against mocks or sandbox?
7. Under what practical terms can we fork and republish? MIT permits it; confirm no trademark or service-name constraints affect a rebranded internal fork.

Integration Approach

Stack fit

• Baseline the target at Laravel 11+ / PHP 8.4 / Redis / Horizon. If the estate sits on Laravel 10 or PHP 8.2, this package is not adoptable without an infrastructure program — surface that as a program dependency with its own timeline, not as a task inside the integration.
• Isolate the package in a dedicated Marketplace module behind our own interfaces. Direct namespace imports from controllers or domain services should fail code review. This is the mechanism that converts an abandoned dependency into a replaceable one.
• Mirror the package's transport-per-token model with Horizon supervisor-per-token (or queue names suffixed by token UUID), and align queue naming with the package's profile naming so runbooks stay coherent across both runtimes during transition.
• Keep credentials in Laravel's encrypted config or a secrets manager — not in whatever storage the package defaults to — until that mechanism is documented and reviewed. Token rotation is a security property we must own.

Migration path

• Greenfield: there is nothing to migrate from. The package has zero dependents in our estate. The path that matters is the exit path if the pilot fails — which is exactly what the adapter boundary buys. Frame the decision to stakeholders as "reversible within two sprints," because that reversibility is the core justification for adopting an unmaintained dependency.
• Where a manual or spreadsheet-driven Yandex.Market process exists today, run package-driven sync in parallel with the manual process for the pilot cohort, with catalog and price state reconciled and differences logged. Cutover only when reconciliation error is stable for a defined window.
• Vendor the fork via VCS repository reference, not Packagist, so internal changes are versioned and deploys are reproducible independent of upstream.

Compatibility

• Symfony-inside-Laravel is the primary compatibility axis. Validate that asset publishing, config loading, and service wiring behave under Laravel's bootstrap before assuming any other compatibility claim. The README's bin/console instructions are a signal, not a formality.
• PHP 8.4 is a hard floor. Pin it in CI and verify no conflicting php constraint exists in the transitive tree. If the package pulls a Symfony major version that conflicts with other installed Symfony components, the conflict is likely to be resolvable but non-trivial — budget for it.
• Two runtimes during transition are acceptable for pilot, not for GA. Define the consolidation milestone explicitly so "temporary" does not become permanent architecture. Set a GA gate: single queue runtime, single supervisor model, one documented on-call runbook.
• Yandex API version drift is our burden. With no vendor contract, we own tracking upstream API changes. Put a recurring quarterly review on the calendar at adoption time, not after the first breakage.

Sequencing

1. Dependency and provenance spike (1 week, hard gate). Inspect the transitive tree, confirm whether a baks-dev core is required, confirm whether the package owns schema, verify Packagist ownership and release provenance. No-go here ends the initiative cheaply.
2. Adapter layer first, integration second (1–2 weeks). Define MarketplaceClient, CatalogSync, OrderFeed interfaces and write the delegating implementation against sandbox. Building the integration before the boundary is how teams end up unable to leave.
3. Queue decision and bridge (parallel, 1–2 weeks). Prototype Laravel-job translation; do not ship the Supervisor-alongside-Horizon variant as the permanent answer.
4. Read-only vertical slice. One token, one read call, one queue round-trip end to end. This is the real feasibility proof, not a successful composer require.
5. Bulk catalog sync with idempotency and DLQ. First workload should tolerate latency — catalog and price pushes, not order status.
6. Second integration surface for webhooks. Separate ticket, separate estimate, not credited to this package.
7. Pilot with a small seller cohort, then GA gate covering runtime consolidation, runbook completeness, and error-rate thresholds.

Operational Impact

Maintenance

• Treat the package as internal code from day one. Fork to the org namespace, pin to the VCS fork, and assign a named owner. Realistic steady-state cost is 0.1–0.2 FTE/yr for dependency bumps, upstream diff review, PHP/Symfony upgrade alignment, and Yandex API drift. Put that number in the business case; it is the price of "free."
• Upgrade risk is asymmetric. Because the fork diverges, upstream fixes require manual cherry-picking, and the thin release notes give no signal about what changed. Adopt a policy of diffing upstream on a schedule rather than reacting to breakage, and accept that we will increasingly own the code path.
• Documentation is a deliverable, not a nice-to-have. Our engineers will write the usage guide, the failure-mode runbook, and the onboarding notes. Budget it in the same sprint as the first working integration or it will never happen.

Support

• There is no vendor, no SLA, no security review artifact, no support contract. Escalation path terminates internally. Any stakeholder expectation of vendor responsiveness should be extinguished in the kickoff, not discovered during an incident.
• Supply-chain posture must be explicit. Zero stars and zero dependents means no community eyes on the code. Require a review pass on the forked source before production, and lock the dependency via commit reference.
• Pilot success criteria should include supportability, not just functionality: can an on-call engineer diagnose a stuck token queue at 2am using only our runbooks? If not, the integration is not production-ready regardless of whether sync works.

Scaling

• Per-token queue topology scales with seller count, and so does operational surface. At 5 sellers this is trivial; at 50 it is 50 queues, 50 retry policies, and a fan-out problem in observability. Decide early whether token-count growth is a product goal — if it is, invest in queue observability and per-token dashboards as part of the pilot, not after.
• Throughput is bounded by Yandex rate limits, not by our workers. Capacity planning must be expressed in API quota per token, with backoff behavior validated against real 429 responses. Adding workers past the quota ceiling buys nothing and creates retry storms.
• The two-runtime problem compounds with scale. Supervisor-plus-Horizon is tolerable for a pilot cohort and untenable at GA. Make consolidation a gate, not a backlog item.

Failure modes

• Retry storms without idempotency. If the package retries non-idempotent writes, duplicate listings or duplicate price updates are plausible. Mitigate with idempotency keys at our adapter, retries capped at 3, exponential backoff, and a dead-letter queue with an alert — do not rely on package defaults.
• Silent token expiry. Undocumented token rotation means credentials can fail quietly and queues can drain into a DLQ nobody watches. Own credential lifecycle explicitly and alert on 401 rates per token.
• Single-maintainer abandonment. The realistic failure is not malice but neglect: upstream stops updating, PHP moves on, and we are running an orphaned fork. The mitigation is the fork plus a quarterly review cadence plus a documented escape hatch through the adapter layer.
• Queue runtime divergence during transition. Messages dispatched on one runtime and consumed on another is a classic pilot-stage incident. Document the message contract and constrain routing before enabling more than one token.
• Endpoint coverage gaps discovered late. Without a coverage matrix, teams assume a capability exists and discover it does not mid-pilot. Enumerate coverage in the spike and publish it to stakeholders as a scope statement.

Ramp-up

• Expect a two-week ramp before first productive commit: PHP 8.4 environment, config publishing, sandbox credentials, and reading Symfony-shaped docs written in Russian. Plan onboarding for one engineer, not a team — parallel onboarding on an undocumented package multiplies confusion without adding throughput.
• Onboarding material must be authored, not found. A short internal README covering: how to add a token, how to add its queue, how to read the DLQ, how to replay a failed job. This is a half-day of work that prevents a recurring tax.
• Skills mix matters. The engineer owning this needs Symfony Messenger familiarity, not just Laravel queue experience. If nobody on the team has run Messenger consumers, add learning time or accept a longer pilot.
• Kill criteria should be written before ramp-up starts. Suggested: if the dependency spike reveals a required baks-dev core, or if a read-only vertical slice is not working within three engineer-weeks, stop and reassess against a first-party client build. Written-in-advance criteria are the only reliable protection against sunk-cost escalation on an unsupported dependency.