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

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

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

Нуждаете се от помощ? Пишете на [email protected] или посетете symelo.com.

Какво прави

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

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

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

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

Изисквания

• 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 не са налични). За PDF compression пише No: Imagick и GD не могат да компресират PDF файлове.

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

Настройките по подразбиране са подходящи за повечето сайтове. Ако искате да ги проверите, отворете раздела Compression. Най-важният избор е Compression level; препоръчва се Balanced. Вижте Раздел 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 има осем раздела. Превключват се мигновено, без презареждане на страницата.

В медийната библиотека също се появяват колона 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.“

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

Статистика

Тези показатели се отнасят за медийната библиотека. Изображенията от папки имат свои показатели в раздела 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 при отделни изображения.

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

При 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.

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

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.“

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

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

Оригинали

Когато оригиналът в пълен размер не се оптимизира, метаданните му (например 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

<picture> 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).
• Ако правилата изчезнат (например след повторно разгръщане на сайта), плъгинът ги връща следващия път, когато администратор отвори 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.“

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

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

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

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

„Новите качени изображения получават тези размери. ‚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. Какво се проверява, зависи от избраната опция за доставяне:

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

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

Тестът използва малко изображение в uploads/symelo-images/public/, а при <picture> tags — и началната ви страница.

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

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

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

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

# 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;
}

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

---

Раздел Other Folders

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

Настройки

Щракнете 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.“

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

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

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

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

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)

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

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

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

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

• Едно изпълнение никога не продължава по-дълго, отколкото позволява лимитът за време на 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)

Натиснете 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 ([email protected]).
• System information: текстов отчет с настройките на плъгина, броя файлове, опашката, механизмите и версиите им, механизма, избран за всяка задача, и данни за сървъра. „Без пароли и ключове.“ Натиснете Copy system information и поставете отчета в имейла си до поддръжката.
• About Symelo LTD: връзка към symelo.com.

---

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

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

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

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

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

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

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

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

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

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

---

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

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

• Файловете се разпознават по съдържанието си, а не по името.
• Копията се записват до файла: 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 мрежата за друг посетител. <picture> tags избягват този проблем, защото всеки формат има собствен адрес.

1. Отворете Медия → Image Optimizations → Delivery.
2. Изберете <picture> 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. Ако в него пише, че сървърът все още изпраща оригиналното изображение, значи сървърът ви не прилага правилата; върнете се към <picture> 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 задача:

   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 да е било включено.

Изключване на изображение от отложеното зареждане или от <picture>

Добавете 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“:

Проверката за поверителност заявява от вашия сайт малък тестов файл, 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 и прочетете съобщението.
• <picture> tags: проверете дали изображенията са оптимизирани (колоната в медийната библиотека) и дали копията съществуват (значките AVIF/WebP). Изчистете кеша на страниците и кеша на CDN мрежата. Изображения, зареждани от друг домейн (например през CDN, която пренаписва адресите на изображенията), никога не се обвиват; Test now посочва тези домейни, когато ги открие на началната ви страница.
• Server rules: вижте таблицата с резултатите от теста в Проверка на доставянето.
• Инструментите за разработчици в браузъра показват кой формат е изтеглен (раздел Network, колона „Type“).

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

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

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 и изпратете информацията по имейл на [email protected] заедно с описание на проблема.

---

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

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

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

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

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

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

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

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

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

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

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

---

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

Възстановяването работи само за файлове, чийто оригинал е запазен (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;
• спира <picture> таговете, както и отложеното зареждане, адаптивните размери и размерите за точките на прекъсване на плъгина (собственото отложено зареждане на 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 и SYMELO_IMAGES_WORKER_SPEED се използват стойностите по подразбиране (picture, normal).

Филтри

Действия

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

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

WP-CLI

REST API

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

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

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