HTTP-ответы

Класс Response расширяет класс HTTP-сообщение методами, подходящими только для сервера, отвечающего клиенту, который его вызвал.

• Работа с ответом
  • Установка выходных данных
  • Установка заголовков
• Принудительное скачивание файла
• Кэширование HTTP
• Политика безопасности контента
  • Включение CSP
  • Настройка во время выполнения
  • Встраиваемый контент
• Справочник по классу

Работа с ответом

Для вас создается экземпляр класса Response и передается в ваши контроллеры. К нему можно получить доступ через $this->response. Часто вам не нужно будет работать с классом напрямую, так как CodeIgniter позаботится о отправке заголовков и тела для вас. Это отлично, если страница успешно создала запрошенный контент. Когда что-то идет не так, или вам нужно отправить очень специфичные коды состояния, или даже воспользоваться мощным кэшированием HTTP, он вам пригодится.

Установка выходных данных

Когда вам нужно установить выходные данные скрипта напрямую, не полагаясь на автоматическое получение CodeIgniter, вы делаете это вручную с помощью метода setBody. Обычно это используется в сочетании с установкой кода состояния ответа:

$this->response->setStatusCode(404)->setBody($body);

Фраза причины (‘OK’, ‘Created’, ‘Moved Permanently’) будет автоматически добавлена, но вы можете добавить пользовательские фразы в качестве второго параметра метода setStatusCode().

$this->response->setStatusCode(404, 'Nope. Not here.');

Вы можете преобразовать массив в JSON или XML и установить соответствующий MIME-тип для заголовка Content-Type с помощью методов setJSON и setXML. Обычно вы отправляете массив данных для преобразования:

$data = [
    'success' => true,
    'id' => 123,
];

return $this->response->setJSON($data);
// or
return $this->response->setXML($data);

Установка заголовков

Часто вам нужно установить заголовки для ответа. Класс Response делает это очень просто с помощью метода setHeader(). Первый параметр — имя заголовка. Второй параметр — значение, которое может быть строкой или массивом значений, которые будут правильно объединены при отправке клиенту. Использование этих функций вместо использования собственных функций PHP позволяет убедиться, что заголовки не отправляются преждевременно, вызывая ошибки, и делает возможным тестирование.

$response->setHeader('Location', 'http://example.com')
         ->setHeader('WWW-Authenticate', 'Negotiate');

Если заголовок существует и может иметь более одного значения, вы можете использовать методы appendHeader() и prependHeader() для добавления значения в конец или начало списка значений соответственно. Первый параметр — имя заголовка, а второй — значение для добавления в конец или в начало.

$response->setHeader('Cache-Control', 'no-cache')
         ->appendHeader('Cache-Control', 'must-revalidate');

Заголовки могут быть удалены из ответа с помощью метода removeHeader(), который принимает имя заголовка в качестве единственного параметра. Регистр не учитывается.

$response->removeHeader('Location');

Принудительное скачивание файла

Класс Response предоставляет простой способ отправки файла клиенту, заставляя браузер загрузить данные на ваш компьютер. Он устанавливает соответствующие заголовки для этого.

Первый параметр — имя, которое вы хотите использовать для загружаемого файла, второй параметр — данные файла.

Если вы установите второй параметр в значение null, а $filename — это существующий, доступный для чтения путь к файлу, тогда его содержимое будет считано вместо данных.

Если вы установите третий параметр в булевое значение true, то будет отправлен фактический MIME-тип файла (на основе расширения имени файла), так что если ваш браузер имеет обработчик для этого типа, он может его использовать.

Пример:

$data = 'Here is some text!';
$name = 'mytext.txt';
return $response->download($name, $data);

Если вы хотите загрузить существующий файл с вашего сервера, вам нужно явно указать null для второго параметра:

// Contents of photo.jpg will be automatically read
return $response->download('/path/to/photo.jpg', null);

Используйте необязательный метод setFileName() для изменения имени файла при отправке в браузер клиента:

return $response->download('awkwardEncryptedFileName.fakeExt', null)->setFileName('expenses.csv');

Кэширование HTTP

В спецификации HTTP есть инструменты, которые помогают клиенту (часто веб-браузеру) кэшировать результаты. При правильном использовании это может значительно повысить производительность вашего приложения, потому что оно сообщит клиенту, что ему не нужно вообще обращаться к серверу, так как ничего не изменилось. И вы не сможете получить больше скорости, чем это.

Это обрабатывается с помощью заголовков Cache-Control и ETag. Это руководство — не подходящее место для подробного введения во все возможности заголовков кэша, но вы можете получить хорошее представление на сайте Google Developers.

По умолчанию все объекты ответа, отправленные через CodeIgniter, имеют кэширование HTTP выключено. Параметры и точные обстоятельства слишком разнообразны, чтобы мы могли установить хорошее значение по умолчанию, кроме как выключить его. Просто установите значения кэша, которые вам нужны, с помощью метода setCache():

$options = [
    'max-age'  => 300,
    's-maxage' => 900,
    'etag'     => 'abcde'
];
$this->response->setCache($options);

Массив $options просто принимает массив пар «ключ-значение», которые, за несколькими исключениями, присваиваются заголовку Cache-Control. Вы можете настроить все параметры точно так, как вам нужно для вашей конкретной ситуации. Хотя большинство параметров применяются к заголовку Cache-Control, он разумно обрабатывает параметры etag и last-modified для соответствующего заголовка.

Политика безопасности контента

Одним из лучших способов защиты от атак XSS является реализация политики безопасности контента на сайте. Это заставляет вас создавать белый список каждого источника контента, который извлекается из HTML вашего сайта, включая изображения, таблицы стилей, файлы JavaScript и т. д. Браузер отклонит контент из источников, которые не соответствуют белому списку. Этот белый список создается в заголовке Content-Security-Policy ответа и может быть настроен различными способами.

Это звучит сложно, и на некоторых сайтах это действительно может быть проблематично. Однако на многих простых сайтах, где весь контент обслуживается с одного домена (http://example.com), это очень просто интегрировать.

Поскольку это сложная тема, это руководство пользователя не будет рассматривать все детали. Для получения дополнительной информации посетите следующие сайты:

• Основной сайт политики безопасности контента
• Спецификация W3C
• Введение на HTML5Rocks
• Статья на SitePoint

Включение CSP

По умолчанию поддержка отключена. Чтобы включить поддержку в вашем приложении, измените значение CSPEnabled в файле app/Config/App.php:

public $CSPEnabled = true;

При включении объект ответа будет содержать экземпляр CodeIgniter\HTTP\ContentSecurityPolicy. Значения, установленные в файле app/Config/ContentSecurityPolicy.php, применяются к этому экземпляру, и если изменения не нужны во время выполнения, то заголовок с правильным форматом отправляется, и все готово.

При включенном CSP в HTTP-ответе добавляются две строки заголовков: заголовок Content-Security-Policy с политиками, определяющими типы контента или источники, которые явно разрешены для разных контекстов, и заголовок Content-Security-Policy-Report-Only, который определяет типы контента или источники, которые будут разрешены, но которые также будут сообщены в место назначения по вашему выбору.

Наша реализация предоставляет обработку по умолчанию, изменяемую с помощью метода reportOnly(). Когда к директиве CSP добавляется дополнительная запись, как показано ниже, она будет добавлена в заголовок CSP, соответствующий блокированию или предотвращению. Это можно переопределить на основе каждого вызова, предоставив необязательный второй параметр вызову метода добавления.

Настройка во время выполнения

Если ваше приложение нуждается в внесении изменений во время выполнения, вы можете получить доступ к экземпляру по адресу $response->CSP. Класс содержит ряд методов, которые довольно четко отображаются на соответствующее значение заголовка, которое вам нужно установить. Примеры показаны ниже с различными сочетаниями параметров, хотя все они принимают либо имя директивы, либо массив из них.:

// specify the default directive treatment
$response->CSP->reportOnly(false);

// specify the origin to use if none provided for a directive
$response->CSP->setDefaultSrc('cdn.example.com');

// specify the URL that "report-only" reports get sent to
$response->CSP->setReportURI('http://example.com/csp/reports');

// specify that HTTP requests be upgraded to HTTPS
$response->CSP->upgradeInsecureRequests(true);

// add types or origins to CSP directives
// assuming that the default treatment is to block rather than just report
$response->CSP->addBaseURI('example.com', true); // report only
$response->CSP->addChildSrc('https://youtube.com'); // blocked
$response->CSP->addConnectSrc('https://*.facebook.com', false); // blocked
$response->CSP->addFontSrc('fonts.example.com');
$response->CSP->addFormAction('self');
$response->CSP->addFrameAncestor('none', true); // report this one
$response->CSP->addImageSrc('cdn.example.com');
$response->CSP->addMediaSrc('cdn.example.com');
$response->CSP->addManifestSrc('cdn.example.com');
$response->CSP->addObjectSrc('cdn.example.com', false); // reject from here
$response->CSP->addPluginType('application/pdf', false); // reject this media type
$response->CSP->addScriptSrc('scripts.example.com', true); // allow but report requests from here
$response->CSP->addStyleSrc('css.example.com');
$response->CSP->addSandbox(['allow-forms', 'allow-scripts']);

Первый параметр каждого из методов «add» — соответствующее строковое значение или массив из них.

Метод reportOnly позволяет указать обработку отчетов по умолчанию для последующих источников, если она не переопределена. Например, вы можете указать, что youtube.com разрешен, а затем предоставить несколько разрешенных, но сообщаемых источников:

$response->addChildSrc('https://youtube.com'); // allowed
$response->reportOnly(true);
$response->addChildSrc('https://metube.com'); // allowed but reported
$response->addChildSrc('https://ourtube.com',false); // allowed

Встраиваемый контент

Возможно установить веб-сайт так, чтобы он не защищал даже встроенные скрипты и стили на своих собственных страницах, так как это может быть результатом контента, сгенерированного пользователем. Для защиты от этого CSP позволяет указать nonce в тегах <style> и <script>, а также добавить эти значения в заголовок ответа. Это сложно обрабатывать в реальной жизни, и наиболее безопасный способ — генерировать их на лету. Чтобы это упростить, вы можете включить заполнитель {csp-style-nonce} или {csp-script-nonce} в тег, и он будет автоматически обработан для вас:

// Original
<script {csp-script-nonce}>
    console.log("Script won't run as it doesn't contain a nonce attribute");
</script>

// Becomes
<script nonce="Eskdikejidojdk978Ad8jf">
    console.log("Script won't run as it doesn't contain a nonce attribute");
</script>

// OR
<style {csp-style-nonce}>
    . . .
</style>

Справочник по классу

Доступные методы родительского класса:

• CodeIgniter\HTTP\Message::body()
• CodeIgniter\HTTP\Message::setBody()
• CodeIgniter\HTTP\Message::populateHeaders()
• CodeIgniter\HTTP\Message::headers()
• CodeIgniter\HTTP\Message::header()
• CodeIgniter\HTTP\Message::headerLine()
• CodeIgniter\HTTP\Message::setHeader()
• CodeIgniter\HTTP\Message::removeHeader()
• CodeIgniter\HTTP\Message::appendHeader()
• CodeIgniter\HTTP\Message::protocolVersion()
• CodeIgniter\HTTP\Message::setProtocolVersion()
• CodeIgniter\HTTP\Message::negotiateMedia()
• CodeIgniter\HTTP\Message::negotiateCharset()
• CodeIgniter\HTTP\Message::negotiateEncoding()
• CodeIgniter\HTTP\Message::negotiateLanguage()
• CodeIgniter\HTTP\Message::negotiateLanguage()

CodeIgniter\HTTP\Response

getStatusCode()

Возвращает:	Текущий HTTP-код состояния для этого ответа
Тип возвращаемого значения:	int

Возвращает текущий код состояния для этого ответа. Если код состояния не был установлен, будет выброшено исключение BadMethodCallException:

echo $response->getStatusCode();

setStatusCode($code[, $reason=''])

Параметры:	$code (int) – HTTP-код состояния $reason (string) – Необязательная фраза причины.
Возвращает:	Текущий экземпляр Response
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает HTTP-код состояния, который должен быть отправлен с этим ответом:

$response->setStatusCode(404);

Фраза причины будет автоматически сгенерирована на основе официальных списков. Если вам нужно установить свою собственную для пользовательского кода состояния, вы можете передать фразу причины как второй параметр:

$response->setStatusCode(230, "Tardis initiated");

getReasonPhrase()

Возвращает:	Текущая фраза причины.
Тип возвращаемого значения:	string

Возвращает текущий код состояния для этого ответа. Если состояние не было установлено, возвращает пустую строку:

echo $response->getReasonPhrase();

setDate($date)

Параметры:	$date (DateTime) – Экземпляр DateTime с временем, которое нужно установить для этого ответа.
Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает дату, используемую для этого ответа. Аргумент $date должен быть экземпляром DateTime:

$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2016');
$response->setDate($date);

setContentType($mime[, $charset='UTF-8'])

Параметры:	$mime (string) – Тип содержимого, который представляет этот ответ. $charset (string) – Кодировка символов, используемая этим ответом.
Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает тип содержимого, который представляет этот ответ:

$response->setContentType('text/plain');
$response->setContentType('text/html');
$response->setContentType('application/json');

По умолчанию метод устанавливает кодировку символов в UTF-8. Если вам нужно изменить это, вы можете передать кодировку символов как второй параметр:

$response->setContentType('text/plain', 'x-pig-latin');

noCache()

Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает заголовок Cache-Control для отключения всех механизмов кэширования HTTP. Это значение по умолчанию для всех сообщений ответа:

$response->noCache();

// Sets the following header:
Cache-Control: no-store, max-age=0, no-cache

setCache($options)

Параметры:	$options (array) – Массив пар «ключ-значение» настроек кэширования
Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает заголовки Cache-Control, включая ETags и Last-Modified. Типичные ключи:

• etag
• last-modified
• max-age
• s-maxage
• private
• public
• must-revalidate
• proxy-revalidate
• no-transform

При передаче параметра last-modified, он может быть либо строкой даты, либо объектом DateTime.

setLastModified($date)

Параметры:	$date (string|DateTime) – Дата, которой нужно установить заголовок Last-Modified
Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Устанавливает заголовок Last-Modified. Объект $date может быть строкой или экземпляром DateTime:

$response->setLastModified(date('D, d M Y H:i:s'));
$response->setLastModified(DateTime::createFromFormat('u', $time));

send(): Response

Возвращает:	Текущий экземпляр ответа.
Тип возвращаемого значения:	CodeIgniter\HTTP\Response

Указывает ответу отправить все обратно клиенту. Сначала будут отправлены заголовки, затем тело ответа. Для основного ответа приложения вызывать это не нужно, так как это обрабатывается автоматически CodeIgniter.

setCookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = false[, $httponly = false[, $samesite = null]]]]]]]])

Параметры:

$name (mixed) – Имя куки или массив параметров $value (string) – Значение куки $expire (int) – Время истечения срока действия куки в секундах $domain (string) – Домен куки $path (string) – Путь куки $prefix (string) – Префикс имени куки $secure (bool) – Только передавать куки через HTTPS $httponly (bool) – Только доступно для HTTP-запросов (без JavaScript) $samesite (string) – Значение параметра SameSite для куки. Если установлено '', атрибут SameSite не будет установлен для куки. Если установлено null, будет использовано значение по умолчанию из config/App.php

Тип возвращаемого значения:

void

Устанавливает куки с указанными значениями. Есть два способа передать данные этому методу для установки куки: метод массива и отдельные параметры:

Метод массива

С помощью этого метода в качестве первого параметра передается ассоциативный массив:

$cookie = [
    'name'   => 'The Cookie Name',
    'value'  => 'The Value',
    'expire' => '86500',
    'domain' => '.some-domain.com',
    'path'   => '/',
    'prefix' => 'myprefix_',
    'secure' => true,
    'httponly' => false,
    'samesite' => 'Lax'
];

$response->setCookie($cookie);

Примечания

Требуются только имя и значение. Для удаления куки установите время истечения срока действия в пустое значение.

Время истечения срока действия устанавливается в секундах, которые будут добавлены к текущему времени. Не указывайте время, а только количество секунд от текущего времени, в течение которого вы хотите, чтобы куки была действительна. Если время истечения срока действия установлено на ноль, куки будет действовать только до тех пор, пока браузер открыт.

Для куки, действительной для всего сайта независимо от способа запроса сайта, добавьте ваш URL в домен, начиная с точки, например: .your-domain.com

Путь обычно не нужен, так как метод устанавливает корневой путь.

Префикс нужен только в случае необходимости предотвращения коллизий имен с другими куками с одинаковым именем для вашего сервера.

Флаг secure нужен только в случае, если вы хотите сделать куки безопасной, установив его в значение true.

Значение SameSite управляет тем, как куки разделяются между доменами и поддоменами. Разрешенные значения: «None», «Lax», «Strict» или пустая строка ''. Если значение пустое, будет установлен атрибут SameSite по умолчанию.

Отдельные параметры

Если вы предпочитаете, вы можете установить куки, передав данные с помощью отдельных параметров:

$response->setCookie($name, $value, $expire, $domain, $path, $prefix, $secure, $httponly, $samesite);

deleteCookie($name = ''[, $domain = ''[, $path = '/'[, $prefix = '']]])

Параметры:	$name (mixed) – Имя куки или массив параметров $domain (string) – Домен куки $path (string) – Путь куки $prefix (string) – Префикс имени куки
Тип возвращаемого значения:	void

Удалить существующую куки, установив ее срок действия в 0.

Примечания

Требуется только имя.

Префикс нужен только в случае необходимости предотвращения коллизий имен с другими куками с одинаковым именем для вашего сервера.

Укажите префикс, если куки нужно удалить только для этого подмножества. Укажите домен, если куки нужно удалить только для этого домена. Укажите путь, если куки нужно удалить только для этого пути.

Если любой из необязательных параметров пуст, куки с тем же именем будет удалена для всех соответствующих случаев.

Пример:

$response->deleteCookie($name);

hasCookie($name = ''[, $value = null[, $prefix = '']])

Параметры:	$name (mixed) – Имя cookie или массив параметров $value (string) – значение cookie $prefix (string) – Префикс имени cookie
Тип возвращаемого значения:	bool

Проверяет, содержит ли ответ указанный cookie.

Примечания

Требуется только имя. Если указан префикс, он будет добавлен к имени cookie.

Если значение не указано, метод просто проверяет наличие cookie с указанным именем. Если значение указано, метод проверяет, существует ли cookie и соответствует ли он заданному значению.

Пример:

if ($response->hasCookie($name)) ...

getCookie($name = ''[, $prefix = ''])

Параметры:	$name (string) – Имя cookie $prefix (string) – Префикс имени cookie
Тип возвращаемого значения:	Cookie|Cookie[]|null

Возвращает указанный cookie, если он найден, или null. Если имя не указано, возвращает массив объектов Cookie.

Пример:

$cookie = $response->getCookie($name);

getCookies()

Тип возвращаемого значения:	Cookie[]

Возвращает все cookie, установленные в текущем экземпляре Response. Это любые cookie, которые вы специально установили только для текущего запроса.