Mailru Laravel Package

Product Decisions This Supports

• Market-entry and localization bets. Mail.ru (VK Group) identity is only worth integrating if the roadmap includes Russian-speaking or CIS markets where Mail.ru/VK accounts are a primary consumer identity. This package is a cheap way to test that bet: one composer require, one controller, one config block — no new infrastructure, no vendor contract, no new service in the architecture diagram. It turns "should we localize login for this market?" from a quarter-long platform project into a two-day spike you can ship behind a feature flag.
• Login conversion and drop-off reduction. The core product value is removing a signup form for a defined user segment. If analytics show meaningful traffic from these geographies with high abandonment at registration, this is a measurable conversion lever with a small, reversible cost. Instrument it as a percentage-of-signups-by-method metric before and after.
• Build vs. buy — clearly "buy," with a caveat. Building a bespoke Mail.ru OAuth client is maybe 3–5 engineer-days plus ongoing maintenance of token/error handling. This adapter is free and rides on Laravel Socialite's existing abstraction. The caveat: you are buying a thin community wrapper, not a supported integration. Price the decision as "free to try, cheap to replace" rather than "free forever."
• Provider-agnostic identity architecture. Adopting this package should be paired with a deliberate decision to model social identity as a separate social_accounts table (provider, provider_user_id, user_id, tokens) rather than columns on users. That single schema decision is the real product artifact here — it makes every future provider (VK, Yandex, Google, Apple) an additive change rather than a migration. Approve the schema decision, not just the package.
• Scope decisions with user-facing consequences. Scope lists are a product decision, not a technical one: adding scopes later forces every existing user back through a consent screen, and Mail.ru does not guarantee an email even when requested. Decide up front whether email is required (and how you'll handle phone-only accounts) or whether the account is usable without it.
• Roadmap hygiene / dependency-risk register. This repo shows zero stars and its last release was May 2022. That belongs on the dependency-risk register as a watch item, not a blocker — but it materially informs whether this becomes a permanent part of the login surface or a scoped experiment with an exit plan.

When to Consider This Package

Adopt when:

• Laravel Socialite is already in the stack for at least one other provider. In that case this is genuinely additive: same Socialite::driver() call site, same controller pattern, same test-mocking boundary. Incremental cost is near zero.
• You have a validated or hypothesis-stage user base in Mail.ru/VK's addressable market, and login friction is a plausible conversion problem.
• You need a fast, cheap experiment and can tolerate community-grade maintenance — i.e. a scoped feature flag, not a bet-the-company auth flow.
• Your team can absorb the operational footguns: redirect-URI byte-matching, config:cache staleness, InvalidStateException handling on a high-traffic callback, and email being nullable.

Look elsewhere when:

• Socialite is not in the stack. Standing up laravel/socialite + socialiteproviders/manager + one community driver purely to get a single provider is a heavier architectural commitment than it appears, and you inherit a second dependency chain for one login button.
• The market hypothesis isn't validated. Don't add a permanent auth surface for speculative geography. If the data doesn't support it, the correct answer is no integration at all — the cheapest provider is the one you don't ship.
• You need vendor-backed support or an SLA. This is a community-maintained, single-provider repo with effectively thin per-provider attention. There is no support contract, and the bus factor is the SocialiteProviders org maintainers.
• VK ID is now the officially recommended surface. Mail.ru's consumer identity stack has been folded into VK ID. Before committing, someone must confirm which endpoints the provider targets today and whether they're live-and-supported versus legacy-in-maintenance. If VK ID is the forward path, plan for the migration rather than assuming this adapter tracks it.
• You require token refresh, revocation handling, or rich error surfacing. The package gives you endpoints and user mapping; refresh paths, error semantics, and background-job token validity are yours to build and own.
• You're on an older Laravel/Socialite major. Community providers lag breaking contract changes in Socialite. Expect to pin an older tag, and validate the matrix {Laravel major} × {Socialite major} × {PHP minor} explicitly.
• You want audit-grade dependency provenance. Version 4.1.1 ships with no release notes beyond a compare link. Patch releases in this monorepo are routine syncs — treat them as unverified until someone reads the diff, and pin versions deliberately.

How to Pitch It (Stakeholders)

For executives — one paragraph. We can add Mail.ru sign-in to the product in roughly two engineer-days, with no new infrastructure, no vendor contract, and no database migration beyond a small identity table we should build anyway. It's a low-cost way to test whether Russian-speaking/CIS markets are worth investing in, and it's fully reversible if the data doesn't support it. The honest caveats: this is a free community-maintained adapter whose last release was in 2022, Mail.ru's identity platform is being consolidated into VK ID, and we'd own the operational edge cases. So the recommendation is to treat it as a scoped, flagged experiment with an explicit review date — not as a permanent, load-bearing piece of our authentication stack. Success is measured as conversion lift for that segment; failure costs us two days and one config file.

For engineering — the essentials. composer require socialiteproviders/mailru; register the driver via a SocialiteWasCalled event listener (extendSocialite('mailru', Provider::class)) in AppServiceProvider::boot(); add credentials to config/services.php and the byte-identical redirect URI to the Mail.ru console. Keep OAuth in a dedicated controller or action class. Model identity as social_accounts keyed on provider_user_id — never email, which can be null for phone-only accounts. Wrap the callback in try/catch and redirect to login with a flash message rather than 500-ing on InvalidStateException. Decide stateful vs. stateless per entry point and be consistent on both legs. Mock at the Socialite boundary for tests. Subclass and override mapUserToObject() for Mail.ru-specific fields rather than forking.

The three things that will actually break, in order: the listener registration (Driver [mailru] is not supported), a stale config:cache after credential changes, and a redirect-URI mismatch (scheme, www, trailing slash, or proxy-generated http:// URLs). Budget the debugging time there, not in the provider class.

Two questions to answer before we start, not after: (1) What's in the 4.1.0 → 4.1.1 diff — Composer metadata only, or does it touch the provider class? (2) Are the endpoints this provider targets still the officially recommended surface, or has VK ID superseded them? If the answer to (2) is "superseded," we should scope the experiment accordingly and plan for a swap.