Сесія · Laravel

Вступ

Оскільки застосунки на HTTP не зберігають стану, сесії дають спосіб тримати інформацію про користувача між кількома запитами. Зазвичай ці дані потрапляють у постійне сховище / бекенд, доступний із наступних запитів.

Laravel постачається з набором бекендів сесії, доступних через виразний уніфікований API. Підтримуються популярні бекенди на зразок Memcached, Redis і баз даних.

Конфігурація

Файл конфігурації сесії вашого застосунку лежить у config/session.php. Обовʼязково перегляньте доступні в ньому опції. За замовчуванням Laravel налаштований на драйвер сесії database.

Опція конфігурації driver визначає, де зберігатимуться дані сесії для кожного запиту. Laravel містить різні драйвери:

• file - сесії зберігаються в storage/framework/sessions.
• cookie - сесії зберігаються в захищених зашифрованих cookie.
• database - сесії зберігаються в реляційній базі даних.
• memcached / redis - сесії зберігаються в одному з цих швидких сховищ на основі кешу.
• dynamodb - сесії зберігаються в AWS DynamoDB.
• array - сесії зберігаються в PHP-масиві і не зберігаються між запитами.

Примітка Драйвер array використовується переважно під час тестування і не дає даним сесії зберігатися.

Вимоги драйверів

База даних

Коли ви використовуєте драйвер сесії database, вам потрібна таблиця бази даних для даних сесії. Зазвичай вона вже є у стандартній міграції Laravel 0001_01_01_000000_create_users_table.php; але якщо з якоїсь причини таблиці sessions у вас немає, згенерувати міграцію можна Artisan-командою make:session-table:

php artisan make:session-table

php artisan migrate

Redis

Перш ніж використовувати сесії на Redis у Laravel, вам потрібно встановити PHP-розширення PhpRedis через PECL або пакет predis/predis через Composer. Докладніше про налаштування Redis дивіться в документації Laravel про Redis.

Примітка Змінна оточення SESSION_CONNECTION або опція connection у файлі конфігурації session.php дозволяє вказати, яке зʼєднання Redis використовується для зберігання сесії.

Робота з сесією

Отримання даних

Працювати з даними сесії в Laravel можна двома основними способами: через глобальний хелпер session і через екземпляр Request. Спершу подивимось на доступ до сесії через екземпляр Request, який можна вказати як тип у замиканні маршруту чи методі контролера. Памʼятайте, що залежності методів контролера автоматично впроваджуються через контейнер сервісів Laravel:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Показати профіль вказаного користувача.
     */
    public function show(Request $request, string $id): View
    {
        $value = $request->session()->get('key');

        // ...

        $user = $this->users->find($id);

        return view('user.profile', ['user' => $user]);
    }
}

Отримуючи елемент із сесії, ви також можете передати значення за замовчуванням другим аргументом методу get. Воно повернеться, якщо вказаного ключа в сесії немає. Якщо значенням за замовчуванням передати замикання і потрібного ключа немає, замикання виконається і поверне свій результат:

$value = $request->session()->get('key', 'default');

$value = $request->session()->get('key', function () {
    return 'default';
});

Глобальний хелпер session

Для отримання й збереження даних у сесії можна також використовувати глобальну PHP-функцію session. Коли хелпер session викликається з одним рядковим аргументом, він повертає значення цього ключа сесії. Коли хелпер викликається з масивом пар ключ / значення, ці значення зберігаються в сесії:

Route::get('/home', function () {
    // Отримати частину даних із сесії...
    $value = session('key');

    // Вказати значення за замовчуванням...
    $value = session('key', 'default');

    // Зберегти частину даних у сесії...
    session(['key' => 'value']);
});

Примітка На практиці різниці між використанням сесії через екземпляр HTTP-запиту і через глобальний хелпер session майже немає. Обидва способи тестуються методом assertSessionHas, доступним у всіх ваших тестах.

Отримання всіх даних сесії

Якщо потрібно дістати всі дані сесії, використовуйте метод all:

$data = $request->session()->all();

Отримання частини даних сесії

Методи only і except дозволяють дістати підмножину даних сесії:

$data = $request->session()->only(['username', 'email']);

$data = $request->session()->except(['username', 'email']);

Перевірка наявності елемента в сесії

Щоб визначити, чи присутній елемент у сесії, використовуйте метод has. Метод has повертає true, якщо елемент присутній і не дорівнює null:

if ($request->session()->has('users')) {
    // ...
}

Щоб визначити, чи присутній елемент у сесії, навіть якщо його значення null, використовуйте метод exists:

if ($request->session()->exists('users')) {
    // ...
}

Щоб визначити, чи елемента в сесії немає, використовуйте метод missing. Метод missing повертає true, якщо елемент відсутній:

if ($request->session()->missing('users')) {
    // ...
}

Збереження даних

Щоб зберегти дані в сесії, зазвичай використовують метод put екземпляра запиту або глобальний хелпер session:

// Через екземпляр запиту...
$request->session()->put('key', 'value');

// Через глобальний хелпер "session"...
session(['key' => 'value']);

Додавання до значень сесії-масивів

Метод push дозволяє додати нове значення до значення сесії, яке є масивом. Наприклад, якщо ключ user.teams містить масив назв команд, ви можете додати до масиву нове значення так:

$request->session()->push('user.teams', 'developers');

Отримання і видалення елемента

Метод pull отримує й видаляє елемент із сесії однією інструкцією:

$value = $request->session()->pull('key', 'default');

Збільшення і зменшення значень сесії

Якщо дані сесії містять ціле число, яке ви хочете збільшити або зменшити, використовуйте методи increment і decrement:

$request->session()->increment('count');

$request->session()->increment('count', $incrementBy = 2);

$request->session()->decrement('count');

$request->session()->decrement('count', $decrementBy = 2);

Flash-дані

Іноді потрібно зберегти елементи в сесії на наступний запит. Це робиться методом flash. Дані, збережені в сесії цим методом, доступні одразу і протягом наступного HTTP-запиту. Після наступного HTTP-запиту flash-дані видаляються. Flash-дані передусім корисні для короткочасних повідомлень про статус:

$request->session()->flash('status', 'Task was successful!');

Якщо потрібно зберегти flash-дані на кілька запитів, використовуйте метод reflash, який залишить усі flash-дані ще на один запит. Якщо треба залишити лише певні flash-дані, використовуйте метод keep:

$request->session()->reflash();

$request->session()->keep(['username', 'email']);

Щоб зберегти flash-дані тільки для поточного запиту, використовуйте метод now:

$request->session()->now('status', 'Task was successful!');

Видалення даних

Метод forget прибирає з сесії частину даних. Якщо потрібно прибрати з сесії всі дані, використовуйте метод flush:

// Забути один ключ...
$request->session()->forget('name');

// Забути кілька ключів...
$request->session()->forget(['name', 'status']);

$request->session()->flush();

Перегенерація ID сесії

Перегенерацію ID сесії часто роблять, щоб зловмисники не могли провести атаку фіксації сесії на ваш застосунок.

Laravel автоматично перегенеровує ID сесії під час автентифікації, якщо ви використовуєте один зі стартових наборів застосунку або Laravel Fortify; але якщо потрібно перегенерувати ID сесії вручну, використовуйте метод regenerate:

$request->session()->regenerate();

Якщо потрібно перегенерувати ID сесії й прибрати всі дані сесії однією інструкцією, використовуйте метод invalidate:

$request->session()->invalidate();

Кеш сесії

Кеш сесії в Laravel дає зручний спосіб кешувати дані в межах окремої сесії користувача. На відміну від глобального кешу застосунку, дані кешу сесії автоматично ізольовані для кожної сесії й очищаються, коли сесія завершується або знищується. Кеш сесії підтримує всі звичні методи кешу Laravel на зразок get, put, remember, forget та інші, але в межах поточної сесії.

Кеш сесії чудово підходить для тимчасових даних конкретного користувача, які мають пережити кілька запитів у межах однієї сесії, але не потребують постійного зберігання. Сюди належать дані форм, проміжні обчислення, відповіді API або будь-які інші ефемерні дані, привʼязані до сесії конкретного користувача.

Доступ до кешу сесії ви отримуєте через метод cache на сесії:

$discount = $request->session()->cache()->get('discount');

$request->session()->cache()->put(
    'discount', 10, now()->plus(minutes: 5)
);

Докладніше про методи кешу Laravel дивіться в документації про кеш.

Блокування сесії

Увага Щоб скористатися блокуванням сесії, ваш застосунок має використовувати драйвер кешу з підтримкою атомарних блокувань. Наразі це драйвери memcached, dynamodb, redis, mongodb (входить до офіційного пакета mongodb/laravel-mongodb), database, file і array. Крім того, ви не можете використовувати драйвер сесії cookie.

За замовчуванням Laravel дозволяє запитам з однією сесією виконуватися паралельно. Тобто, якщо ви робите два HTTP-запити до застосунку через JavaScript-бібліотеку, вони виконуватимуться одночасно. Для багатьох застосунків це не проблема; проте втрата даних сесії можлива в невеликій частині застосунків, які роблять паралельні запити до двох різних ендпоїнтів, і обидва пишуть дані в сесію.

Щоб цього уникнути, Laravel дає можливість обмежити паралельні запити для конкретної сесії. Для початку достатньо додати метод block до визначення маршруту. У цьому прикладі вхідний запит до ендпоїнта /profile отримає блокування сесії. Поки блокування утримується, будь-які вхідні запити до ендпоїнтів /profile чи /order з тим самим ID сесії чекатимуть, доки перший запит завершить виконання:

Route::post('/profile', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10);

Route::post('/order', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10);

Метод block приймає два необовʼязкові аргументи. Перший - максимальна кількість секунд, протягом яких утримується блокування сесії до його звільнення. Звісно, якщо запит завершиться раніше, блокування звільниться раніше.

Другий аргумент методу block - кількість секунд, протягом яких запит має чекати, намагаючись отримати блокування сесії. Якщо запит не зможе отримати блокування сесії за вказану кількість секунд, буде викинуто Illuminate\Contracts\Cache\LockTimeoutException.

Якщо жоден із цих аргументів не переданий, блокування отримується максимум на 10 секунд, а запити чекатимуть на отримання блокування максимум 10 секунд:

Route::post('/profile', function () {
    // ...
})->block();

Додавання власних драйверів сесії

Реалізація драйвера

Якщо жоден із наявних драйверів сесії не підходить під потреби вашого застосунку, Laravel дозволяє написати власний обробник сесії. Ваш власний драйвер сесії має реалізовувати вбудований у PHP SessionHandlerInterface. Цей інтерфейс містить лише кілька простих методів. Заготовка реалізації для MongoDB виглядає так:

<?php

namespace App\Extensions;

class MongoSessionHandler implements \SessionHandlerInterface
{
    public function open($savePath, $sessionName) {}
    public function close() {}
    public function read($sessionId) {}
    public function write($sessionId, $data) {}
    public function destroy($sessionId) {}
    public function gc($lifetime) {}
}

Laravel не містить стандартної теки для ваших розширень. Ви вільні розміщувати їх де завгодно. У цьому прикладі ми створили теку Extensions для MongoSessionHandler.

Оскільки призначення цих методів не є очевидним, ось огляд призначення кожного:

• Метод open зазвичай використовується у файлових системах зберігання сесій. Оскільки Laravel постачається з драйвером сесії file, вам рідко доведеться щось писати в цьому методі. Можете просто залишити його порожнім.
• Метод close, як і open, теж зазвичай можна ігнорувати. Для більшості драйверів він не потрібен.
• Метод read має повертати рядкову версію даних сесії, повʼязаних із вказаним $sessionId. Не потрібно виконувати жодної серіалізації чи іншого кодування під час отримання або збереження даних сесії у вашому драйвері, оскільки серіалізацію виконає Laravel.
• Метод write має записати вказаний рядок $data, повʼязаний із $sessionId, у якесь постійне сховище, наприклад MongoDB чи інше сховище на ваш вибір. Знову ж таки, вам не потрібно виконувати жодної серіалізації - Laravel уже подбав про це.
• Метод destroy має прибрати дані, повʼязані з $sessionId, із постійного сховища.
• Метод gc має знищити всі дані сесій, старші за вказаний $lifetime, який є UNIX-таймстемпом. Для систем із самостійним закінченням терміну дії, як Memcached і Redis, цей метод можна залишити порожнім.

Реєстрація драйвера

Коли ваш драйвер реалізовано, час зареєструвати його в Laravel. Щоб додати додаткові драйвери до бекенду сесії Laravel, використовуйте метод extend фасада Session. Викликати метод extend слід із методу boot сервіс-провайдера. Це можна зробити в наявному App\Providers\AppServiceProvider або створити цілком новий провайдер:

<?php

namespace App\Providers;

use App\Extensions\MongoSessionHandler;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Session;
use Illuminate\Support\ServiceProvider;

class SessionServiceProvider extends ServiceProvider
{
    /**
     * Реєстрація сервісів застосунку.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * Ініціалізація сервісів застосунку.
     */
    public function boot(): void
    {
        Session::extend('mongo', function (Application $app) {
            // Повернути реалізацію SessionHandlerInterface...
            return new MongoSessionHandler;
        });
    }
}

Після реєстрації драйвера сесії ви можете вказати драйвер mongo як драйвер сесії вашого застосунку через змінну оточення SESSION_DRIVER або у файлі конфігурації config/session.php.