From 3817efb521368bbb28dffca40db9a32f6de2662d Mon Sep 17 00:00:00 2001 From: serhio <10.1000.june@gmail.com> Date: Fri, 25 Oct 2024 03:04:27 +0300 Subject: [PATCH] Fully added Ukrainian lang for sessions-cookies docs --- docs/guide-uk/runtime-sessions-cookies.md | 185 +++++++++++----------- 1 file changed, 90 insertions(+), 95 deletions(-) diff --git a/docs/guide-uk/runtime-sessions-cookies.md b/docs/guide-uk/runtime-sessions-cookies.md index c23960d09b2..d90d1ea4018 100644 --- a/docs/guide-uk/runtime-sessions-cookies.md +++ b/docs/guide-uk/runtime-sessions-cookies.md @@ -1,147 +1,147 @@ -Сессии и куки +Сесії і кукі ==================== -Сессии и куки позволяют сохранять пользовательские данные между запросами. При использовании чистого PHP можно получить доступ к этим данным через глобальные переменные `$_SESSION` и `$_COOKIE`, соответственно. Yii инкапсулирует сессии и куки в объекты, что дает возможность обращаться к ним в объектно-ориентированном стиле и дает дополнительное удобство в работе. +Сесії та кукі дозволяють зберігати користувацькі дані між запитами. При використанні чистого PHP можна отримати доступ до цих даних через глобальні змінні `$_SESSION` та `$_COOKIE`, відповідно. Yii інкапсулює сесії та кукі в об'єкти, що дає можливість звертатися до них в об'єктно-орієнтованому стилі та забезпечує додаткову зручність в роботі. -## Сессии +## Сесії -По аналогии с [запросами](runtime-requests.md) и [ответами](runtime-responses.md), к сессии можно получить доступ через `session` [компонент приложения](structure-application-components.md), который по умолчанию является экземпляром [[yii\web\Session]]. +За аналогією з [запитами](runtime-requests.md) та [відповідями](runtime-responses.md), до сесій можна отримати доступ через `session` [компонент додатку](structure-application-components.md), який за замовчуванням є екземпляром [[yii\web\Session]]. -### Открытие и закрытие сессии +### Відкриття та закриття сесії -Открыть и закрыть сессию можно следующим образом: +Відкрити та закрити сесію можна наступним чином: ```php $session = Yii::$app->session; -// проверяем что сессия уже открыта +// перевіряєм що сесія вже відкрита if ($session->isActive) ... -// открываем сессию +// відкиваєм сесію $session->open(); -// закрываем сессию +// закриваємо сесію $session->close(); -// уничтожаем сессию и все связанные с ней данные. +// знищуємо сесію і всі пов'язані з нею дані. $session->destroy(); ``` -Можно вызывать [[yii\web\Session::open()|open()]] и [[yii\web\Session::close()|close()]] многократно без возникновения ошибок; внутри компонента все методы проверяют сессию на факт того, открыта она или нет. +Можна викликати [[yii\web\Session::open()|open()]] і [[yii\web\Session::close()|close()]] багаторазово без виникнення помилок; всередині компонента всі методи перевіряють сесію на те, відкрита вона чи ні. -### Доступ к данным сессии +### Доступ до даних сесії -Получить доступ к сохраненным в сессию данным можно следующим образом: +Отримати доступ до збережених в сесію даних можна наступним чином: ```php $session = Yii::$app->session; -// получение переменной из сессии. Следующие способы использования эквивалентны: +// отримання змінної з сесії. Наступні способи використання еквівалентні: $language = $session->get('language'); $language = $session['language']; $language = isset($_SESSION['language']) ? $_SESSION['language'] : null; -// запись переменной в сессию. Следующие способы использования эквивалентны: +// запис змінної в сесію. Наступні способи використання еквівалентні: $session->set('language', 'en-US'); $session['language'] = 'en-US'; $_SESSION['language'] = 'en-US'; -// Удаление переменной из сессии. Следующие способы использования эквивалентны: +// видалення змінної з сесії. Наступні способи використання еквівалентні: $session->remove('language'); unset($session['language']); unset($_SESSION['language']); -// проверка на существование переменной в сессии. Следующие способы использования эквивалентны: +// перевірка на існування змінної в сесії. Наступні способи використання еквівалентні: if ($session->has('language')) ... if (isset($session['language'])) ... if (isset($_SESSION['language'])) ... -// Обход всех переменных в сессии. Следующие способы использования эквивалентны: +// обхід усіх змінних у сесії. Наступні способи використання еквівалентні: foreach ($session as $name => $value) ... foreach ($_SESSION as $name => $value) ... ``` -> Info: При получении данных из сессии через компонент `session`, сессия будет автоматически открыта, если она не была открыта до этого. В этом заключается отличие от получения данных из глобальной переменной `$_SESSION`, которое требует обязательного вызова `session_start()`. +> Info: При отриманні даних з сесії через компонент `session`, сесія буде автоматично відкрита, якщо вона не була відкрита до цього. У цьому полягає відмінність від отримання даних з глобальної змінної `$_SESSION`, що вимагає обов'язкового виклику `session_start()`. -При работе с сессионными данными, являющимися массивами, компонент `session` имеет ограничение, запрещающее прямую модификацию отдельных элементов массива. Например, +При роботі з сесійними даними, які є масивами, компонент `session` має обмеження, що забороняє пряму модифікацію окремих елементів масиву. Наприклад, ```php $session = Yii::$app->session; -// следующий код НЕ БУДЕТ работать +// наступний код НЕ БУДЕ працювати $session['captcha']['number'] = 5; $session['captcha']['lifetime'] = 3600; -// а этот будет: +// а цей буде: $session['captcha'] = [ 'number' => 5, 'lifetime' => 3600, ]; -// этот код также будет работать: +// цей код також буде працювати: echo $session['captcha']['lifetime']; ``` -Для решения этой проблемы можно использовать следующие обходные приемы: +Для вирішення цієї проблеми можна використовувати такі обхідні прийоми: ```php $session = Yii::$app->session; -// прямое использование $_SESSION (убедитесь, что Yii::$app->session->open() был вызван) +// пряме використання $_SESSION (переконайтеся, що Yii::$app->session->open() був викликаний) $_SESSION['captcha']['number'] = 5; $_SESSION['captcha']['lifetime'] = 3600; -// получите весь массив, модифицируйте и сохраните обратно в сессию +// отримайте весь масив, модифікуйте і збережіть назад у сесію $captcha = $session['captcha']; $captcha['number'] = 5; $captcha['lifetime'] = 3600; $session['captcha'] = $captcha; -// используйте ArrayObject вместо массива +// використовуйте ArrayObject замість масиву $session['captcha'] = new \ArrayObject; ... $session['captcha']['number'] = 5; $session['captcha']['lifetime'] = 3600; -// записывайте данные с ключами, имеющими одинаковый префикс +// записуйте дані з ключами, які мають однаковий префікс $session['captcha.number'] = 5; $session['captcha.lifetime'] = 3600; ``` -Для улучшения производительности и читаемости кода рекомендуется использовать последний прием. Другими словами, вместо того, чтобы хранить массив как одну переменную сессии, мы сохраняем каждый элемент массива как обычную сессионную переменную с общим префиксом. +Для покращення продуктивності та читабельності коду рекомендується використовувати останній прийом. Іншими словами, замість того, щоб зберігати масив як одну змінну сесії, ми зберігаємо кожен елемент масиву як звичайну сесійну змінну зі спільним префіксом. -### Пользовательское хранилище для сессии +### Користувацьке сховище для сесії -По умолчанию класс [[yii\web\Session]] сохраняет данные сессии в виде файлов на сервере. Однако Yii предоставляет ряд классов, которые реализуют различные способы хранения данных сессии: +За замовчуванням клас [[yii\web\Session]] зберігає дані сесії у вигляді файлів на сервері. Однак Yii надає ряд класів, які реалізують різні способи зберігання даних сесії: -* [[yii\web\DbSession]]: сохраняет данные сессии в базе данных. -* [[yii\web\CacheSession]]: хранение данных сессии в предварительно сконфигурированном компоненте кэша [кэш](caching-data.md#cache-components). -* [[yii\redis\Session]]: хранение данных сессии в [redis](https://redis.io/). -* [[yii\mongodb\Session]]: хранение сессии в [MongoDB](https://www.mongodb.com/). +* [[yii\web\DbSession]]: зберігає дані сесії в базі даних. +* [[yii\web\CacheSession]]: зберігання даних сесії в попередньо сконфігурованому компоненті кешу [кеш](caching-data.md#cache-components). +* [[yii\redis\Session]]: зберігання даних сесії в [redis](https://redis.io/). +* [[yii\mongodb\Session]]: зберігання сесії в [MongoDB](https://www.mongodb.com/). -Все эти классы поддерживают одинаковый набор методов API. В результате вы можете переключаться между различными хранилищами сессий без модификации кода приложения. +Усі ці класи підтримують однаковий набір методів API. В результаті ви можете перемикатися між різними сховищами сесій без модифікації коду додатку. -> Note: Если вы хотите получить данные из переменной `$_SESSION` при использовании пользовательского хранилища, вы должны быть уверены, что сессия уже стартовала [[yii\web\Session::open()]], в связи с тем, что обработчики хранения пользовательских сессий регистрируются в этом методе. +> Note: Якщо ви хочете отримати дані з змінної `$_SESSION` при використанні користувацького сховища, ви повинні бути впевнені, що сесія вже стартувала [[yii\web\Session::open()]], оскільки обробники зберігання користувацьких сесій реєструються в цьому методі. -Чтобы узнать, как настроить и использовать эти компоненты, обратитесь к документации по API. Ниже приведен пример конфигурации [[yii\web\DbSession]] для использования базы данных для хранения сессии: +Щоб дізнатися, як налаштувати і використовувати ці компоненти, зверніться до документації по API. Нижче наведено приклад конфігурації [[yii\web\DbSession]] для використання бази даних для зберігання сесії: ```php return [ 'components' => [ 'session' => [ 'class' => 'yii\web\DbSession', - // 'db' => 'mydb', // ID компонента для взаимодействия с БД. По умолчанию 'db'. - // 'sessionTable' => 'my_session', // название таблицы для хранения данных сессии. По умолчанию 'session'. + // 'db' => 'mydb', // ID компонента для взаємодії з БД. По замовчуванню 'db'. + // 'sessionTable' => 'my_session', // назва таблиці для даних сесії. По замовчуванню 'session'. ], ], ]; ``` -Также необходимо создать таблицу для хранения данных сессии: +Також необхідно створити таблицю для зберігання даних сесії: ```sql CREATE TABLE session @@ -152,129 +152,125 @@ CREATE TABLE session ) ``` -где 'BLOB' соответствует типу данных предпочитаемой вами DBMS. Ниже приведены примеры соответствия типов BLOB в наиболее популярных DBMS: +де 'BLOB' відповідає типу даних вашої DBMS. Нижче наведені приклади відповідності типів BLOB у найбільш популярних DBMS: - MySQL: LONGBLOB - PostgreSQL: BYTEA - MSSQL: BLOB -> Note: В зависимости от настроек параметра `session.hash_function` в вашем php.ini, может понадобиться изменить длину поля `id`. Например, если `session.hash_function=sha256`, нужно установить длину поля в 64 вместо 40. +> Note: В залежності від налаштувань параметра `session.hash_function` у вашому php.ini, може знадобитися змінити довжину поля `id`. Наприклад, якщо `session.hash_function=sha256`, потрібно встановити довжину поля на 64 замість 40. +### Flash-повідомлення -### Flash-сообщения +Flash-повідомлення - це особливий тип даних у сесії, які встановлюються один раз під час запиту і доступні лише протягом наступного запиту, після чого вони автоматично видаляються. Такий спосіб зберігання інформації в сесії найчастіше використовується для реалізації повідомлень, які будуть відображені кінцевому користувачу один раз, наприклад, підтвердження про успішну відправку форми. -Flash-сообщения - это особый тип данных в сессии, которые устанавливаются один раз во время запроса и доступны только на протяжении следующего запроса, затем они автоматически удаляются. Такой способ хранения информации в сессии наиболее часто используется для реализации сообщений, которые будут отображены конечному пользователю один раз, например подтверждение об успешной отправке формы. - -Установить и получить flash-сообщения можно через компонент приложения `session`. Например: +Встановити та отримати flash-повідомлення можна через компонент програми `session`. Наприклад: ```php $session = Yii::$app->session; -// Запрос #1 -// установка flash-сообщения с названием "postDeleted" -$session->setFlash('postDeleted', 'Вы успешно удалили пост.'); +// Запит #1 +// встановлення flash-повідомлення з назвою "postDeleted" +$session->setFlash('postDeleted', 'Ви успішно видалили пост.'); -// Запрос #2 -// отображение flash-сообщения "postDeleted" +// Запит #2 +// відображення flash-повідомлення "postDeleted" echo $session->getFlash('postDeleted'); -// Запрос #3 -// переменная $result будет иметь значение false, так как flash-сообщение было автоматически удалено +// Запит #3 +// змінна $result буде мати значення false, оскільки flash-повідомлення було автоматично видалено $result = $session->hasFlash('postDeleted'); ``` -Так как flash-сообщения хранятся в сессии как обычные данные, в них можно записывать произвольную информацию, и она будет доступна лишь в следующем запросе. +Оскільки flash-повідомлення зберігаються в сесії як звичайні дані, в них можна записувати довільну інформацію, і вона буде доступна лише в наступному запиті. -При вызове [[yii\web\Session::setFlash()]], происходит перезаписывание flash-сообщений c таким же названием. -Для того, чтобы добавить новые данные к уже существующему flash-сообщению, необходимо вызвать [[yii\web\Session::addFlash()]]. -Например: +При виклику [[yii\web\Session::setFlash()]] відбувається перезаписування flash-повідомлень з таким же назвою. Для того, щоб додати нові дані до вже існуючого flash-повідомлення, необхідно викликати [[yii\web\Session::addFlash()]]. +Наприклад: ```php $session = Yii::$app->session; -// Запрос #1 -// добавить новое flash-сообщение с названием "alerts" -$session->addFlash('alerts', 'Вы успешно удалили пост.'); -$session->addFlash('alerts', 'Вы успешно добавили нового друга.'); -$session->addFlash('alerts', 'Благодарим.'); +// Запит #1 +// додати нове flash-повідомлення з назвою "alerts" +$session->addFlash('alerts', 'Ви успішно видалили пост.'); +$session->addFlash('alerts', 'Ви успішно додали нового друга.'); +$session->addFlash('alerts', 'Дякуємо.'); -// Запрос #2 -// Переменная $alerts теперь содержит массив flash-сообщений с названием "alerts" +// Запит #2 +// Змінна $alerts тепер містить масив flash-повідомлень з назвою "alerts" $alerts = $session->getFlash('alerts'); ``` -> Note: Старайтесь не использовать [[yii\web\Session::setFlash()]] совместно с [[yii\web\Session::addFlash()]] для flash-сообщений с одинаковым названием. Это связано с тем, что последний метод автоматически преобразует хранимые данные в массив, чтобы иметь возможность хранить и добавлять новые данные в flash-сообщения с тем же названием. В результате, при вызове [[yii\web\Session::getFlash()]] можно обнаружить, что возвращается массив, в то время как ожидалась строка. - - -## Куки +> Note: Намагайтеся не використовувати [[yii\web\Session::setFlash()]] спільно з [[yii\web\Session::addFlash()]] для flash-повідомлень з однаковою назвою. Це пов'язано з тим, що останній метод автоматично перетворює збережені дані в масив, щоб мати можливість зберігати та додавати нові дані в flash-повідомлення з тією ж назвою. В результаті, при виклику [[yii\web\Session::getFlash()]] можна виявити, що повертається масив, тоді як очікувалася строка. -Yii представляет каждую куку как объект [[yii\web\Cookie]]. Оба компонента приложения [[yii\web\Request]] и [[yii\web\Response]] -поддерживают коллекции кук через свойство `cookies`. В первом случае коллекция кук является их представлением из HTTP-запроса, во втором - представляет куки, которые будут отправлены пользователю. +## Кукі +Yii представляє кожну з cookie як об'єкт [[yii\web\Cookie]]. Обидва компоненти програми [[yii\web\Request]] і [[yii\web\Response]] +підтримують колекції кукі через своє властивість cookies. У першому випадку колекція кукі є їх представленням з HTTP-запиту, у другому — представляє кукі, які будуть відправлені користувачу. -### Чтение кук +### Читання кукі -Получить куки из текущего запроса можно следующим образом: +Отримати кукі з поточного запиту можна наступним чином: ```php -// получение коллекции кук (yii\web\CookieCollection) из компонента "request" +// отримання колекції кукі (yii\web\CookieCollection) з компонента "request" $cookies = Yii::$app->request->cookies; -// получение куки с названием "language. Если кука не существует, "en" будет возвращено как значение по-умолчанию. +// отримання кукі з назвою "language". Якщо кукі не існує, "en" буде повернуто як значення за замовчуванням. $language = $cookies->getValue('language', 'en'); -// альтернативный способ получения куки "language" +// альтернативний спосіб отримання кукі "language" if (($cookie = $cookies->get('language')) !== null) { $language = $cookie->value; } -// теперь переменную $cookies можно использовать как массив +// тепер змінну $cookies можна використовувати як масив if (isset($cookies['language'])) { $language = $cookies['language']->value; } -// проверка на существование куки "language" +// перевірка на існування кукі "language" if ($cookies->has('language')) ... if (isset($cookies['language'])) ... ``` -### Отправка кук +### Відправка кукі -Отправить куку конечному пользователю можно следующим образом: +Відправити кукі кінцевому користувачу можна наступним чином: ```php -// получение коллекции (yii\web\CookieCollection) из компонента "response" +// отримання колекції (yii\web\CookieCollection) з компонента "response" $cookies = Yii::$app->response->cookies; -// добавление новой куки в HTTP-ответ +// додавання нової кукі в HTTP-відповідь $cookies->add(new \yii\web\Cookie([ 'name' => 'language', 'value' => 'zh-CN', ])); -// удаление куки... +// видалення кукі... $cookies->remove('language'); -// ...что эквивалентно следующему: +// ...що еквівалентно наступному: unset($cookies['language']); ``` -Кроме свойств [[yii\web\Cookie::name|name]] и [[yii\web\Cookie::value|value]], класс [[yii\web\Cookie]] также предоставляет ряд свойств для получения информации о куках: [[yii\web\Cookie::domain|domain]], [[yii\web\Cookie::expire|expire]]. Эти свойства можно сконфигурировать и затем добавить куку в коллекцию для HTTP-ответа. +Крім властивостей [[yii\web\Cookie::name|name]] та [[yii\web\Cookie::value|value]], клас [[yii\web\Cookie]] також надає ряд властивостей для отримання інформації про куки: [[yii\web\Cookie::domain|domain]], [[yii\web\Cookie::expire|expire]]. Ці властивості можна сконфігурувати, а потім додати кукі в колекцію для HTTP-відповіді. -> Note: Для большей безопасности значение свойства [[yii\web\Cookie::httpOnly]] по умолчанию установлено в `true`. Это уменьшает риски доступа к защищенной куке на клиентской стороне (если браузер поддерживает такую возможность). Вы можете обратиться к [httpOnly wiki](https://owasp.org/www-community/HttpOnly) для дополнительной информации. +> Note: Для більшої безпеки значення властивості [[yii\web\Cookie::httpOnly]] за замовчуванням встановлено в `true`. Це зменшує ризики доступу до захищеної кукі на клієнтській стороні (якщо браузер підтримує таку можливість). Ви можете звернутися до [httpOnly wiki](https://owasp.org/www-community/HttpOnly) для додаткової інформації. -### Валидация кук +### Валідація кукі -Во время записи и чтения кук через компоненты `request` и `response`, как будет показано в двух последующих подразделах, фреймворк предоставляет автоматическую валидацию, которая обеспечивает защиту кук от модификации на стороне клиента. Это достигается за счет подписи каждой куки секретным ключом, позволяющим приложению распознать куку, которая была модифицирована на клиентской стороне. В таком случае кука НЕ БУДЕТ доступна через свойство [[yii\web\Request::cookies|cookie collection]] компонента `request`. +Під час запису та читання куків через компоненти `request` та `response`, як буде показано в двох наступних підрозділах, фреймворк надає автоматичну валідацію, яка забезпечує захист кукі від модифікації на стороні клієнта. Це досягається завдяки підписанню кожної кукі секретним ключем, що дозволяє додатку розпізнавати кукі, які були модифіковані на клієнтській стороні. У такому випадку кукі НЕ БУДЕ доступна через властивість [[yii\web\Request::cookies|cookie collection]] компонента `request`. -> Note: Валидация кук защищает только от их модификации. Если валидация не была пройдена, получить доступ к кукам все еще можно через глобальную переменную `$_COOKIE`. Это связано с тем, что дополнительные пакеты и библиотеки могут манипулировать куками без вызова валидации, которую обеспечивает Yii. +> Note: Валідація кукі захищає тільки від їх модифікації. Якщо валідація не була пройдена, отримати доступ до кукі все ще можна через глобальну змінну `$_COOKIE`. Це пов'язано з тим, що додаткові пакети та бібліотеки можуть маніпулювати кукі без виклику валідації, яку забезпечує Yii. -По-умолчанию валидация кук включена. Её можно отключить, установив свойство [[yii\web\Request::enableCookieValidation]] -в `false`, однако мы настоятельно не рекомендуем это делать. -> Note: Куки, которые напрямую читаются/пишутся через `$_COOKIE` и `setcookie()` НЕ БУДУТ валидироваться. +За замовчуванням валідація кукі увімкнена. Її можна вимкнути, встановивши властивість [[yii\web\Request::enableCookieValidation]] в `false`, однак ми настійливо не рекомендуємо цього робити. -При использовании валидации кук необходимо указать значение свойства [[yii\web\Request::cookieValidationKey]], которое будет использовано для генерации вышеупомянутого секретного ключа. Это можно сделать, настроив компонент `request` в конфигурации приложения: +> Note: Кукі, які безпосередньо читаються/пишуться через `$_COOKIE` та `setcookie()`, НЕ БУДУТЬ валідовуватися. + +При використанні валідації кукі необхідно вказати значення властивості [[yii\web\Request::cookieValidationKey]], яке буде використано для генерації згаданого вище секретного ключа. Це можна зробити, налаштувавши компонент `request` у конфігурації додатка: ```php return [ @@ -286,5 +282,4 @@ return [ ]; ``` -> Note: Свойство [[yii\web\Request::cookieValidationKey|cookieValidationKey]] является секретным значением и должно быть известно только людям, которым вы доверяете. Не помещайте эту информацию под систему контроля версий. - +> Note: Властивість [[yii\web\Request::cookieValidationKey|cookieValidationKey]] є секретним значенням і повинно бути відомо лише тим, кому ви довіряєте. Не розміщуйте цю інформацію в системі контролю версій.