Nette Documentation Preview

syntax 
Конфігурація HTTP
*****************

.[perex]
Огляд параметрів конфігурації для Nette HTTP.

Якщо ви не використовуєте весь фреймворк, а лише цю бібліотеку, прочитайте, [як завантажити конфігурацію|bootstrap:].


HTTP-заголовки
==============

```neon
http:
	# заголовки, які надсилаються з кожним запитом
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# впливає на заголовок X-Frame-Options
	frames: ...      # (string|bool) за замовчуванням 'SAMEORIGIN'
```

Фреймворк з міркувань безпеки надсилає заголовок `X-Frame-Options: SAMEORIGIN`, який вказує, що сторінку можна відображати всередині іншої сторінки (в елементі `<iframe>`) лише якщо вона знаходиться на тому ж домені. Це може бути небажаним у деяких ситуаціях (наприклад, якщо ви розробляєте програму для Facebook), тому поведінку можна змінити, встановивши `frames: http://allowed-host.com` або `frames: true`.


Content Security Policy
-----------------------

Легко можна створювати заголовки `Content-Security-Policy` (далі CSP), їх опис ви знайдете в [опису CSP |https://content-security-policy.com]. Директиви CSP (наприклад, `script-src`) можуть бути записані або як рядки відповідно до специфікації, або як масив значень для кращої читабельності. Тоді не потрібно навколо ключових слів, як-от `'self'`, ставити лапки. Nette також автоматично генерує значення `nonce`, тому в заголовку буде, наприклад, `'nonce-y4PopTLM=='`.

```neon
http:
	# Content Security Policy
	csp:
		# рядок у форматі відповідно до специфікації CSP
		default-src: "'self' https://example.com"

		# масив значень
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool у випадку перемикачів
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

У шаблонах використовуйте `<script n:nonce>...</script>`, і значення nonce доповниться автоматично. Робити безпечні сайти в Nette справді легко.

Подібно можна створити й заголовки `Content-Security-Policy-Report-Only` (які можна використовувати одночасно з CSP) та [Feature Policy|https://developers.google.com/web/updates/2018/06/feature-policy]:

```neon
http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com
```


HTTP cookie
-----------

Можна змінити стандартні значення деяких параметрів методу [Nette\Http\Response::setCookie() |response#setCookie] та сесії.

```neon
http:
	# область дії cookie за шляхом
	cookiePath: ...          # (string) за замовчуванням '/'

	# домени, які приймають cookie
	cookieDomain: 'example.com'  # (string|domain) за замовчуванням не встановлено

	# надсилати cookie лише через HTTPS?
	cookieSecure: ...        # (bool|auto) за замовчуванням auto

	# вимкне надсилання cookie, яку Nette використовує як захист від CSRF
	disableNetteCookie: ...  # (bool) за замовчуванням false
```

Атрибут `cookieDomain` визначає, які домени можуть приймати cookie. Якщо він не вказаний, cookie приймає той самий (під)домен, що й встановив його, *але не* його піддомени. Якщо `cookieDomain` вказаний, піддомени також включаються. Тому вказання `cookieDomain` є менш обмежувальним, ніж його відсутність.

Наприклад, при `cookieDomain: nette.org` cookies доступні також на всіх піддоменах, таких як `doc.nette.org`. Того ж можна досягти також за допомогою спеціального значення `domain`, тобто `cookieDomain: domain`.

Стандартне значення `auto` для атрибута `cookieSecure` означає, що якщо сайт працює на HTTPS, cookies будуть надсилатися з прапором `Secure` і, отже, будуть доступні лише через HTTPS.


HTTP-проксі
-----------

Якщо сайт працює за HTTP-проксі, вкажіть його IP-адресу, щоб правильно працювало визначення з'єднання через HTTPS, а також IP-адреси клієнта. Тобто, щоб функції [Nette\Http\Request::getRemoteAddress() |request#getRemoteAddress] та [isSecured() |request#isSecured] повертали правильні значення, а в шаблонах генерувалися посилання з протоколом `https:`.

```neon
http:
	# IP-адреса, діапазон (напр. 127.0.0.1/8) або масив цих значень
	proxy: 127.0.0.1       # (string|string[]) за замовчуванням не встановлено
```


Сесія
=====

Базові налаштування [сесій |sessions]:

```neon
session:
	# показувати панель сесії в Tracy Bar?
	debugger: ...        # (bool) за замовчуванням false

	# час неактивності, після якого сесія закінчиться
	expiration: 14 days  # (string) за замовчуванням '3 hours'

	# коли має запускатися сесія?
	autoStart: ...       # (smart|always|never) за замовчуванням 'smart'

	# обробник, сервіс, що реалізує інтерфейс SessionHandlerInterface
	handler: @handlerService
```

Опція `autoStart` керує тим, коли має запускатися сесія. Значення `always` означає, що сесія запуститься завжди при запуску програми. Значення `smart` означає, що сесія запуститься при старті програми лише тоді, коли вона вже існує, або в момент, коли ми хочемо з неї читати або в неї записувати. І нарешті, значення `never` забороняє автоматичний запуск сесії.

Далі можна налаштовувати всі PHP [директиви сесії |https://www.php.net/manual/en/session.configuration.php] (у форматі camelCase) та також [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Приклад:

```neon
session:
	# 'session.name' запишемо як 'name'
	name: MYID

	# 'session.save_path' запишемо як 'savePath'
	savePath: "%tempDir%/sessions"
```


Session cookie
--------------

Session cookie надсилається з тими ж параметрами, що й [інші cookie |#HTTP cookie], але ці ви можете для неї змінити:

```neon
session:
	# домени, які приймають cookie
	cookieDomain: 'example.com'   # (string|domain)

	# обмеження при доступі з іншого домену
	cookieSamesite: None          # (Strict|Lax|None) за замовчуванням Lax
```

Атрибут `cookieSamesite` впливає на те, чи буде cookie надіслано при [доступі з іншого домену |nette:glossary#SameSite cookie], що забезпечує певний захист від атак [Cross-Site Request Forgery |nette:glossary#Cross-Site Request Forgery CSRF] (CSRF).


Сервіси DI
==========

Ці сервіси додаються до DI-контейнера:

| Назва           | Тип                        | Опис
|-----------------------------------------------------
| `http.request`	  | [api:Nette\Http\Request]   | [HTTP-запит| request]
| `http.response`	  | [api:Nette\Http\Response]  | [HTTP-відповідь| response]
| `session.session`   | [api:Nette\Http\Session]   | [керування сесіями| sessions]

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

Огляд параметрів конфігурації для Nette HTTP.

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

HTTP-заголовки

http:
	# заголовки, які надсилаються з кожним запитом
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# впливає на заголовок X-Frame-Options
	frames: ...      # (string|bool) за замовчуванням 'SAMEORIGIN'

Фреймворк з міркувань безпеки надсилає заголовок X-Frame-Options: SAMEORIGIN, який вказує, що сторінку можна відображати всередині іншої сторінки (в елементі <iframe>) лише якщо вона знаходиться на тому ж домені. Це може бути небажаним у деяких ситуаціях (наприклад, якщо ви розробляєте програму для Facebook), тому поведінку можна змінити, встановивши frames: http://allowed-host.com або frames: true.

Content Security Policy

Легко можна створювати заголовки Content-Security-Policy (далі CSP), їх опис ви знайдете в опису CSP. Директиви CSP (наприклад, script-src) можуть бути записані або як рядки відповідно до специфікації, або як масив значень для кращої читабельності. Тоді не потрібно навколо ключових слів, як-от 'self', ставити лапки. Nette також автоматично генерує значення nonce, тому в заголовку буде, наприклад, 'nonce-y4PopTLM=='.

http:
	# Content Security Policy
	csp:
		# рядок у форматі відповідно до специфікації CSP
		default-src: "'self' https://example.com"

		# масив значень
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool у випадку перемикачів
		upgrade-insecure-requests: true
		block-all-mixed-content: false

У шаблонах використовуйте <script n:nonce>...</script>, і значення nonce доповниться автоматично. Робити безпечні сайти в Nette справді легко.

Подібно можна створити й заголовки Content-Security-Policy-Report-Only (які можна використовувати одночасно з CSP) та Feature Policy:

http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com

Можна змінити стандартні значення деяких параметрів методу Nette\Http\Response::setCookie() та сесії.

http:
	# область дії cookie за шляхом
	cookiePath: ...          # (string) за замовчуванням '/'

	# домени, які приймають cookie
	cookieDomain: 'example.com'  # (string|domain) за замовчуванням не встановлено

	# надсилати cookie лише через HTTPS?
	cookieSecure: ...        # (bool|auto) за замовчуванням auto

	# вимкне надсилання cookie, яку Nette використовує як захист від CSRF
	disableNetteCookie: ...  # (bool) за замовчуванням false

Атрибут cookieDomain визначає, які домени можуть приймати cookie. Якщо він не вказаний, cookie приймає той самий (під)домен, що й встановив його, але не його піддомени. Якщо cookieDomain вказаний, піддомени також включаються. Тому вказання cookieDomain є менш обмежувальним, ніж його відсутність.

Наприклад, при cookieDomain: nette.org cookies доступні також на всіх піддоменах, таких як doc.nette.org. Того ж можна досягти також за допомогою спеціального значення domain, тобто cookieDomain: domain.

Стандартне значення auto для атрибута cookieSecure означає, що якщо сайт працює на HTTPS, cookies будуть надсилатися з прапором Secure і, отже, будуть доступні лише через HTTPS.

HTTP-проксі

Якщо сайт працює за HTTP-проксі, вкажіть його IP-адресу, щоб правильно працювало визначення з'єднання через HTTPS, а також IP-адреси клієнта. Тобто, щоб функції Nette\Http\Request::getRemoteAddress() та isSecured() повертали правильні значення, а в шаблонах генерувалися посилання з протоколом https:.

http:
	# IP-адреса, діапазон (напр. 127.0.0.1/8) або масив цих значень
	proxy: 127.0.0.1       # (string|string[]) за замовчуванням не встановлено

Сесія

Базові налаштування сесій:

session:
	# показувати панель сесії в Tracy Bar?
	debugger: ...        # (bool) за замовчуванням false

	# час неактивності, після якого сесія закінчиться
	expiration: 14 days  # (string) за замовчуванням '3 hours'

	# коли має запускатися сесія?
	autoStart: ...       # (smart|always|never) за замовчуванням 'smart'

	# обробник, сервіс, що реалізує інтерфейс SessionHandlerInterface
	handler: @handlerService

Опція autoStart керує тим, коли має запускатися сесія. Значення always означає, що сесія запуститься завжди при запуску програми. Значення smart означає, що сесія запуститься при старті програми лише тоді, коли вона вже існує, або в момент, коли ми хочемо з неї читати або в неї записувати. І нарешті, значення never забороняє автоматичний запуск сесії.

Далі можна налаштовувати всі PHP директиви сесії (у форматі camelCase) та також readAndClose. Приклад:

session:
	# 'session.name' запишемо як 'name'
	name: MYID

	# 'session.save_path' запишемо як 'savePath'
	savePath: "%tempDir%/sessions"

Session cookie надсилається з тими ж параметрами, що й інші cookie, але ці ви можете для неї змінити:

session:
	# домени, які приймають cookie
	cookieDomain: 'example.com'   # (string|domain)

	# обмеження при доступі з іншого домену
	cookieSamesite: None          # (Strict|Lax|None) за замовчуванням Lax

Атрибут cookieSamesite впливає на те, чи буде cookie надіслано при доступі з іншого домену, що забезпечує певний захист від атак Cross-Site Request Forgery (CSRF).

Сервіси DI

Ці сервіси додаються до DI-контейнера:

Назва Тип Опис
http.request Nette\Http\Request HTTP-запит
http.response Nette\Http\Response HTTP-відповідь
session.session Nette\Http\Session керування сесіями