包简介

Socialite for Laravel

README 文档

README

Пакет добавляет готовый OAuth-вход для Laravel через laravel/socialite:

маршруты /socialite/{driver}/redirect и /socialite/{driver}/callback;
таблицу social_accounts для привязки провайдера к пользователю;
автоматическую авторизацию существующего пользователя или создание нового;
привязку дополнительного провайдера для уже авторизованного пользователя;
generic hook для кастомного redirect screen без правки vendor-кода.

Требования

PHP ^8.3|8.4|8.5
Laravel ^12.25|^13.1
laravel/socialite

Установка

composer require ichinya/laravel-socialite
php artisan vendor:publish --tag=ichinya-socialite
php artisan migrate

Как работает flow

Гость переходит на socialite.redirect.
Пакет создаёт provider через Socialite::driver($driver).
Если для драйвера настроен redirect_hooks, пакет даёт hook-классу шанс вернуть кастомный response.
Если hook не настроен, вернул null, сконфигурирован неверно или завершился ошибкой, пакет делает fallback к штатному provider response.
На callback пакет связывает driver + identity с пользователем и выполняет login/bind flow.

Локальная разработка пакета через path repository

Если пакет разрабатывается локально внутри Laravel-приложения:

composer config repositories.ichinya-laravel-socialite path packages/ichinya/laravel-socialite
composer update ichinya/laravel-socialite
composer show ichinya/laravel-socialite

Ожидаемый результат проверки: dist: [path] packages/ichinya/laravel-socialite.

Чтобы вернуться к обычной версии из registry:

composer config --unset repositories.ichinya-laravel-socialite
composer update ichinya/laravel-socialite

Настройка `config/socialite.php`

<?php

return [
    'drivers' => [
        'github' => '/assets/socialite/github.svg',
        'google' => '/assets/socialite/google.svg',
        'telegram' => '/assets/socialite/telegram.svg',
    ],

    'redirect_hooks' => [
        'telegram' => \App\Infrastructure\Auth\TelegramRedirectScreen::class,
    ],

    'stateless_drivers' => [
        'telegram' => true,
    ],

    'redirects' => [
        'after_login' => '/cabinet',
        'after_bind' => '/cabinet',
        'on_error' => 'route:login',
    ],
];

Ключи конфига

drivers: активные провайдеры в формате driver => icon_path.
redirect_hooks: карта driver => class-string для container-resolved hook-классов.
stateless_drivers: драйверы, для которых нужно ->stateless().
redirects.after_login: редирект после login flow.
redirects.after_bind: редирект после bind flow.
redirects.on_error: редирект при ошибке OAuth. Поддерживает путь и route:<name>.

Generic redirect hook

Hook нужен для custom redirect screen, когда provider на этапе redirect() отдаёт HTML, legacy widget или другой нестандартный ответ, а приложению нужен собственный wrapper screen.

Hook-класс должен реализовывать Ichinya\LaravelSocialite\Contracts\RedirectHook:

<?php

namespace App\Infrastructure\Auth;

use Closure;
use Ichinya\LaravelSocialite\Contracts\RedirectHook;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Response;
use Symfony\Component\HttpFoundation\RedirectResponse as SymfonyRedirectResponse;

class TelegramRedirectScreen implements RedirectHook
{
    public function handle(
        string $driver,
        mixed $provider,
        Closure $fallback,
    ): RedirectResponse|Response|SymfonyRedirectResponse|string|null {
        if ($driver !== 'telegram' || !method_exists($provider, 'getButton')) {
            return null;
        }

        return response('<html>custom wrapper screen</html>');
    }
}

Hook получает lazy callback $fallback, если приложению нужно вручную вернуть исходный provider response без преждевременного вызова redirect().

Что может вернуть hook

Illuminate\Http\Response
Illuminate\Http\RedirectResponse
Symfony\Component\HttpFoundation\RedirectResponse
string
null

Fallback semantics

hook не настроен: пакет ведёт себя как раньше;
hook сконфигурирован на несуществующий класс или класс с неверным контрактом: ошибка логируется, затем выполняется fallback;
hook вернул null: используется штатный provider response;
hook выбросил исключение: ошибка логируется, затем выполняется fallback;
hook не должен заменять callback/login flow, он влияет только на этап redirect.

Диагностика

В логах ищите:

DEBUG на resolve hook по driver;
DEBUG на fallback после null;
WARN на отсутствующий hook-класс;
ERROR на exception внутри hook или ошибке container resolution;
INFO на successful custom response.

Настройка `config/services.php` и `.env`

Google / GitHub

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => env('GOOGLE_REDIRECT_URI'),
],

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => env('GITHUB_REDIRECT_URI'),
],

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI="${APP_URL}/socialite/google/callback"

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URI="${APP_URL}/socialite/github/callback"

Telegram

Для Telegram нужен socialiteproviders/telegram.

composer require socialiteproviders/telegram

'telegram' => [
    'bot' => env('TELEGRAM_LOGIN_BOT_NAME', env('TELEGRAM_BOT_NAME')),
    'client_id' => null,
    'client_secret' => env('TELEGRAM_BOT_TOKEN'),
    'redirect' => env('TELEGRAM_LOGIN_REDIRECT_URI', env('APP_URL').'/socialite/telegram/callback'),
],

TELEGRAM_LOGIN_BOT_NAME=your_bot_name
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_LOGIN_REDIRECT_URI="${APP_URL}/socialite/telegram/callback"

Пример регистрации Telegram provider:

use Illuminate\Support\Facades\Event;
use SocialiteProviders\Manager\SocialiteWasCalled;
use SocialiteProviders\Telegram\Provider as TelegramProvider;

Event::listen(function (SocialiteWasCalled $event): void {
    $event->extendSocialite('telegram', TelegramProvider::class);
});

Связь в модели `User`

use Ichinya\LaravelSocialite\Traits\HasSocialites;

class User extends Authenticatable
{
    use HasSocialites;
}

После этого доступна связь:

$user->socials;

Маршруты пакета

GET /socialite/{driver}/redirect (socialite.redirect)
GET /socialite/{driver}/callback (socialite.callback)

Обработка ошибок на login screen

При ошибке OAuth пакет редиректит на socialite.redirects.on_error и кладёт текст ошибки в ключ socialite.

@if($errors->has('socialite'))
    <div>{{ $errors->first('socialite') }}</div>
@endif

Частые проблемы

Invalid state

Добавьте драйвер в stateless_drivers:

'stateless_drivers' => [
    'telegram' => true,
],

Bot username required

Проверьте services.telegram.bot и TELEGRAM_LOGIN_BOT_NAME.

Mixed Content

Проверьте:

APP_URL=https://...
доверие к proxy-заголовкам в Laravel и веб-сервере.

Changelog

Смотрите CHANGELOG.md.

License

MIT. See LICENSE.md.

ichinya/laravel-socialite 适用场景与选型建议

ichinya/laravel-socialite 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 53 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 03 月 17 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「oauth」「oauth2」「laravel」「oauth2-client」「socialite」「laravel-socialite」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 ichinya/laravel-socialite 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 ichinya/laravel-socialite 我们能提供哪些服务？

定制开发 / 二次开发

基于 ichinya/laravel-socialite 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 ichinya/laravel-socialite 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

henter/wechat-oauth 34

WeChat OAuth SDK

vantt/oauth2-hydra-php 0

Ory-Hydra OAuth 2.0 Client Provider for The PHP League OAuth2-Client

hubzero/orcid-php 2

Library for ORCID web services

gener1c-code/oauth2-server 0

A lightweight and powerful OAuth 2.0 authorization and resource server library with support for all the core specification grants. This library will allow you to secure your API with OAuth and allow your applications users to approve apps that want to access their data from your API.

cakedc/cakephp-email-toolkit 4

Email Toolkit Plugin for CakePHP

wherebyus/league-oauth2-social 0

The missing social authentication for thephpleague/oauth2-server, adapted from schedula/league-oauth2-social

ichinya/laravel-socialite

包简介

关键字：

README 文档

README

Требования

Установка

Как работает flow

Локальная разработка пакета через path repository

Настройка `config/socialite.php`

Ключи конфига

Generic redirect hook

Что может вернуть hook

Fallback semantics

Диагностика

Настройка `config/services.php` и `.env`

Google / GitHub

Telegram

Связь в модели `User`

Маршруты пакета

Обработка ошибок на login screen

Частые проблемы

Invalid state

Bot username required

Mixed Content

Changelog

License

ichinya/laravel-socialite 适用场景与选型建议

与 ichinya/laravel-socialite 相关的其它包

统计信息

GitHub 信息

其他信息

ichinya/laravel-socialite

包简介

关键字：

README 文档

README

Требования

Установка

Как работает flow

Локальная разработка пакета через path repository

Настройка config/socialite.php

Ключи конфига

Generic redirect hook

Что может вернуть hook

Fallback semantics

Диагностика

Настройка config/services.php и .env

Google / GitHub

Telegram

Связь в модели User

Маршруты пакета

Обработка ошибок на login screen

Частые проблемы

Invalid state

Bot username required

Mixed Content

Changelog

License

ichinya/laravel-socialite 适用场景与选型建议

与 ichinya/laravel-socialite 相关的其它包

统计信息

GitHub 信息

其他信息

Настройка `config/socialite.php`

Настройка `config/services.php` и `.env`

Связь в модели `User`