Стиснення

OxPHP стискає HTTP-відповіді за допомогою Brotli, Zstandard або gzip — залежно від того, що приймає клієнт. Стиснення застосовується автоматично до фіксованого переліку типів вмісту (текст, JSON, XML, SVG, WebAssembly та кілька форматів шрифтів), тож обсяг переданих даних зменшується без жодних змін у коді вашого застосунку.

Як це працює

Заголовок Accept-Encoding клієнта зчитується один раз, ще до того, як запит потрапить у конвеєр маршрутизації, і зіставляється з кодуваннями, які пропонує сервер. Що відбувається далі, залежить від того, звідки беруться байти.

Кешований статичний файл, для якого вже є збережена стиснена копія, віддається безпосередньо з цієї копії. Під час запиту нічого не стискається, і жодна з наведених нижче перевірок не застосовується. Див. Кешовані статичні файли.

Будь-яка інша відповідь (вивід PHP, власна сторінка помилки, статичний файл, для якого ще немає збереженої копії) після формування проходить ті самі перевірки в такому порядку:

1. Часткові відповіді пропускаються. Відповідь 206 ніколи не кодується, бо зсуви в її Content-Range описують незакодоване представлення.
2. Перевірка типу вмісту. MIME-тип відповіді шукається в переліку типів, що стискаються.
3. Перевірка на наявне кодування. Відповідь, яка вже має заголовок Content-Encoding, залишається без змін.
4. Перевірка розміру. Стискаються лише тіла розміром від 256 байтів до 3 MiB (3 145 728 байтів) включно з обох боків. Якщо відповідь має заголовок Content-Length, використовується він; відповіді PHP зазвичай його не мають, тож для них вимірюється буферизоване тіло.
5. Стиснення. Узгоджене кодування застосовується з налаштованим рівнем. Якщо стиснений результат не менший за оригінал, натомість надсилається нестиснена відповідь.

Невеликі тіла стискаються безпосередньо; після певного порогу робота переходить у блокувальний потік, щоб не гальмувати асинхронне середовище виконання. Поріг становить 64 KiB і знижується до 4 KiB, щойно рівень стає достатньо високим, щоб крива витрат різко пішла вгору: понад якість 4 для Brotli, рівень 6 для gzip, рівень 9 для Zstandard. За стандартних значень Brotli вже перебуває в «крутій» половині, тож тіла Brotli понад 4 KiB стискаються поза асинхронним потоком.

flowchart TD
    AE["Accept-Encoding, read once per request"]
    W["Ranked by weight. A coding the server<br/>does not offer scores zero and drops out"]
    Q{"Is a stored copy<br/>being served?"}
    A["Tie broken br, then zstd, then gzip.<br/>Built once at br 11, zstd 19, gzip 9"]
    P["Tie broken zstd, then br, then gzip.<br/>Compressed now at the configured<br/>zstd 6, br 5, gzip 6"]
    H["Content-Encoding, recomputed Content-Length,<br/>Vary, weakened ETag, no Accept-Ranges"]
    AE --> W
    W --> Q
    Q -->|yes| A
    Q -->|no| P
    A --> H
    P --> H

Вибір кодування

Accept-Encoding ранжує кодування за вагою (RFC 9110 §12.5.3), і OxPHP читає його саме так:

• Назви кодувань порівнюються без урахування регістру, а невідомі кодування ігноруються.
• br;q=0 відмовляється від Brotli. Це не те саме, що просто не вказати кодування: * може підхопити пропущене кодування, але не те, від якого явно відмовилися.
• * охоплює будь-яке кодування, не назване в заголовку явно, з указаною для нього вагою.
• Вага, яку не вдається розібрати, залишає кодування з вагою за замовчуванням; некоректний параметр його не відкидає. Це важливо для q=0. Значення qvalue має щонайбільше три знаки після коми, тож q=0.000 відмовляється від кодування, тоді як q=0.0000 взагалі не є коректною вагою і читається як повне прийняття. Кодування, назване двічі, читається з першою вагою.
• Серед кодувань, які клієнт приймає і які пропонує сервер, перемагає те, якому клієнт надав найвищу вагу. Кодування, вимкнене в налаштуваннях, отримує нульову оцінку ще до ранжування, тож клієнт, чиє улюблене кодування сервер не пропонує, переходить до наступного вибору, а не до нестисненої відповіді.
• Заголовок, який нічого не приймає (порожній або *;q=0), дає незакодовану відповідь. OxPHP ніколи не відповідає 406 через кодування вмісту і ніколи не сприймає identity як токен.

Зазвичай ваги рівні, бо браузери надсилають усі підтримувані кодування без ваг. OxPHP розв’язує цю нічию залежно від того, що станеться зі стисненими байтами:

Перший рядок діє лише тоді, коли збережена копія вже існує. Звернення до її появи, а також кожен файл, завеликий для кешування, підпадають під другий рядок — тому статичний ресурс зазвичай спочатку віддається в Zstandard, а вже потім у Brotli.

Пріоритет лише розв’язує нічию. Клієнт, який надсилає br;q=0.2, gzip;q=0.9, отримує gzip на обох шляхах, і збережена копія, створена для нього, теж буде в gzip.

Клієнт, який не приймає жодного з трьох кодувань, отримує незакодовану відповідь. На практиці запасним варіантом є gzip: його приймає кожен HTTP-клієнт останніх двадцяти років, тоді як Zstandard потребує браузера, випущеного у 2024 році або пізніше.

Vary: Accept-Encoding

Оскільки результат залежить від заголовка запиту, кожна відповідь у межах вікна стиснення має Vary: Accept-Encoding — стиснена чи ні, статична чи динамічна. Представлення, яке сервер закодував би для якогось клієнта, залежить від цього заголовка, навіть якщо поточному клієнту віддаються незакодовані байти, а спільний кеш, якому сказали б інакше, передав би ці байти клієнту, що просив кодування.

За межами цього правила залишаються два випадки:

• Динамічна відповідь, яку сервер ніколи не тримає повністю (усе, що передається потоком у міру того, як PHP його генерує), не має Vary: на цьому шляху стиснення неможливе за жодного заголовка, тож відповідь справді не змінюється. Статичний файл, достатньо великий для потокової передачі, до цієї групи не належить і має цей заголовок, бо той самий файл читається повністю й стискається для клієнта, який узгодив кодування.
• Відповідь 304 не має ані Vary, ані Content-Encoding: вона оновлює представлення, яке клієнт уже має, а не описує нове.

Vary додається окремим рядком заголовка, а не об’єднується з тим, який застосунок уже надіслав, тож відповідь, що встановила Vary: Cookie, виходить із двома рядками Vary. Це допустимо, і OxPHP перед додаванням читає їх усі, щоб Accept-Encoding ніколи не дублювався, але проміжний вузол, який читає лише перший рядок, його пропустить.

Кешовані статичні файли

Статичний файл, що вміщується в кеш вмісту (1 MiB або менше) і придатний для стиснення (тип із переліку, щонайменше 256 байтів), стискається один раз, а не за кожного запиту.

1. 1
   Перший запит: промах кешу. Файл читається з диска, зберігається і стискається для цього запиту так само, як і все інше.
2. 2
   Наступний запит: запуск створення копії. Файл уже в кеші, і якщо для кодування, узгодженого цим запитом, ще немає збереженої копії, сервер доручає створити її у фоновому потоці. Запит, що запустив створення, обслуговується звичайним способом — стисненням під запит, — як і кожен запит, що надходить, поки копія створюється.
3. 3
   Копія готова. Подальші запити, що узгоджують те саме кодування, отримують відповідь зі збереженої копії.

Лічильника звернень немає: тригером є перше влучання в кеш без збереженої копії для цього кодування, тож файл, який досі віддавався лише клієнтам gzip, отримує копію Brotli під час першого звернення клієнта з Brotli.

Збережені копії створюються з максимальним рівнем кожного кодування (Brotli 11, Zstandard 19, gzip 9) незалежно від налаштованих рівнів для запитів, які збережена копія ніколи не використовує. Окремого параметра для них немає: єдиний спосіб не допустити створення копії — повністю вимкнути кодування. Максимальна якість зазвичай дає на 8–12% менше байтів, ніж рівень Brotli для запитів.

Кожне кодування отримує власну збережену копію, що створюється на вимогу, тож файл, який віддається лише клієнтам gzip, ніколи не коштуватиме стиснення Brotli. Усі копії мають спільний валідатор кешованого файлу й відкидаються разом із кешованими байтами: коли запис витісняється, щоб не перевищити бюджет кешу в 64 MiB (у який зараховуються і збережені копії), або коли увімкнено STATIC_REVALIDATE і він помічає зміну файлу на диску. Цей параметр за замовчуванням вимкнений, тож у стандартному розгортанні збережена копія відкидається лише у двох випадках — через витіснення або перезапуск. Байти, що не стискаються, позначаються як такі й повторно не обробляються, а відповідь 304 не запускає створення копії й не віддає збережену копію.

Файли, завеликі для кешування

Між межею кешу та верхньою межею вікна стиснення (від 1 MiB до 3 MiB — діапазон, де живуть бандли фреймворків, source maps і модулі WebAssembly) файл читається повністю і стискається за кожного запиту, якщо клієнт узгодив кодування, а тип придатний для стиснення. Такий файл не кешується й ніколи не отримує збереженої копії, тож це найдорожче стиснення, яке сервер виконує на один запит.

Під час читання такий файл утримується в пам’яті, доки відповідь не буде записано, тож одночасно читається лише обмежена кількість таких файлів. Запит, що надходить понад цей ліміт, отримує файл потоком і без кодування, а не чекає на вільне місце. Тому за тривалого навантаження на великий ресурс одні клієнти отримують його стисненим, а інші — ні; обидві відповіді коректні для цієї URL-адреси, і Vary: Accept-Encoding є в них у будь-якому разі.

За межами цього випадку файл понад 1 MiB передається потоком із диска без змін: тип, що не стискається, клієнт, який не приймає жодного кодування, або будь-що понад 3 MiB.

Скільки коштує статичний файл залежно від розміру:

flowchart TD
    F["Static file"]
    C1{"256 B or larger?"}
    C2{"1 MiB or smaller?"}
    C3{"3 MiB or smaller?"}
    N1["Sent as-is, and cached.<br/>The framing would cost more than it saves"]
    N2["Cached, and a stored copy is built once<br/>in the background on the first cache hit"]
    N3["Read whole and compressed on every request.<br/>Too large to cache, so no copy is kept"]
    N4["Streamed from disk, never compressed.<br/>Past the compression window"]
    F --> C1
    C1 -->|no| N1
    C1 -->|yes| C2
    C2 -->|yes| N2
    C2 -->|no| C3
    C3 -->|yes| N3
    C3 -->|no| N4

Ця схема передбачає тип, придатний для стиснення, і клієнта, який узгодив кодування. Приберіть будь-яку з цих умов — і файл кешується до 1 MiB, понад цю межу передається потоком, діапазони підтримуються всюди, і ніде нічого не кодується.

Налаштування

Кодування пропонується, якщо воно є в COMPRESSION_ENCODINGS і його рівень не дорівнює 0; порушення будь-якої з цих умов вимикає його. Вимкнене кодування зникає з усієї функції: воно ніколи не узгоджується, ніколи не стискається на шляху запиту й ніколи не створюється як збережена копія.

Чому саме такі значення за замовчуванням

• Brotli 5, а не 4. Точка перелому якості Brotli (зміна хешера) лежить між ними. На рівні 4 він давав більше байтів, ніж gzip на власному стандартному рівні, для JSON понад 4 KB і для реальних мініфікованих ресурсів, та ще й витрачав на це більше CPU, тож жодних причин віддавати йому перевагу над gzip не залишалося. На рівні 5 він дає менший результат з-поміж двох на кожному виміряному тілі приблизно за подвійну ціну gzip у CPU.
• Gzip 6. Власне значення за замовчуванням zlib, близьке до точки спадної віддачі. Рівень 9 коштує приблизно вдвічі більше заради одного-двох відсотків.
• Zstandard 6, а не його власне значення за замовчуванням 3. На тілах понад кілька кілобайтів рівень 6 витрачає менше часу, ніж якість Brotli, з якою попередні випуски стискали все, і водночас дає менше байтів, тож порівняно з тим, що надсилали ті випуски, нічого не погіршується.

Рівні від 9 до 11 краще підходять для стиснення офлайн або під час збирання, ніж для роботи на кожен запит; кешовані статичні файли все одно їх використовують, бо ця ціна сплачується один раз.

Типи вмісту, що стискаються

Перелік закритий: правил за префіксом чи шаблоном немає, тож тип, якого в ньому немає, ніколи не стискається, навіть якщо стискався б добре. У межах переліку порівняння поблажливе. Параметри й пробіли навколо відкидаються, а сам тип порівнюється без урахування регістру, тож і text/html; charset=utf-8, і Application/JSON збігаються.

Текстові типи:

• text/html
• text/css
• text/plain
• text/xml
• text/javascript

Типи application:

• application/javascript
• application/json
• application/xml
• application/xhtml+xml
• application/rss+xml
• application/atom+xml
• application/manifest+json
• application/ld+json
• application/wasm

Інші типи:

• image/svg+xml
• font/ttf
• font/otf
• application/x-font-ttf
• application/x-font-opentype
• application/vnd.ms-fontobject

Що не стискається

Відповіді надсилаються без стиснення, якщо виконується будь-яка з таких умов:

• Клієнт не приймає жодного з br, zstd і gzip у заголовку Accept-Encoding, приймає їх лише з нульовою вагою (br;q=0, zstd;q=0, gzip;q=0) або взагалі не надсилає такого заголовка
• Кожне кодування, яке приймає клієнт, вимкнене через COMPRESSION_ENCODINGS або рівнем 0
• Відповідь уже має заголовок Content-Encoding (наприклад, попередньо стиснений вміст, створений застосунком)
• Тіло відповіді менше за 256 байтів або більше за 3 MiB
• Відповідь має статус 206 Partial Content: зсуви діапазонів описують незакодоване представлення, тож часткове тіло ніколи не кодується
• Типу вмісту немає в переліку вище. image/png, image/jpeg, font/woff2 і application/zip виключено, бо ці формати вже мають власне стиснення, а text/event-stream — бо потік подій має доходити до клієнта подія за подією. text/csv, application/pdf, image/x-icon і відповідь без Content-Type узагалі теж виключено, бо їх немає в переліку
• Сервер не тримає тіло повністю: PHP-скрипти, що використовують oxphp_stream_flush(), Server-Sent Events і статичні файли, які читаються з диска в міру надсилання. OxPHP стискає відповідь цілком. Brotli, Zstandard і gzip уміють кодувати поступово, тож це обмеження сервера, а не кодувань
• Відповідь надійшла від плагіна, який відповів ще до запуску конвеєра, — наприклад, 429 через обмеження частоти запитів, що повертається до етапу стиснення
• Відповідь надійшла від внутрішнього слухача (INTERNAL_ADDR), який віддає /metrics і ендпоінти перевірки стану без кодування незалежно від того, що приймає збирач метрик

Заголовки відповіді

Відповідь, яку кодує сервер, змінюється так — незалежно від того, чи її стиснено для цього запиту, чи віддано зі збереженої копії:

Усі кодування одного статичного файлу мають цей спільний слабкий тег, обчислений із незакодованого розміру й часу модифікації. Варіанти розрізняє саме Vary; тег лише визначає свіжість, тож кеш, що повторно перевіряє один варіант, не може повідомити серверу, який саме з них він зберігає.

Спостережуваність

Два лічильники на ендпоінті метрик показують, що насправді зробило стиснення:

• oxphp_compressed_responses_total: відповіді, надіслані з кодуванням вмісту
• oxphp_compression_bytes_saved_total: незакодований розмір мінус стиснений розмір, у сумі

Обидва враховують як віддачу зі збережених копій, так і стиснення під запит, тож співвідношення з oxphp_requests_total відповідає на питання «чи охоплює стиснення мій трафік» надійніше, ніж окремий curl -I.

Усунення несправностей

Приклад для Docker

Промпти для вашого агента

Ці промпти розраховані на агента з підключеним MCP-сервером документації OxPHP — потрібні сторінки він прочитає сам.

Див. також

• Статичні файли — віддача файлів, визначення MIME та HTTP-кешування
• Метрики — лічильники стиснення та решта ендпоінта
• Довідник із налаштувань — повний перелік змінних середовища