# Ръководство за потребителя на Symelo Image Optimizations

За Symelo Image Optimizations версия 1.0.1.

Това ръководство обяснява как да настроите Symelo Image Optimizations, какво прави всяка опция и как сами да отстранявате проблеми. Последната част, „За разработчици“, обхваща константите в wp-config.php, куките (hooks), командите на WP-CLI и REST API.

Нуждаете се от помощ? Пишете на office@symelo.com или посетете [symelo.com](https://symelo.com/).

## Съдържание

1. [Какво прави](#какво-прави)
2. [Основни понятия](#основни-понятия)
3. [Изисквания](#изисквания)
4. [Инсталиране и първоначална настройка](#инсталиране-и-първоначална-настройка)
5. [Къде да намерите всичко](#къде-да-намерите-всичко)
6. [Раздел Overview](#раздел-overview)
7. [Раздел Compression](#раздел-compression)
8. [Раздел Delivery](#раздел-delivery)
9. [Раздел Other Folders](#раздел-other-folders)
10. [Раздел Engines](#раздел-engines)
11. [Раздел Advanced](#раздел-advanced)
12. [Раздел Support](#раздел-support)
13. [В медийната библиотека](#в-медийната-библиотека)
14. [Как се обработва всеки тип файл](#как-се-обработва-всеки-тип-файл)
15. [Практически рецепти](#практически-рецепти)
16. [Отстраняване на проблеми](#отстраняване-на-проблеми)
17. [Поверителност и сигурност](#поверителност-и-сигурност)
18. [Отмяна на промените и деинсталиране](#отмяна-и-деинсталиране)
19. [За разработчици](#за-разработчици)

---

## Какво прави

Symelo Image Optimizations прави изображенията ви по-малки, без да променя начина, по който изглежда сайтът ви. Всичко се случва на собствения ви сървър; изображенията никога не се качват към външна услуга.

- **Компресира** JPEG и PNG файловете при качването им, а с едно щракване — и в цялата ви съществуваща медийна библиотека.
- **Създава WebP и AVIF копия** на всяко изображение и ги сервира на браузърите, които ги поддържат.
- **Преоразмерява** прекалено големите качени изображения (например 6000-пикселови снимки от фотоапарат) до зададени максимална ширина и височина.
- **Премахва личните метаданни**, като GPS местоположение и данни за фотоапарата.
- **Запазва оригиналите**, така че можете да възстановите едно изображение или цялата библиотека.
- **Зарежда отложено** (lazy loading) изображенията и вграденото съдържание, така че браузърът ги изтегля едва когато всеки момент ще се покажат при превъртане.
- Подобрява **адаптивните изображения** (responsive images), така че телефоните да не изтеглят файлове с размери за настолен компютър.
- Оптимизира изображенията и в **папките на темите и плъгините**.
- Работи с графичните библиотеки, които има PHP на сървъра ви (Imagick и GD, които използва и WordPress), и показва точно какво се поддържа.

Цялата работа се извършва във фонов режим. Можете да затворите страницата, докато тя тече.

## Основни понятия

| Понятие | Значение |
|---|---|
| **Без загуби** (lossless) | Компресия, при която всеки пиксел остава абсолютно същият. Спестяването идва от по-ефективното пакетиране и премахването на метаданните. |
| **Със загуби** (lossy) | Компресия, която премахва детайли, които окото почти не забелязва, в замяна на много по-малки файлове. Число за *качество* (например 82 от 100) определя доколко. |
| **WebP** | Модерен формат за изображения, обикновено с 25–35% по-малък от JPEG. Поддържа се от всички съвременни браузъри. |
| **AVIF** | По-нов формат, често наполовина по-малък от JPEG. Създава се по-бавно. Браузърите без поддръжка на AVIF получават WebP или оригинала. |
| **Копие** | Версията във WebP или AVIF, която плъгинът записва до изображението, например `photo.jpg.webp` и `photo.jpg.avif`. Името на оригиналния ви файл и адресът му (URL) не се променят. |
| **srcset / sizes** | HTML атрибути, които изброяват наличните размери на изображението (`srcset`) и с каква ширина се показва то (`sizes`), така че браузърът да избере най-малкия файл, който изглежда достатъчно рязко. |
| **Отложено зареждане** (lazy loading) | Изображението се зарежда едва когато посетителят превърти близо до него. |
| **Механизъм** (engine) | Софтуерът, който извършва работата: графичните библиотеки на PHP, Imagick и GD. |
| **CDN** | Мрежа за доставка на съдържание (например Cloudflare), която кешира файловете на сайта ви на сървъри по целия свят. |

## Изисквания

- WordPress 6.4 или по-нова версия.
- PHP 7.4 или по-нова версия. При по-стара версия на PHP плъгинът остава неактивен и показва известие.
- Поне една графична библиотека на PHP: **Imagick** или **GD**. Ако няма нито една от двете, се показва известие: „this server has no image library (Imagick or GD), so images can't be optimized.“
- Права за запис на уеб сървъра в папката с качените файлове (uploads), както и във всички папки на теми или плъгини, които изберете да оптимизирате.
- По избор: за WebP/AVIF чрез **Server rules** — Apache или LiteSpeed с mod_rewrite (и mod_headers) или достъп до конфигурацията на Nginx. Начинът на доставяне по подразбиране, **<picture> tags**, работи на всеки сървър.

Кои формати може да създава сървърът ви, зависи от това как са компилирани PHP и неговите библиотеки. Разделите **Engines** и **Overview** показват точно какво е налично, а опциите, които не са възможни, са неактивни и е посочена причината.

Компресирането на PDF не е възможно с Imagick и GD, затова за **PDF compression** се показва **No**, а **Optimize PDF files** е неактивна.

Само администраторите могат да отварят настройките (правото `manage_options`). В медийната библиотека всеки, който може да редактира дадено изображение, може и да го оптимизира или възстанови.

Multisite се поддържа. Всеки сайт има свои собствени настройки и записи.

---

## Инсталиране и първоначална настройка

### Какво се случва при активиране

1. В wp-admin отидете в **Разширения → Добавяне на разширение → Качване на разширение**, изберете .zip файла, щракнете **Инсталиране**, а след това **Активиране**.
2. Плъгинът създава своята таблица в базата данни и планира ежедневна задача за поддръжка. Нищо не се изтегля и нито едно съществуващо изображение не се променя.
3. Оттук нататък **новите качени изображения се оптимизират автоматично** няколко секунди след качването им, с настройките по подразбиране: компресия **Balanced**, WebP и AVIF копия, преоразмеряване до най-много 2560 пиксела ширина, премахване на метаданните и запазване на оригиналите.
4. Съществуващите ви изображения остават непроменени, докато не стартирате масова оптимизация.

Екранът на плъгина се намира в **Медия → Image Optimizations**.

### Стъпка 1: Проверете какво може сървърът ви

1. Отидете в **Медия → Image Optimizations**. Отваря се разделът **Overview**.
2. Вижте картата **What this server can do**. За всяка задача е показано **Yes** заедно с механизма, който ще я изпълнява, или **No**:
   **JPEG compression**, **PNG compression**, **WebP copies**, **AVIF copies**, **PDF compression**, **Resizing**.
3. Ако за **WebP copies** или **AVIF copies** пише **No**, отворете раздела **Engines**, за да видите защо, и помолете хостинг доставчика си да включи поддръжката на WebP/AVIF в Imagick или GD (вижте [WebP или AVIF не са налични](#webp-или-avif-не-е-наличен)). За **PDF compression** пише **No**: Imagick и GD не могат да компресират PDF файлове.

### Стъпка 2: Прегледайте настройките за компресия

Настройките по подразбиране са подходящи за повечето сайтове. Ако искате да ги проверите, отворете раздела **Compression**. Най-важният избор е **Compression level**; препоръчва се **Balanced**. Вижте [Раздел Compression](#раздел-compression).

### Стъпка 3: Оптимизирайте съществуващите си изображения

1. В раздела **Overview** намерете **Bulk optimization**.
2. Щракнете **Optimize all images**.
3. Лентата за напредъка показва „Finding images…“, а след това „*X* of *Y* files“. Можете да затворите страницата; работата продължава във фонов режим.
4. Когато приключи, в картата пише „Last bulk run finished on …“, а в горната част на страницата се показва спестеното: „*N* media files processed. Visitors download *P*% less (*size*).“

На малък или споделен сървър първо задайте **Advanced → Background speed** на **Gentle**. Вижте [Използване на плъгина на малък сървър](#използване-на-плъгина-на-малък-сървър).

### Стъпка 4: Проверете дали се сервират WebP и AVIF

1. Отворете раздела **Delivery**. По подразбиране е избрано **<picture> tags (recommended)**, което работи навсякъде.
2. Под **Check delivery** щракнете **Test now**. Трябва да видите „<picture> delivery is on: pages offer WEBP, AVIF versions of optimized images to browsers that support them.“, последвано от това, което тестът е открил на началната ви страница, например „On the home page, 12 images have WebP/AVIF sources.“

---

## Къде да намерите всичко

**Медия → Image Optimizations** има осем раздела. Превключват се мигновено, без презареждане на страницата.

| Раздел | За какво служи |
|---|---|
| **Overview** | Спестено място, масова оптимизация, какво поддържа сървърът и последни проблеми. |
| **Compression** | Ниво на компресия, кои копия да се създават, преоразмеряване, метаданни, оригинали, изключени размери. |
| **Delivery** | Как се сервират WebP/AVIF, отложено зареждане и адаптивни изображения, с тест на доставянето. |
| **Other Folders** | Оптимизиране на изображенията в темата, плъгините и други папки в wp-content. |
| **Engines** | Кои механизми са открити и кой от тях изпълнява всяка задача. |
| **Advanced** | Състояние и скорост на фоновата обработка, поведение при деинсталиране и възстановяване на всичко. |
| **Guide** | Това ръководство, вградено в плъгина, със съдържание и поле за търсене („Find in this guide“). |
| **Support** | Връзки за помощ, отчет със системна информация и данни за контакт. |

В медийната библиотека също се появяват колона **Optimization** и бутони, вижте [В медийната библиотека](#в-медийната-библиотека). На екрана „Разширения“ под плъгина има връзка **Settings**.

---

## Раздел Overview

### Обобщение

Горната карта показва едно от следните:

- „*N* media files processed. Visitors download *P*% less (*size*).“ Спестеното отчита това, което посетителите действително изтеглят: най-малкия от файла и неговите WebP/AVIF копия.
- „Ready. New uploads are optimized automatically; existing images can be optimized in bulk below.“
- „This server has no engine that can compress images. See the Engines tab.“

Под нея се появяват предупреждения за остарели графични библиотеки на сървъра ви (вижте [Предупреждения за графичните библиотеки](#предупреждения-за-библиотеките-за-изображения)).

### Статистика

| Показател | Значение |
|---|---|
| **Smaller for visitors (with WebP/AVIF)** | С колко по-малко изтеглят посетителите в сравнение с оригиналните ви файлове. |
| **Disk space saved** | С колко по-малки са оптимизираните файлове от оригиналите (без да се броят копията). |
| **Files optimized** | Файлове, които са станали по-малки или са получили копия. Всеки размер на изображението се брои за отделен файл. |
| **WebP copies** / **AVIF copies** | Колко копия има. |

Тези показатели се отнасят за медийната библиотека. Изображенията от папки имат свои показатели в раздела **Other Folders**.

### Масова оптимизация

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

| Опция | Какво прави | По подразбиране |
|---|---|---|
| **Also redo images optimized with different settings** | Оптимизира отново изображенията, обработени с друго ниво на компресия, с други копия, с други ограничения за размера или с друга настройка за метаданните. Без нея се обработват само изображения, които не са оптимизирани (или при които е имало грешка, или са били възстановени, или са били заменени междувременно). | Изключено |
| **Include the selected folders (themes, plugins)** | Обработва и изображенията в папките, избрани в раздела **Other Folders**. Показва се само когато има избрани папки. | Включено |

Щракнете **Optimize all images**. Изпълнението минава през две фази:

1. **Finding images…**: медийната библиотека се сканира на малки порции. Ако сте включили точките на прекъсване (breakpoints) (вижте [Адаптивни изображения](#адаптивни-изображения)), липсващите размери за тях се създават в този момент.
2. **„*X* of *Y* files“**: файловете се оптимизират.

Докато тече, можете да използвате **Pause**, **Resume** или **Cancel**. Докато е на пауза, новите качени изображения продължават да се оптимизират. **Cancel** спира изпълнението: „Files already optimized stay optimized.“

Редът „Speed: Normal (change)“ показва текущата скорост на фоновата обработка и води към раздела **Advanced**.

Не е нужно да държите страницата отворена. Докато *е* отворена обаче, тя също помага на фоновата работа да напредва.

### Какво може този сървър

За всяка задача (**JPEG compression**, **PNG compression**, **WebP copies**, **AVIF copies**, **PDF compression**, **Resizing**): **Yes** с механизма, който ще се използва, или **No**. **Engines →** отваря раздела **Engines**.

### Последни проблеми

Последните осем файла, при които е възникнала грешка, с причината за нея. Щракнете името на файла, за да редактирате изображението. **Try failed files again** ги добавя отново в опашката. Вижте [Съобщения за файловете](#съобщения-за-файловете).

---

## Раздел Compression

След като промените нещо, щракнете **Save changes** в долната част. Новите настройки важат веднага за новите качени изображения. За да ги приложите към вече оптимизираните изображения, стартирайте масова оптимизация с **Also redo images optimized with different settings** или щракнете **Re-optimize** при отделни изображения.

### Ниво на компресия

| Ниво | Описание в плъгина | JPEG | PNG | WebP копие | AVIF копие |
|---|---|---|---|---|---|
| **Lossless** | Всеки пиксел остава същият, включително в WebP копията. По-малки файлове единствено благодарение на по-добрата компресия и премахнатите метаданни. Само PNG и GIF изображенията получават WebP копия (без загуби); AVIF копия не се създават. | Само без загуби | Без загуби | Без загуби, само за PNG и GIF изображения | Няма |
| **Balanced** (по подразбиране) | Препоръчително. Голямо спестяване без видима разлика. | Качество 82 | Без загуби | Качество 80 | Качество 62 |
| **Aggressive** | Най-малки файлове. Подходящо за повечето снимки; може леко да размие фините детайли. | Качество 72 | Намален брой цветове (със загуби) | Качество 70 | Качество 50 |
| **Custom** | Изберете качеството за всеки формат поотделно. | Плъзгач 30–100 (по подразбиране 82) | По ваш избор | Плъзгач 30–100 (по подразбиране 80) | Плъзгач 20–100 (по подразбиране 62) |

При **Custom** се появяват плъзгачи за **JPEG**, **WebP** и **AVIF**, както и опцията **Reduce PNG colours (lossy, much smaller)**. Тази опция за PNG е неактивна, когато на сървъра няма механизъм, който може да компресира PNG файлове.

Добре е да знаете:

- **Lossless** запазва всеки пиксел непроменен във всичко, което получават посетителите, включително в копията. PNG и GIF изображенията получават WebP копие без загуби, когато то е по-малко (създадено с Imagick или с GD на PHP 8.1 и по-нова версия). JPEG снимките не получават WebP копие, защото WebP без загуби на снимка на практика винаги е по-голям от JPEG файла, а AVIF копие не получава нито едно изображение. За WebP и AVIF копия на снимки изберете **Balanced**.
- Преоразмеряването (вижте [Преоразмеряване на големи качени изображения](#преоразмеряване-на-големи-качени-изображения)) променя пикселите на прекалено големите качени изображения при всяко ниво; изключете го, ако дори те трябва да останат непокътнати.
- JPEG файл, който вече е компресиран с (приблизително) избраното качество или с по-ниско, никога не се компресира повторно със загуби; той получава само оптимизация без загуби.
- Плъгинът винаги започва от запазения оригинал, така че повторната оптимизация никога не компресира вече компресирано изображение втори път.
- Файлът се заменя само когато резултатът е осезаемо по-малък (с поне 1 KB или 1%). В противен случай се отбелязва като **Already optimal**.

### Какво да се прави

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Optimize new uploads automatically** | „Изпълнява се във фонов режим няколко секунди след всяко качване.“ Важи и когато WordPress генерира наново или редактира файловете на изображение. | Включено |
| **Create WebP copies** | Записва WebP копие до всяко изображение, когато то е по-малко от оптимизирания файл. При **Lossless** копие (без загуби) получават само PNG и GIF изображенията. | Включено |
| **Create AVIF copies** | Записва AVIF копие до всяко изображение, когато то е по-малко както от оптимизирания файл, така и от WebP копието. Не се създава при **Lossless**. | Включено |
| **Remove metadata (EXIF, GPS location, camera details)** | Премахва EXIF, XMP, IPTC и коментарите. „Цветовите профили и ориентацията на снимката се запазват.“ | Включено |
| **Optimize PDF files** | „С механизма за компресиране на PDF от раздела Engines. Подписаните PDF файлове никога не се променят.“ Imagick и GD не могат да компресират PDF файлове, затова опцията е неактивна: „Not available: this server has no engine that can compress PDFs.“ | Включено (неактивна) |

**Create WebP copies**, **Create AVIF copies** и **Optimize PDF files** са неактивни, когато сървърът не може да ги изпълни, и до тях има обяснение, например „Not available: no engine on this server can write AVIF. Ask your host for PHP 8.1+ with AVIF support in GD, or Imagick with AVIF.“

### Преоразмеряване на големи качени изображения

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Scale down images larger than:** | Включва или изключва преоразмеряването. Изисква Imagick или GD. | Включено |
| **Max width** | От 320 до 10000 px. | 2560 px |
| **Max height** | 0 за липса на ограничение, иначе от 320 до 10000 px. | 0 (без ограничение) |

„Смалява се само основният качен файл; WordPress създава по-малките размери от него.“ Преоразмеряването се прилага за JPEG, PNG и WebP файлове (но не и за анимирани изображения). Изображението запазва пропорциите си. Плъгинът също така следи собственото смаляване на „големи изображения“ в WordPress никога да не намалява качените файлове под зададения от вас максимум.

### Оригинали

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Keep the originals so changes can be undone** | Съхранява всеки оригинал в `uploads/symelo-images/backups`, преди да го промени. „Без тях ‚Restore original‘ само премахва WebP и AVIF копията.“ | Включено |
| **Also optimize the full-size original WordPress keeps of scaled photos** | Когато смалява голяма снимка, WordPress запазва и непроменения качен файл (например `photo.jpg` до `photo-scaled.jpg`). „Този файл не се показва на сайта, но заема място.“ | Изключено |

Когато оригиналът в пълен размер не се оптимизира, метаданните му (например GPS местоположението) все пак се премахват, ако **Remove metadata** е включена, защото файлът е публично достъпен. Пикселите остават същите. Когато **Keep the originals** е включена, преди това се прави резервно копие на файла, както на всеки друг файл, така че при възстановяване на изображението се връщат и метаданните му.

### Изключване на размери на изображенията

„Отметнатите размери остават точно такива, каквито ги е създал WordPress: не се компресират и не получават WebP или AVIF копия. Оставете всички неотметнати, за да се оптимизира всеки размер.“

Всеки размер на изображение, регистриран от WordPress, темата ви и плъгините, е изброен заедно с размерите си (∞ означава без ограничение). Броячът показва „Every size is optimized.“ или „Sizes excluded: *N*“. По подразбиране нищо не е изключено.

Изключването на размер засяга само изображенията, оптимизирани след това, както пише и в картата: „Изключването на размер не променя вече оптимизираните изображения. За да върнете този размер такъв, какъвто го е създал WordPress, възстановете оригиналите на изображенията и след това ги оптимизирайте отново.“ Само **Re-optimize** не е достатъчно, защото не докосва изключените размери.

---

## Раздел Delivery

След като промените нещо в този раздел, щракнете **Save changes**.

### Сервиране на WebP и AVIF

| Опция | Как работи | Кога да я използвате |
|---|---|---|
| **&lt;picture&gt; tags (recommended)** (по подразбиране) | „Работи на всеки сървър и с всеки кеш или CDN. Всяко изображение получава AVIF и WebP източници, а браузърите избират най-добрия, който поддържат. Обхванати са само изображенията на собствения адрес на този сайт: изображенията, зареждани от друг адрес (например от CDN, който пренаписва адресите на изображенията), остават непроменени.“ Плъгинът пренаписва HTML кода на страницата: всеки `<img>`, който има копия, се обвива в елемент `<picture>` с AVIF и WebP източници. Малко CSS правило не позволява на обвивката да влияе на оформлението, така че изображенията изглеждат и се държат както преди. | Почти винаги. |
| **Server rules** | „HTML кодът остава непроменен: сървърът изпраща WebP/AVIF копието на оригиналния адрес (URL).“ Правилата се записват в `wp-content/.htaccess` за Apache или LiteSpeed; за Nginx е нужен фрагмент в неговата конфигурация. „Не е подходящо за сайтове зад Cloudflare или повечето други CDN: те кешират една версия на адрес за всички.“ | Когато не можете или не искате да променяте HTML кода и пред сайта няма CDN. |
| **Don't serve them** | „Само създава копията (например когато CDN сам конвертира изображенията).“ | Когато нещо друго сервира модерните формати. |

**&lt;picture&gt; tags в подробности:**

- Работи върху цялата страница, така че обхваща изображенията на темата и плъгините, а не само тези в публикациите ви.
- Обвиват се само изображенията, чийто адрес е на собствения ви сайт (в uploads или wp-content) и които имат копие на диска. Изображенията, зареждани от друг адрес, например през CDN или услуга за изображения, която пренаписва адресите им към свой домейн, никога не се обвиват: плъгинът не може да определи на кой файл отговарят. **Test now** изброява такива изображения, ако ги открие на началната ви страница.
- Предлагат се само форматите, отметнати в раздела **Compression**. Премахването на отметката от **Create AVIF copies** веднага спира предлагането на AVIF.
- На сайт с HTTPS WebP/AVIF източниците винаги използват `https://`, дори когато тема или по-стари публикации все още свързват изображение с `http://`. Браузърите блокират източниците с `http://` на защитени страници и не биха показали изображение изобщо. Самият `<img>` остава непроменен.
- Изображенията, които използват друг скрипт за отложено зареждане (атрибути `data-src` или `data-lazy-src`), не се обвиват.
- За да изключите изображение, задайте му класа `no-picture` (или `skip-picture`, `symelo-no-picture`) или атрибута `data-skip-picture`.
- RSS емисиите, REST API, AJAX заявките и отговорите, които не са HTML, никога не се променят.

**Server rules в подробности:**

- Когато превключите на **Server rules** и запазите, плъгинът записва правилата и веднага ги тества (вижте [Проверка на доставянето](#проверка-на-доставянето)).
- Правилата се поставят между `# BEGIN Symelo Image Optimizations` и `# END Symelo Image Optimizations` в `wp-content/.htaccess`. Те отговарят на заявка за `photo.jpg` с `photo.jpg.avif` или `photo.jpg.webp`, когато браузърът приема съответния формат и копието съществува, и добавят заглавката `Vary: Accept`.
- Правилата сервират само форматите, отметнати в раздела **Compression**. Когато поставите или премахнете отметката от **Create WebP copies** или **Create AVIF copies** и запазите, правилата се пренаписват веднага, така че премахването на отметката от AVIF незабавно спира сервирането на AVIF. При Nginx копирайте обновения фрагмент (вижте [Конфигурация за Nginx](#конфигурация-за-nginx)).
- Ако правилата изчезнат (например след повторно разгръщане на сайта), плъгинът ги връща следващия път, когато администратор отвори wp-admin, както и при ежедневната поддръжка.
- Превключването на друга опция или деактивирането на плъгина премахва правилата.
- Ако файлът не може да бъде записан: „wp-content/.htaccess can't be written. Add the rules manually or ask your host.“

Ако режимът е зададен в wp-config.php, опциите са неактивни: „Set by SYMELO_IMAGES_DELIVERY in wp-config.php.“

### Отложено зареждане

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Load images only when they are about to scroll into view** | „Използва вграденото в браузъра отложено зареждане: без скриптове и без разместване на оформлението.“ Изключването ѝ изключва и собственото отложено зареждане на WordPress. | Включено |
| **Load the first … images right away** | От 0 до 20. „Изображенията в горната част на страницата (лого, основен банер) трябва да се зареждат веднага, за да се появи страницата бързо.“ | 3 |
| **Also lazy-load theme and plugin images and embeds** | „WordPress обработва само изображенията в съдържанието.“ Когато тази опция е включена, плъгинът добавя отложено зареждане към всяко изображение и iframe (видеа, карти) на страницата. | Включено |

Подробности за отложеното зареждане в цялата страница:

- Първите изображения на страницата се зареждат веднага, дори ако тема или плъгин ги е маркирал за отложено зареждане, така че основното ви изображение не се забавя.
- Малките икони (64×64 пиксела или по-малки, с размер, зададен в HTML кода) не се броят към „първите изображения“.
- Изображенията с `fetchpriority="high"` никога не се зареждат отложено.
- За да изключите изображение или iframe, добавете класа `skip-lazy` (или `no-lazy`, `symelo-no-lazy`) или атрибута `data-skip-lazy`.

### Адаптивни изображения

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Add extra image sizes (breakpoints)** | „Запълва празнините между размерите на WordPress, така че телефоните, таблетите и големите екрани да изтеглят изображение, близко до размера, в който го показват.“ | Изключено |
| **Widths** | Ширини в пиксели, разделени със запетая, от 100 до 4000, най-много 12. | 480, 1280, 1920 |
| **Tell browsers how wide images really are** | Задава атрибута `sizes` на блоковете „Изображение“, „Галерия“, „Корица“, „Представително изображение“, „Медия и текст“ и на мрежите с продукти на WooCommerce според оформлението на темата ви, „така че браузърите да не изтеглят по-големи файлове от необходимото.“ | Включено |

„Новите качени изображения получават тези размери. ‚Optimize all images‘, както и ‚Optimize now‘ или ‚Re-optimize‘ в медийната библиотека ги добавят към съществуващите изображения.“ Командата `optimize` на WP-CLI също ги добавя. Допълнителните размери се наричат `symelo-480`, `symelo-1280` и т.н.

**Tell browsers how wide images really are** чете ширината на съдържанието и широката ширина от настройките на блоковата ви тема (или класическата `$content_width`). Опцията оставя собствената стойност на WordPress там, където не може да знае ширината, например при представителните изображения в цикли на заявки (query loops).

### Проверка на доставянето

Щракнете **Test now**. Какво се проверява, зависи от избраната опция за доставяне:

- **&lt;picture&gt; tags**: „Проверява кои формати може да създава този сървър, след което разглежда началната страница така, както я получава посетител: кои изображения имат WebP/AVIF източници и кои се зареждат от друг адрес.“
- **Server rules**: „Заявява тестово изображение така, както го прави браузър, и проверява в какъв формат то се връща.“ Картата показва и дали правилата са на мястото си: **Rules are in wp-content/.htaccess** или **Rules are not in wp-content/.htaccess**.

Тестват се само форматите, отметнати в раздела **Compression**.

| Резултат | Значение |
|---|---|
| „&lt;picture&gt; delivery is on: pages offer WEBP, AVIF versions of optimized images to browsers that support them.“ | Сървърът може да създава копията (режим &lt;picture&gt;). Едно или повече от следващите изречения казват какво е открил тестът на началната страница. |
| „On the home page, *N* images have WebP/AVIF sources.“ | Всичко е наред. |
| „No image on the home page has WebP/AVIF sources yet. Its images may not be optimized yet, or a page cache may still serve an older version of the page.“ | Оптимизирайте изображенията (масова оптимизация), след това изчистете кеша на страниците и кеша на CDN и тествайте отново. |
| „*N* images on the home page load from another address (*cdn.example.com*), so they can't get WebP/AVIF sources.“ | Тези изображения идват от друг домейн, например от CDN, който пренаписва адресите на изображенията, и никога не се обвиват. Ако CDN може сам да конвертира изображенията, изберете **Don't serve them**. |
| „The home page has no images to check.“ | На началната страница няма какво да се провери; копията пак се сервират навсякъде, където има изображения. |
| „The home page couldn't be checked (…).“ | Сайтът не е успял да зареди собствената си начална страница (блокирани заявки, HTTP удостоверяване на тестов сайт). Вместо това проверете някоя страница с инструментите за разработчици на браузъра си. |
| „No WebP or AVIF copy could be made, so there is nothing to serve yet.“ | Сървърът не може да създава копия. Вижте раздела **Engines**. |
| „WebP and AVIF copies are turned off on the Compression tab, so there is nothing to serve.“ | Отметнете **Create WebP copies** или **Create AVIF copies**. |
| „Delivery is off: copies are created but not served by the plugin.“ | Избрано е **Don't serve them**. |
| „The server sends WebP/AVIF to browsers that support them.“ | Всичко е наред (правила на сървъра). |
| „The server sends the modern formats, but without a 'Vary: Accept' header. Enable mod_headers (Apache) so caches keep the versions apart.“ | Работи, но кешовете може да объркат форматите. |
| „The server sends WebP/AVIF correctly, but the site is behind *Cloudflare*, which caches one version of each image for every visitor…“ | Открит е CDN или кеширащ прокси сървър (Cloudflare, Amazon CloudFront, Sucuri, Fastly, BunnyCDN или друг кеширащ прокси). Използвайте **&lt;picture&gt; tags** или се уверете, че CDN кешира изображенията поотделно според заглавката „Accept“. |
| „The server still sends the original image. The rewrite rules aren't active on this server…“ | Правилата не работят тук (няма Apache/LiteSpeed с mod_rewrite или липсва фрагментът за Nginx). Използвайте **&lt;picture&gt; tags**. |

Тестът използва малко изображение в `uploads/symelo-images/public/`, а при **&lt;picture&gt; tags** — и началната ви страница.

### Конфигурация за Nginx

На сървъри с Nginx, когато е избрано **Server rules** или когато проверката в „Здраве на сайта“ наскоро е установила, че запазените оригинали могат да бъдат изтеглени (вижте [Поверителност и сигурност](#поверителност-и-сигурност)), картата показва **Nginx configuration** с бутон **Copy**. Nginx пренебрегва файловете `.htaccess`, на които разчита плъгинът, затова този фрагмент върши тяхната работа:

- Винаги блокира уеб достъпа до личните папки на плъгина: запазените оригинали (които все още съдържат GPS местоположението си) и временните файлове.
- При **Server rules** освен това сервира WebP/AVIF копията на оригиналните адреси на изображенията за форматите, отметнати в раздела **Compression**. Копирайте го отново, когато ги промените.

Плъгинът показва точния фрагмент за вашия сайт. При **Server rules** и отметнати и двата формата той изглежда така:

```nginx
# In the http { } block:
map $http_accept $symelo_images_avif { default ""; "~*image/avif" ".avif"; }
map $http_accept $symelo_images_webp { default ""; "~*image/webp" ".webp"; }

# In the server { } block:
# Kept originals (with their GPS data) and temporary files stay private.
location ^~ /wp-content/uploads/symelo-images/backups/ { deny all; }
location ^~ /wp-content/uploads/symelo-images/tmp/ { deny all; }

# WebP/AVIF copies at the original image URLs.
location ~* ^/wp\-content/.+\.(jpe?g|png|gif|webp)$ {
    types { image/avif avif; image/webp webp; image/jpeg jpg jpeg; image/png png; image/gif gif; }
    add_header Vary Accept;
    try_files $uri$symelo_images_avif $uri$symelo_images_webp $uri =404;
}
```

При **&lt;picture&gt; tags** (или **Don't serve them**) се показва само частта за блока server с двата реда `deny`. Възможно е хостинг доставчикът ви да трябва да добави фрагмента вместо вас. След това презаредете Nginx и щракнете **Test now**.

---

## Раздел Other Folders

Оптимизира изображения, които не са в медийната библиотека: изображенията на темата ви, ресурсите на плъгините и други папки в wp-content. „Оригиналите се запазват както при медийните файлове, така че всичко може да бъде отменено.“

### Настройки

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Active theme (*name*)** | Включва папката на активната ви тема (а при дъщерна тема — и тази на родителската). | Изключено |
| **Other folders** | „По една на ред, спрямо wp-content“, например `plugins/my-plugin/assets` или `uploads/gallery`. Можете да поставите и пътища, които започват с `wp-content/`, или пълния път на сървъра. До 30 папки. | Празно |
| **Check these folders automatically and optimize new or updated images** | „Новите изображения се откриват веднъж дневно. На всеки 10 минути бърза проверка засича и изображенията, които обновяване на тема или плъгин (или повторно разгръщане) е върнало в първоначалния им вид, и ги оптимизира отново.“ Бързата проверка преглежда извадка от оптимизираните изображения в папките; ако някое от тях е било върнато, папките се сканират и оптимизират отново. | Включено |

Щракнете **Save changes**. Папка, която не съществува, се отхвърля: „"…" isn't a folder inside wp-content.“ Папката с резервните копия на самия плъгин не може да бъде добавена.

### Изображения от папки

Тази карта се появява, след като изберете папки. Тя показва „*N* files found, *N* optimized, *P*% smaller for visitors.“, времето на последното сканиране и списък с до 50 файла с техните **Status** и **Size**.

- **Scan folders**: открива нови, променени и премахнати файлове („Found *N* files: *N* new, *N* changed.“).
- **Optimize folder images**: сканира и след това добавя в опашката всеки файл, който още не е оптимизиран, при който е имало грешка или който е бил възстановен.

Какво открива сканирането: JPEG, PNG, GIF и WebP файлове (и PDF файлове, когато **Optimize PDF files** е включена и има механизъм, който може да ги компресира). Пропуска папките `.git`, `.svn`, `node_modules` и `.cache`, папките, които са символни връзки, файловете от медийната библиотека и собствените WebP/AVIF копия на плъгина. Едно сканиране спира след 20 000 файла или 25 секунди: „The scan stopped early (too many files); select smaller folders.“

Изображенията от папки се сервират като WebP/AVIF по същия начин като медийните изображения. Няма начин да възстановите отделни изображения от папки или само изображенията от папки: **Advanced → Restore all originals** (или `wp symelo-images restore --all`) връща всички оригинали — и на изображенията от папки, *и* на цялата медийна библиотека.

---

## Раздел Engines

### Открити на този сървър

Първият ред описва сървъра, например „Linux on x86_64, PHP 8.3.12.“

Таблицата изброява всички механизми:

| Колона | Значение |
|---|---|
| **Engine** | Името и произходът му, например **PHP extension**. |
| **Version** | Откритата версия. |
| **Status** | **Available**, **Outdated** (открит, но твърде стар, за да се използва) или **Not found**, с бележка, която обяснява защо. |
| **Can do** | Задачите, които механизмът изпълнява. |

| Механизъм | Задачи |
|---|---|
| Imagick (ImageMagick) | JPEG, PNG, WebP и AVIF (всеки от тях само ако вашата компилация на ImageMagick го поддържа), преоразмеряване |
| GD | JPEG, PNG, WebP и AVIF (всеки от тях само ако вашата компилация на GD го поддържа), преоразмеряване |

Под таблицата се появяват бележки за графичните библиотеки (вижте [Предупреждения за графичните библиотеки](#предупреждения-за-библиотеките-за-изображения)).

### Механизъм за всяка задача

За всяка задача изберете **Automatic** или конкретен механизъм. „Automatic избира най-добрия наличен механизъм. Ако избраният от вас не може да обработи даден файл, се използва следващият подходящ механизъм.“ Елементът **Automatic** показва кой механизъм избира в момента, например „Automatic (Imagick (ImageMagick))“. Механизмите, които сървърът не може да използва, са изброени, но са неактивни и до тях пише „— not available“.

| Задача | Ред при Automatic |
|---|---|
| **JPEG compression** | Imagick, GD |
| **PNG compression** | Imagick, GD |
| **WebP copies** | Imagick, GD |
| **AVIF copies** | Imagick, GD |
| **PDF compression** | Няма: „This server has no engine that can compress PDFs.“ |
| **Resizing** | Imagick, GD |

Imagick е с предимство, защото запазва цветовите профили и обработва CMYK и 16-битови изображения. GD се използва за файловете, които Imagick откаже да обработи, или когато Imagick не е инсталиран.

Imagick и GD не могат да компресират JPEG без загуби, затова при нивото **Lossless** от JPEG файловете се премахват само метаданните.

Когато за дадена задача няма механизъм, редът под нея го съобщава, например „This server has no engine that can compress PDFs.“

Щракнете **Save changes**. Ако избраният от вас механизъм не е наличен: „*engine* can't do that job on this server, so Automatic is used instead.“ Ако избран механизъм изчезне по-късно (например защото софтуерът, който го е предоставял, е премахнат), за тази задача се използва **Automatic**, без да се показва съобщение.

---

## Раздел Advanced

### Фонова обработка (Background processing)

| Ред | Значение |
|---|---|
| **Waiting in the queue** | Файлове, които чакат да бъдат оптимизирани, възстановени или почистени. |
| **Last run** | Кога е било последното фоново изпълнение и колко файла е обработило за колко секунди. |
| **Started by the site itself** | Последният път, когато сайтът е стартирал изпълнение, като е изпратил заявка до самия себе си. |
| **Started by WP-Cron** | Последният път, когато планировчикът на WordPress е стартирал изпълнение. |
| **Last start error** | Показва се, когато сайтът не е успял да изпрати тази заявка до самия себе си. |

„Сайтът сам стартира кратки фонови изпълнения, а WP-Cron служи като резервен вариант. На сървъри, които блокират и двете, изпълнявайте `wp symelo-images run --paced` от системна cron задача; както фоновите изпълнения, командата спазва скоростта на фоновата обработка по-долу.“

- **Process the queue now** изпълнява една партида веднага. Както пише в картата, това става „без паузите и проверките на натоварването на фоновата скорост“, защото сте го поискали изрично.
- **Empty the queue** премахва всичко чакащо (и отменя текущата масова оптимизация). Вече оптимизираните файлове остават оптимизирани.

### Скорост на фоновата обработка (Background speed)

„Доколко масовата оптимизация може да натоварва сървъра. Новите качвания и ‚Optimize now‘ винаги се обработват веднага.“

| Скорост | Описание в плъгина | Работа на изпълнение | Пауза между изпълненията | Приоритет на енкодера | Нишки на енкодера | Масовата работа изчаква, когато натоварването на ядро на процесора е поне |
|---|---|---|---|---|---|---|
| **Fast** | Дълги серии, една след друга. За самостоятелни (dedicated) сървъри или за първо изпълнение в спокоен период. | 25 с | Няма | Нормален | По подразбиране на енкодера | Никога |
| **Normal (recommended)** (по подразбиране) | Равномерна работа във фонов режим. Масовата работа изчаква, когато сървърът е претоварен. | 15 с | Няма | Понижен | 2 | 2,0 |
| **Gentle, for small servers** | Кратки серии от около 5 секунди с 30-секундни паузи, а масовата работа изчаква винаги, когато сървърът е зает. Големите библиотеки се обработват по-бавно, но посетителите няма да усетят нищо. | 5 с | 30 с | Най-нисък приоритет за процесора и диска | 1 | 0,7 |

- Едно изпълнение никога не продължава по-дълго, отколкото позволява лимитът за време на PHP на вашия сървър.
- Приоритетът и нишките на енкодера важат за механизмите, които стартират отделни програми енкодери (такива механизми могат да добавят други плъгини). Imagick и GD работят вътре в PHP и винаги използват една нишка.
- Когато сървърът предоставя тази информация, ще видите „Server load right now: *X* per CPU core (*N* cores).“, а ако се е случило през последния час — и „Bulk work last waited for a busy server at …“.

Ако скоростта е зададена в wp-config.php: „Set by SYMELO_IMAGES_WORKER_SPEED in wp-config.php.“

### При изтриване на плъгина (When the plugin is deleted)

| Настройка | Какво прави | По подразбиране |
|---|---|---|
| **Delete its settings, records and the WebP/AVIF copies** | Когато изтриете плъгина, се премахват също настройките му, таблицата му в базата данни и всяко WebP/AVIF копие. „Оптимизираните изображения остават такива, каквито са. Запазените оригинали остават в uploads/symelo-images/backups, освен ако не ги изтриете или възстановите преди това.“ | Изключено |

Натиснете **Save changes**.

### Отмяна на всичко (Undo everything)

Показва броя на запазените оригинали: „*N* originals are kept.“

- **Restore all originals**: връща всеки оригинал и премахва всички WebP и AVIF копия — както за изображенията от медийната библиотека, така и за тези от папки. Изпълнява се във фонов режим („Restoring *N* files in the background.“). Ако тече масова оптимизация, тя първо се отменя.
- **Delete all kept originals**: изтрива резервните копия, за да освободи място на диска. Оптимизираните изображения остават, но „промените вече не могат да бъдат отменени“.

И двете действия искат потвърждение. **Restore all originals** пита „Put every original file back, for media and folder images? The optimized versions and all WebP/AVIF copies will be removed.“ **Delete all kept originals** предупреждава, че действието е необратимо.

---

## Раздел Support

- **Get help**: „Повечето проблеми се свеждат до това какво поддържа сървърът (вижте Engines), правата за достъп до файловете или блокирани фонови заявки (вижте Advanced).“ Съдържа връзки към **What this server supports**, **Background processing status** и **Check Site Health**, както и бутон **Email support** (office@symelo.com).
- **System information**: текстов отчет с настройките на плъгина, броя файлове, опашката, механизмите и версиите им, механизма, избран за всяка задача, и данни за сървъра. „Без пароли и ключове.“ Натиснете **Copy system information** и поставете отчета в имейла си до поддръжката.
- **About Symelo LTD**: връзка към symelo.com.

---

## В медийната библиотека

### Колона и поле Optimization

В изгледа със списък на медийната библиотека колоната **Optimization** показва състоянието на всяко изображение. Същата информация се появява и като поле **Optimization** в детайлите за прикачения файл (в изскачащия прозорец на изгледа с мрежа и в екрана за редактиране).

| Състояние | Значение |
|---|---|
| **Optimizing…** | В опашката е или се обработва. Клетката се обновява сама. |
| **Saved *P*% (*before* → *after*)** | Оптимизирано. Когато доставянето на WebP/AVIF е включено, *after* е това, което изтеглят посетителите. Значките **AVIF** и **WebP** показват кои копия съществуват. **Details** изброява всички размери на изображението. |
| **Already optimal** | Файлът не може да бъде направен осезаемо по-малък. |
| Съобщението за грешка | Оптимизацията е неуспешна (вижте [Съобщения за файловете](#съобщения-за-файловете)). |
| Причината или **Skipped** | Файлът е пропуснат, например защото е твърде голям. |
| **Original restored** | Оригиналът е върнат. |
| **Not optimized** | Още не е обработено. |

Бутони (за потребители, които могат да редактират изображението):

| Бутон | Кога се показва | Какво прави |
|---|---|---|
| **Optimize now** | Неоптимизирано или възстановено | Оптимизира изображението веднага. |
| **Re-optimize** | Оптимизирано | Оптимизира отново всички размери от оригинала с текущите настройки. |
| **Restore original** | Оптимизирано, със запазен оригинал | Връща оригинала и премахва копията. Пита „Put the original files back? The optimized versions and WebP/AVIF copies will be removed.“ |
| **Remove WebP/AVIF** | Оптимизирано, но без запазен оригинал | Премахва само копията, след потвърждение. |
| **Try again** | Неуспешно или пропуснато | Опитва отново. За пропуснатите файлове (например над ограничението за размер) обработва отново всички размери на изображението. |

**Optimize now**, **Re-optimize** и **Try again** създават и липсващите размери за точките на прекъсване, когато [точките на прекъсване (breakpoints)](#адаптивни-изображения) са включени.

### Групови действия

В изгледа със списък отметнете изображенията и изберете от **Групови действия**:

- **Optimize images**: оптимизира отново избраните изображения, дори ако преди това са били оптимизирани или пропуснати. Не създава липсващи размери за точките на прекъсване.
- **Restore original images**: възстановява избраните изображения.

Известие потвърждава: „*N* files queued. They are processed in the background.“

Когато изтриете изображение от медийната библиотека, плъгинът изтрива и неговите WebP/AVIF копия, запазения му оригинал и записите за него.

---

## Как се обработва всеки тип файл

| Тип файл | Какво се случва |
|---|---|
| **JPEG** | Компресира се отново с качеството на избраното ниво (или без загуби), записва се като прогресивен JPEG, а метаданните се премахват (ориентацията и цветовият профил се запазват). WebP и AVIF копия (при **Lossless** не се създават). |
| **PNG** | Компресира се отново без загуби или с по-малко цветове при **Aggressive** (или при **Custom** с отметнато **Reduce PNG colours**). Метаданните се премахват. WebP копие (без загуби или със загуби — което е по-малко) и AVIF копие; при **Lossless** — само WebP копие без загуби. |
| **GIF** | Не се компресира отново. Статичните GIF файлове получават WebP копие, както и AVIF копие, ако Imagick или GD могат да го създадат (не и при **Lossless**). Анимираните GIF файлове запазват анимацията си само с механизъм, който я поддържа; Imagick и GD не я поддържат, затова анимираните GIF файлове не получават копия. |
| **WebP** (качен като WebP) | Не се компресира отново, освен ако не трябва да се преоразмери. Метаданните се премахват. Може да получи AVIF копие (не и при **Lossless**). |
| **AVIF** (качен като AVIF) | Пропуска се: „AVIF files are already compressed.“ |
| **PDF** | Обработва се само с механизъм за **PDF compression**, а Imagick и GD не са такива, затова PDF файловете остават непроменени. Подписаните PDF файлове никога не се променят. |

Други правила:

- Файловете се разпознават по съдържанието си, а не по името.
- Копията се записват до файла: `photo.jpg` получава `photo.jpg.webp` и `photo.jpg.avif`. Копие се запазва само ако е по-малко от оптимизирания файл (а AVIF копие — само ако е по-малко и от WebP копието).
- Изображения над 60 мегапиксела или файлове над 100 MB се пропускат: „The file is larger than the limit for optimizing.“
- WebP и AVIF копия на CMYK JPEG файлове (често срещани при подготовка за печат) могат да се създават само с Imagick.
- Ширината, височината и размерът на файла на изображението в WordPress се обновяват след преоразмеряване или възстановяване.

---

## Практически рецепти

### Доставяне на WebP/AVIF зад Cloudflare

CDN мрежи като Cloudflare обикновено кешират една версия на всеки адрес на изображение за всички посетители. При **Server rules** браузър, който не може да показва AVIF, може да получи AVIF файл, кеширан от CDN мрежата за друг посетител. **&lt;picture&gt; tags** избягват този проблем, защото всеки формат има собствен адрес.

1. Отворете **Медия → Image Optimizations → Delivery**.
2. Изберете **&lt;picture&gt; tags (recommended)** и натиснете **Save changes**.
3. Натиснете **Test now** под **Check delivery**.
4. Изчистете кеша на CDN мрежата (и кеша на страниците, ако има такъв), за да получават посетителите обновения HTML.

Ако вашата CDN мрежа сама конвертира изображенията в WebP/AVIF, изберете вместо това **Don't serve them** или изключете копията в раздела **Compression**, за да спестите място на диска.

### Използване на сървърни правила на Apache или LiteSpeed

1. Отворете **Delivery**, изберете **Server rules** и натиснете **Save changes**.
2. Плъгинът записва правилата в `wp-content/.htaccess` и веднага ги тества. Прочетете съобщението в горната част на страницата.
3. Ако в него пише, че сървърът все още изпраща оригиналното изображение, значи сървърът ви не прилага правилата; върнете се към **&lt;picture&gt; tags**.

При Nginx копирайте фрагмента от **Nginx configuration** в конфигурацията на сървъра (или помолете хостинг доставчика си да го направи), презаредете Nginx и натиснете **Test now**.

### Оптимизиране на изображенията на темата

1. Отворете **Other Folders**.
2. Отметнете **Active theme (*name*)**. Ако желаете, добавете и други папки, например `plugins/my-slider/images`.
3. Оставете отметнато **Check these folders automatically and optimize new or updated images**, за да се оптимизират изображенията отново след обновяване на темата.
4. Натиснете **Save changes**, а след това **Optimize folder images**.

Списъкът под **Folder images** показва състоянието на всеки файл.

### Използване на плъгина на малък сървър

1. Отворете **Advanced → Background speed**, изберете **Gentle, for small servers** и натиснете **Save changes**.
2. По желание в **Compression** махнете отметката от **Create AVIF copies**. AVIF е форматът, който се създава най-бавно.
3. Стартирайте масовата оптимизация от **Overview**. Тя работи на кратки серии с паузи, с най-нисък приоритет, и изчаква, докато сървърът е зает. Новите качвания все така се оптимизират веднага.
4. Ако **Advanced → Background processing** не показва скорошни изпълнения, възможно е хостинг доставчикът ви да блокира заявките на сайта до самия себе си. Помолете го да настрои системна cron задача:

   ```sh
   wp symelo-images run --paced --max-seconds=240
   ```

   например на всеки пет минути. С `--paced` командата спазва скоростта Gentle като фоновите изпълнения: кратки серии, паузи и изчакване, докато сървърът е зает. `--max-seconds` прекратява всяко изпълнение, преди да е започнала следващата cron задача.

### Промяна на нивото на компресия и повторна обработка на съществуващите изображения

1. В **Compression** изберете новото ниво и натиснете **Save changes**.
2. В **Overview** отметнете **Also redo images optimized with different settings** и натиснете **Optimize all images**.

Тъй като плъгинът винаги започва от запазените оригинали, по-високото качество наистина връща детайлите, стига **Keep the originals** да е било включено.

### Изключване на изображение от отложеното зареждане или от &lt;picture&gt;

Добавете CSS клас към изображението (в редактора на блокове: **Разширени → Допълнителни CSS класове**):

- `skip-lazy`: изображението винаги се зарежда веднага.
- `no-picture`: изображението никога не се обвива в `<picture>` (винаги се използва оригиналният формат).

### Освобождаване на място на диска

Запазените оригинали може да заемат толкова място, колкото цялата ви оригинална библиотека.

1. Уверете се, че сте доволни от резултатите (прегледайте няколко страници и изображения).
2. Отворете **Advanced → Undo everything** и натиснете **Delete all kept originals**.

След това промените не могат да бъдат отменени. За да спрете запазването на оригинали при бъдещите качвания, махнете отметката от **Keep the originals so changes can be undone** в раздела **Compression**.

### Изключване на размер на изображение

Ако даден размер на изображение трябва да остане точно такъв, какъвто го е създал WordPress (например размер за изтегляне за печат):

1. В **Compression → Exclude image sizes** отметнете този размер и натиснете **Save changes**.
2. Ако изображенията вече са оптимизирани, възстановете ги и ги оптимизирайте отново.

---

## Отстраняване на проблеми

### Проверки в Здраве на сайта

**Инструменти → Здраве на сайта** включва четири проверки. Първите три са със значка „Performance“, а последната — със значка „Security“:

| Проверка | Добър резултат | Проблем и решение |
|---|---|---|
| Images can be converted to WebP and AVIF | „This server can create both modern formats.“ | „This server can't create AVIF images“ (или WebP). Помолете хостинг доставчика си да включи формата в Imagick или GD (вижте [WebP или AVIF не е наличен](#webp-или-avif-не-е-наличен)). |
| Image libraries are up to date | „No image library with known security problems was found.“ | „An image library may need a security update.“ Вижте по-долу. |
| Image optimization runs in the background | „Queued images are being processed.“ | „Image optimization is stuck“: има чакащи файлове, а нищо не е изпълнявано от 30 минути. Вижте [Изображенията остават „Optimizing…“](#изображенията-остават-optimizing). |
| Kept originals are private | „Files in uploads/symelo-images/backups can't be downloaded from the web.“ | „Kept originals can be downloaded by anyone“: сървърът пренебрегва `.htaccess` файловете, които ги защитават (така работи например Nginx). Добавете правилата от **Delivery → Nginx configuration** в конфигурацията на сървъра (вижте [Конфигурация за Nginx](#конфигурация-за-nginx)) или изтрийте запазените оригинали. „Access to kept originals couldn't be checked“ означава, че сайтът не е успял да заяви тестовия файл от самия себе си. |

Проверката за поверителност заявява от вашия сайт малък тестов файл, `uploads/symelo-images/backups/access-check.txt`, така, както би могъл да го направи всеки. Резултатът се запомня за един ден, когато папката е защитена, за един час, когато проверката е неуспешна, и за десет минути, когато файловете могат да бъдат изтеглени, така че поправката се вижда бързо.

**Здраве на сайта → Информация → Symelo Image Optimizations** изброява всеки механизъм с версията и задачите му, както и механизма, използван за всяка задача.

### Изображенията остават „Optimizing…“

Фоновата работа не стартира.

1. Отворете **Advanced → Background processing**. Ако се показва **Last start error**, сървърът ви не е успял да изпрати заявка до самия себе си.
2. Натиснете **Process the queue now**. Ако файловете се обработят, оптимизаторът работи и е блокирано само автоматичното стартиране.
3. Чести причини: защитна стена или плъгин за сигурност, който блокира заявките на сайта до самия себе си, HTTP удостоверяване на тестов (staging) сайт или изключен WP-Cron (`DISABLE_WP_CRON`).
4. Решение: разрешете заявките на сайта до самия себе си или изпълнявайте `wp symelo-images run --paced` от системна cron задача.

Масовата работа напредва и докато разделът **Overview** е отворен.

### WebP или AVIF не е наличен

Опцията е неактивна в **Compression** или в Overview пише **No** за **WebP copies** или **AVIF copies**.

- Отворете **Engines**. Бележките обясняват защо даден механизъм не може да създава формата, например „This GD build can't write AVIF.“ или „The Imagick PHP extension isn't installed.“
- Поискайте от хостинг доставчика си PHP 8.1+ с поддръжка на AVIF в GD или Imagick, компилиран с поддръжка на WebP/AVIF. След това презаредете раздела **Engines**.

### Изображенията не се доставят като WebP/AVIF

- Натиснете **Delivery → Test now** и прочетете съобщението.
- **&lt;picture&gt; tags**: проверете дали изображенията са оптимизирани (колоната в медийната библиотека) и дали копията съществуват (значките **AVIF**/**WebP**). Изчистете кеша на страниците и кеша на CDN мрежата. Изображения, зареждани от друг домейн (например през CDN, която пренаписва адресите на изображенията), никога не се обвиват; **Test now** посочва тези домейни, когато ги открие на началната ви страница.
- **Server rules**: вижте таблицата с резултатите от теста в [Проверка на доставянето](#проверка-на-доставянето).
- Инструментите за разработчици в браузъра показват кой формат е изтеглен (раздел Network, колона „Type“).

### Съобщения за файловете

Появяват се в медийната библиотека, в **Overview → Recent problems** и в списъка в **Other Folders**.

| Съобщение | Какво да направите |
|---|---|
| „The file can't be changed: the web server has no write permission.“ | Помолете хостинг доставчика си да даде на уеб сървъра права за запис в папката за качвания (или в избраната папка). |
| „The file no longer exists.“ | Файлът е изтрит извън WordPress. Не е нужно да правите нищо. |
| „This file is outside the folders the plugin may change.“ | Файлът не е в uploads или в избрана папка (или символна връзка сочи извън тях). |
| „Not a supported image or PDF.“ | Съдържанието на файла не е JPEG, PNG, GIF, WebP или PDF, каквото и да подсказва името му. |
| „AVIF files are already compressed.“ | Така е предвидено; качените AVIF файлове не се променят. |
| „The file is larger than the limit for optimizing.“ | Над 60 мегапиксела или над 100 MB. Разработчик може да увеличи ограниченията (вижте филтрите). След това натиснете **Try again** под изображението в медийната библиотека (или използвайте груповото действие **Optimize images**). Масовата оптимизация не опитва отново пропуснатите файлове. |
| „The backups folder could not be created, so the file was left untouched.“ / „The original could not be backed up, so the file was left untouched.“ | Проверете дали папката `uploads/symelo-images` може да бъде създадена и дали в нея може да се записва, както и дали има свободно място на диска. |
| „The optimized file could not be written.“ / „The temporary folder could not be created.“ | Дискът е пълен или липсват права за запис. |
| „No engine on this server can create WEBP.“ (или AVIF) | Вижте [WebP или AVIF не е наличен](#webp-или-avif-не-е-наличен). |
| „No PDF engine is available on this server.“ | Imagick и GD не могат да компресират PDF файлове. Изключете **Compression → Optimize PDF files**, ако не искате PDF файловете да се показват в списъка. |
| „GD could not read the image.“ / „ImageMagick: …“ | Механизмът не е успял да обработи този файл. Изберете друг механизъм за тази задача в **Engines** и опитайте отново. |
| „Processing stopped: …“ / „Processing stopped unexpectedly several times. The image may be too large for this server's memory or time limits.“ | На PHP не са му стигнали паметта или времето. Поискайте от хостинг доставчика си по-висок лимит на паметта или изключете много големите изображения. |
| „The original wasn't kept, so only the WebP and AVIF copies were removed.“ | Показва се след **Restore**, когато **Keep the originals** е било изключено. |

**Try failed files again** (в Overview) или **Try again** (в медийната библиотека) добавя неуспешните файлове отново в опашката. **Try again** опитва отново и пропуснатите изображения.

### Предупреждения за библиотеките за изображения

В **Overview**, **Engines** и в Здраве на сайта може да видите предупреждения като:

- „ImageMagick *version* is older than *version*, which fixes published security issues…“ Възможно е хостинг доставчикът ви да е отстранил уязвимостите, без да променя версията; ако не е, помолете го да обнови ImageMagick (самият WordPress я използва при всяко качване).

Ако библиотеката идва от Linux дистрибуция, която пренася поправките за сигурност в по-старите версии (например пакетите на Debian или Ubuntu), плъгинът показва вместо това по-спокойна бележка, с която ви моли да поддържате пакетите на сървъра актуални.

### Все още имате проблем?

Отворете раздела **Support**, натиснете **Copy system information** и изпратете информацията по имейл на office@symelo.com заедно с описание на проблема.

---

## Поверителност и сигурност

### Какво се съхранява и къде

| Данни | Къде |
|---|---|
| Настройки | Опцията `symelo_images_settings` в базата данни. |
| По един запис за всеки оптимизиран файл: път, размери, състояние, използвани механизми, контролна сума, грешки | Таблица в базата данни, `{prefix}symelo_images`, за всеки сайт. |
| WebP и AVIF копия | До всяко изображение (`photo.jpg.webp`, `photo.jpg.avif`). |
| Запазени оригинали | `uploads/symelo-images/backups/`, както и малкият файл `access-check.txt`, който заявява проверката за поверителност в Здраве на сайта. |
| Временни файлове | `uploads/symelo-images/tmp/`. Остатъците, по-стари от един ден, се изтриват ежедневно. |
| Тестово изображение за доставянето | `uploads/symelo-images/public/`. |

Плъгинът добавя `.htaccess` файлове, които блокират уеб достъпа до папките с резервни копия и временни файлове на Apache и LiteSpeed. **При Nginx тези файлове нямат ефект.** Запазените оригинали все още съдържат GPS местоположението и метаданните от фотоапарата, затова при Nginx тези папки трябва да бъдат блокирани в конфигурацията на сървъра:

```nginx
location ^~ /wp-content/uploads/symelo-images/backups/ { deny all; }
location ^~ /wp-content/uploads/symelo-images/tmp/ { deny all; }
```

**Delivery → Nginx configuration** показва тези редове с точните пътища за вашия сайт (вижте [Конфигурация за Nginx](#конфигурация-за-nginx)); `^~` им дава предимство пред правилата за изображения, например тези на самия плъгин. Независимо какъв уеб сървър използвате, Здраве на сайта проверява дали запазените оригинали не могат да бъдат изтеглени и ви предупреждава, ако могат (вижте [Проверки в Здраве на сайта](#проверки-в-здраве-на-сайта)).

### Какво се изпраща и къде

- **Изображенията никога не напускат сървъра ви.** Цялата компресия и всички конвертирания се извършват локално.
- **Фонова работа**: сайтът ви изпраща кратки заявки до самия себе си (до `wp-admin/admin-ajax.php`, удостоверени със случаен таен ключ, различен за всеки сайт) и използва WP-Cron. Тестът за доставянето заявява от собствения ви сайт тестово изображение (а при &lt;picture&gt; таговете — и началната страница), а проверката за поверителност в Здраве на сайта заявява тестов файл от папката с резервни копия.
- **Без външни услуги.** Плъгинът не изпраща данни към никаква външна услуга.
- Нищо не се изпраща към Symelo LTD. Връзките към symelo.com и имейл връзката в раздела Support правят нещо само когато ги натиснете.

### Премахване на метаданни

Когато **Remove metadata** е включено, EXIF (фотоапарат, настройки, GPS местоположение), XMP, IPTC и коментарите се премахват от оптимизираните изображения и техните копия. Оригиналът в пълен размер, който WordPress пази за мащабираните снимки, също губи метаданните си, дори когато не е оптимизиран. Запазените оригинали в папката с резервни копия остават непроменени и затова не бива да могат да бъдат изтегляни (вижте по-горе).

### Бележки за сигурността

- Плъгинът работи само с библиотеките за изображения на PHP. Той не стартира и не изтегля програми.
- Файловете се променят само в uploads, wp-content и папките, които изберете. Символните връзки не могат да водят извън тях.
- ImageMagick винаги получава изрично зададен файлов формат и ограничения на ресурсите.
- Всяко административно действие проверява правата и nonce защитата на WordPress. Фоновият процес не приема нищо друго освен тайния ключ на сайта и може да обработва само това, което вече е в опашката.

---

## Отмяна и деинсталиране

| Искате да… | Направете следното |
|---|---|
| Отмените промените по едно изображение | Медийна библиотека → **Restore original**. |
| Отмените промените по няколко изображения | Изглед със списък в медийната библиотека → отметнете ги → **Restore original images**. |
| Отмените промените по изображенията от папки | **Advanced → Restore all originals**. Това възстановява и медийната библиотека; изображенията от папки не могат да бъдат възстановени отделно. |
| Отмените всичко | **Advanced → Restore all originals**, след което изчакайте **Waiting in the queue** да стане 0. |
| Спрете доставянето на WebP/AVIF | **Delivery → Don't serve them**. |
| Спрете оптимизирането на новите качвания | **Compression** → махнете отметката от **Optimize new uploads automatically**. |

Възстановяването работи само за файлове, чийто оригинал е запазен (**Keep the originals** е включено и **Delete all kept originals** не е използвано). Без оригинал възстановяването премахва само WebP и AVIF копията. Това важи и за оригиналите в пълен размер, които WordPress пази за мащабираните снимки: когато **Keep the originals** е включено, те се архивират, преди метаданните им да бъдат премахнати, така че възстановяването връща метаданните.

Преди възстановяване се иска потвърждение: „Put the original files back? The optimized versions and WebP/AVIF copies will be removed.“ След това можете да оптимизирате изображенията отново по всяко време.

**Деактивирането** на плъгина:

- спира цялата фонова работа и планираните задачи;
- премахва сървърните правила от `wp-content/.htaccess`;
- спира &lt;picture&gt; таговете, както и отложеното зареждане, адаптивните размери и размерите за точките на прекъсване на плъгина (собственото отложено зареждане на WordPress продължава да работи);
- оставя на място оптимизираните изображения, копията, запазените оригинали и настройките, така че при повторно активиране работата продължава оттам, докъдето е стигнала.

**Изтриването** на плъгина (Разширения → Изтриване):

- Винаги: премахва планираните задачи, сървърните правила, временните файлове, тестовото изображение за доставянето и състоянието на фоновия процес.
- Ако **Advanced → Delete its settings, records and the WebP/AVIF copies** е включено: изтрива също всяко WebP/AVIF копие, таблицата в базата данни и настройките.
- Никога: оптимизираните ви изображения остават такива, каквито са, а запазените оригинали остават в `uploads/symelo-images/backups`.

За да се върнете напълно към оригиналните си изображения:

1. **Advanced → Restore all originals**.
2. Изчакайте, докато **Advanced → Background processing → Waiting in the queue** покаже 0.
3. Отметнете **Delete its settings, records and the WebP/AVIF copies** и натиснете **Save changes**.
4. Деактивирайте и изтрийте плъгина.
5. Изтрийте папката `uploads/symelo-images`, ако в нея е останало нещо.

---

## За разработчици

### Константи в wp-config.php

Константите имат предимство пред екрана с настройки и заключват съответните опции.

| Константа | Стойности | Настройка |
|---|---|---|
| `SYMELO_IMAGES_DELIVERY` | `picture`, `rewrite` или `none` | **Delivery → Serving WebP and AVIF** |
| `SYMELO_IMAGES_WORKER_SPEED` | `fast`, `normal` или `gentle` | **Advanced → Background speed** |

При невалидни стойности на `SYMELO_IMAGES_DELIVERY` и `SYMELO_IMAGES_WORKER_SPEED` се използват стойностите по подразбиране (`picture`, `normal`).

### Филтри

| Филтър | По подразбиране | Предназначение |
|---|---|---|
| `symelo_images_capability` | `'manage_options'` | Правото (capability) за екрана с настройки, масовата оптимизация и REST API. За оптимизиране и възстановяване на отделни изображения в медийната библиотека (бутони, групови действия) е нужно само право за редактиране на съответното изображение (`edit_post`), така че авторите могат да оптимизират собствените си качвания. |
| `symelo_images_engine_order` | Механизмите, подредени по ранг | `( array $engine_ids, string $task )`. Автоматичният ред за всяка задача (`jpeg`, `png`, `webp`, `avif`, `pdf`, `resize`). |
| `symelo_images_max_pixels` | `60000000` | Изображенията с повече пиксели се пропускат. |
| `symelo_images_max_bytes` | `100 * MB_IN_BYTES` | По-големите файлове се пропускат. |
| `symelo_images_imagick_limits` | памет 256 MB, map 512 MB, диск 2048 MB, 1 нишка, 180 с | Име на константа `Imagick::RESOURCETYPE_*` => ограничение. |
| `symelo_images_pace` | Вижте [Скорост на фоновата обработка](#скорост-на-фоновата-обработка-background-speed) | `( array $profile, string $speed )`. Ключове: `budget`, `pause`, `nice`, `idle_io`, `threads`, `max_load`. |
| `symelo_images_worker_budget` | Бюджетът на избраната скорост | Секундите, през които едно фоново изпълнение работи, преди да предаде работата на следващото (минимум 5). |
| `symelo_images_dispatch_args` | Неблокираща POST заявка | Аргументите на `wp_remote_post()` за заявката, която сайтът изпраща до самия себе си. |
| `symelo_images_skip_page` | `false` | Върнете `true`, за да пропуснете обработката на цялата страница (&lt;picture&gt; и отложено зареждане) за текущата заявка. |
| `symelo_images_more_from_symelo` | `[]` | Продуктите, изброени под „More from Symelo LTD“ в раздела Support. |
| `symelo_images_tabs` | `[]` | Допълнителни раздели в екрана на плъгина (`slug => label`); вижте `docs/extending.md`. |
| `symelo_images_warnings`, `symelo_images_notes` | Проверките на библиотеките | `( string[] $items, Plugin $plugin )`. Предупрежденията (в Overview) и бележките (в Engines), които се показват също в системната информация и в `GET /status`. |
| `symelo_images_system_info` | Секциите на отчета | `( array $sections, Plugin $plugin )`. Секциите на системната информация в раздела Support. |
| `symelo_images_rest_status` | Отчетът за състоянието | `( array $status, Plugin $plugin )`. Отговорът на `GET /status`. |

### Действия

| Действие | Аргументи | Кога |
|---|---|---|
| `symelo_images_loaded` | `Plugin $plugin` | Плъгинът е зареден. |
| `symelo_images_register_engines` | `EngineManager $engines` | Списъкът с механизми се изгражда; добавяйте механизми с `$engines->add()`. |
| `symelo_images_file_optimized` | `FileRecord $after, FileRecord $before` | След като файл е оптимизиран, оптимизацията му е неуспешна, бил е пропуснат или е възстановен. |
| `symelo_images_engines_tab` | `Plugin $plugin` | В края на раздела Engines, за картите на добавките. |
| `symelo_images_tab_{$slug}` | `Plugin $plugin` | Изобразява панела на раздел, добавен със `symelo_images_tabs`. |

Добавките се изграждат върху тези куки (hooks) и върху класовете, изброени в `docs/extending.md`, където са обяснени също механизмите, ранговете и константата `SYMELO_IMAGES_API_VERSION` (в момента `1.0`).

### HTML класове и атрибути

| Клас или атрибут | Ефект |
|---|---|
| `skip-lazy`, `no-lazy`, `symelo-no-lazy`, `data-skip-lazy` | Това изображение или iframe никога не се зарежда отложено. |
| `no-picture`, `skip-picture`, `symelo-no-picture`, `data-skip-picture` | Това изображение никога не се обвива в `<picture>`. |
| `fetchpriority="high"` | Никога не се зарежда отложено. |

### WP-CLI

| Команда | Какво прави |
|---|---|
| `wp symelo-images status` | Механизмът за всяка задача, общият брой файлове, спестеното място и размерът на опашката, както и предупрежденията за библиотеките. |
| `wp symelo-images optimize <id>... [--force]` | Оптимизира веднага тези прикачени файлове (и създава липсващите размери за точките на прекъсване). `--force` обработва отново и вече оптимизираните файлове. |
| `wp symelo-images optimize --all [--force]` | Всички изображения в медийната библиотека (и PDF файловете, когато се оптимизират PDF файлове). |
| `wp symelo-images restore <id>...` | Възстановява тези прикачени файлове. |
| `wp symelo-images restore --all [--yes]` | Възстановява всички оптимизирани файлове, включително файловете от папки, и премахва всички копия. |
| `wp symelo-images run [--max-seconds=<seconds>] [--paced]` | Обработва опашката, докато се изпразни (или докато изтече времето, минимум 10 секунди). Използвайте тази команда от системна cron задача. Без `--paced` тя работи без паузи; с `--paced` спазва **Background speed** като фоновите изпълнения (продължителност на порцията, паузи между масовите порции, изчакване, докато сървърът е зает). |
| `wp symelo-images folders` | Сканира избраните папки и оптимизира новите или променените файлове. |

### REST API

Всички маршрути са под `/wp-json/symelo-images/v1/` и изискват правото на плъгина (администратор, например с парола за приложение). Маршрутите за прикачени файлове проверяват и дали можете да редактирате всеки от тях.

| Метод и маршрут | Параметри | Какво прави |
|---|---|---|
| `GET /status` | – | Пълен отчет: версия и версия на API, платформа, механизми, задачи, предупреждения и бележки, настройки, общи стойности, напредък на масовата оптимизация, състояние на фоновия процес, доставяне (включително проверката за поверителност на папката с резервни копия, `delivery.private_files`). |
| `GET /settings` | – | Всички настройки. |
| `POST /settings` | JSON тяло с произволни ключове на настройки | Променя само изпратените ключове, като ги валидира както екранът с настройки. Връща настройките и евентуалните грешки. |
| `POST /optimize` | `ids` (масив, до 500), `force` (bool), `now` (bool) | Добавя прикачени файлове в опашката; с `now` ги обработва в рамките на заявката. |
| `POST /restore` | `ids`, `now` | Възстановява прикачени файлове. |
| `GET /attachments/{id}` | – | Записите за един прикачен файл. |
| `GET /bulk` | – | Напредъкът на масовата оптимизация. |
| `POST /bulk` | `action` (`start`, `pause`, `resume`, `cancel`), `reoptimize`, `media` (по подразбиране true), `folders` | Управлява масовата оптимизация. |
| `POST /worker` | `seconds` (5–60, по подразбиране 20) | Обработва опашката за известно време в рамките на тази заявка (алтернатива на WP-CLI при външен cron). |
| `POST /delivery/test` | – | Изпълнява теста за доставянето. При &lt;picture&gt; таговете `page` съдържа проверката на началната страница (`images`, `pictures`, `foreign`, `hosts`), а `ok`/`message` я описват. |
| `POST /folders` | `action` (`scan`, `optimize`) | Сканира или оптимизира избраните папки. |
| `POST /maintenance` | `action` (`restore_all`, `drop_backups`, `clear_queue`, `retry_failed`) | Действията по поддръжката от разделите Advanced и Overview. |

### Планирани задачи

| Кука | График | Предназначение |
|---|---|---|
| `symelo_images_daily` | Ежедневно | Изтрива остарелите временни файлове, възстановява липсващите сървърни правила и сканира избраните папки. |
| `symelo_images_worker` | Всяка минута, само докато има работа в опашката | Резервен механизъм, който стартира фоновите изпълнения. |
| `symelo_images_worker_next` | Еднократно | Стартира следващото изпълнение след пауза (при скорост Gentle или зает сървър). |
| `symelo_images_folder_check` | На всеки 10 минути, докато има избрани папки и ежедневната проверка е включена | Оптимизира отново изображенията от папки, които са били върнати в изходния си вид. |

Всички те се премахват при деактивиране.