Image Cleaner Utility для ocStore / OpenCart

Модуль Очистки Неиспользуемых Изображений для ocStore

Общая информация

Image Cleaner — это бесплатный модуль для ocStore/OpenCart, предназначенный для поиска и удаления неиспользуемых изображений из папки /image/catalog/. Этот модуль помогает поддерживать ваш сайт оптимизированным, освобождая дисковое пространство, удаляя изображения, которые не используются на сайте, например, не привязанные к товарам, категориям, баннерам, производителям, информационным страницам или блогам. Модуль десятки раз проверялся на работем сайте на локальном сервере и виртуальном хостинге в паре ocStore 3.0.3.7 + PHP 7.3.

Модуль интегрируется в административную панель и добавляет пункт меню «Уборка в картинках», через который можно запускать проверку и удаление неиспользуемых изображений.

Введение для новичков

Image Cleaner Utility — это простой модуль для интернет-магазина на ocStore (или OpenCart), который помогает найти и удалить ненужные картинки из папки /image/catalog/. Если вы не знаете, что такое PHP, база данных, FTP или OCMOD — этот документ должен помочь. Всегда можно задать вопрос или обратиться к любому специалисту-кодеру.

Зачем это нужно? Когда вы добавляете товары, категории или баннеры в магазин, изображения сохраняются в папке /image/catalog/. Если вы удаляете товар, его картинки могут остаться — это "мусор", который занимает место на сервере. Image Cleaner находит такие файлы и позволяет их удалить через админ-панель, не копаясь в коде.

Важно для новичков: Сделайте резервную копию сайта (все файлы + база данных) перед использованием! Используйте FileZilla для файлов и phpMyAdmin для базы данных. Это спасёт, если что-то пойдёт не так.

Почему это важно

При работе с интернет-магазином со временем накапливаются изображения, которые больше нигде не используются. Они занимают место на сервере и могут замедлять или делать невозможным резервное копирование сайта. Image Cleaner позволяет безопасно удалить такие файлы.

Основные возможности

• Сканирование папки /image/catalog/ на наличие неиспользуемых изображений.
• Удаление найденных файлов с подтверждением действия.
• Белый список критически важных файлов, которые нельзя удалять (placeholder.png, no_image.png, логотип магазина).
• Проверка HTML-описаний товаров, страниц и блогов для поиска используемых изображений.
• Отображение результатов проверки и удаления прямо в админ-панели.
• Защита с помощью CSRF-токена (user_token).
• Проверка прав на файлы перед удалением.
• Многоязычная поддержка. Добавляет в админ-панель пункт меню с названием:
  • "Уборка в картинках" (русский).
  • "Image Cleanup" (английский).
  • "Очищення зображень" (украинский).
• OCMOD: На данный момент модуль не использует OCMOD (систему модификаторов ocStore/OpenCart). Установка требует ручного копирования файлов и простейшей правки кода в одном файле (см. раздел "Подробная инструкция по установке"). В будущем, для Image Cleaner Utility поддержка OCMOD также не планируется, достаточно, если вы хоть не много можете читать код, а если нет - то стоит обратиться к такому человеку.

Структура файлов модуля

admin/
├── controller/
│ └── tool/
│ └── image_cleaner.php # Логика модуля
├── language/
│ ├── en-gb/tool/image_cleaner.php // английская локализация модуля
│ ├── ru-ru/tool/image_cleaner.php // русская локализация модуля
│ └── uk-ua/tool/image_cleaner.php // украинская локализация модуля
└── view/
 └── template/
 └── tool/
 └── image_cleaner.twig # Шаблон отображения интерфейса управления утилитой

Требования (проверьте перед установкой)

Чтобы модуль работал, ваш магазин должен соответствовать этим требованиям:

• ocStore/OpenCart: Версия 3.0.3.7. Если у вас другая версия (например, OpenCart 3.x), протестируйте на копии сайта.
• PHP: Версия 7.3. Проверьте в админке: "Система" → "Информация о сервере" → найдите "PHP Version".
• Доступ к файлам: Нужен FTP (через FileZilla) или доступ через панель хостинга (cPanel, DirectAdmin и т.д.).
• Права на файлы: Папка /image/catalog/ должна быть доступна для чтения и записи (права 755 для папок, 644 для файлов, иногда 777).
• База данных: MySQL или MariaDB, доступ через phpMyAdmin.
• Модуль блога (опционально): Если используете OCTemplates блог (таблицы oct_blogarticle_***), модуль проверит и его изображения.

Как узнать версию PHP?

1. Зайдите в админку.
2. Перейдите: "Система" → "Информация о сервере".
3. Найдите строку "PHP Version". Если не 7.3, попросите хостинг обновить.

Подробная инструкция по установке

Ниже описаны шаги для абсолютного новичка, чтобы модуль заработал корректно.

1. Скачивание модуля

• Перейдите на страницу проекта на GitHub: https://github.com/webitproff/oc-image_cleaner
• Нажмите кнопку "Code" → "Download ZIP".
• Распакуйте архив на вашем компьютере.
• Либо для продвинутых можно использовать Git: git clone https://github.com/webitproff/oc-image_cleaner.git

2. Копирование файлов

• Скопируйте содержимое папки upload/ из архива в корневую директорию вашего сайта, где установлен ocStore/OpenCart. Просто тупо папку admin копируем в папку сайта.
• При копировании, текущие файлы движка не перезаписываются!

3. Добавление пункта меню в админку

• Откройте файл admin/controller/common/column_left.php.
• Найдите строку:

$this->load->language('common/column_left');

• После неё добавьте следующий код:

$this->load->language('tool/image_cleaner'); // строка загрузки языковой локализации image_cleaner (Загружает переводы для модуля) 

• Найдите массив $data['menus'][] (это список пунктов меню админки). После первого пункта (обычно Dashboard, Панель стану, Панель состояния)::

// Menu
$data['menus'][] = array(
'id' => 'menu-dashboard',
'icon' => 'fa-dashboard',
'name' => $this->language->get('text_dashboard'),
'href' => $this->url->link('common/dashboard', 'user_token=' . $this->session->data['user_token'], true),
'children' => array()
);

• После неё добавьте следующий код:

// start пункт меню утилиты image_cleaner
$data['menus'][] = array(
'id' => 'menu-tool-image-cleaner',
'icon' => 'fa fa-trash-o',
'name' => $this->language->get('image_cleaner_title'),
'href' => $this->url->link('tool/image_cleaner', 'user_token=' . $this->session->data['user_token'], true),
'children' => array()
);
// end пункт меню утилиты image_cleaner

• Это добавит пункт меню "Уборка в картинках" с иконкой корзины в левую колонку админки.

4. Проверка прав доступа к модулю

Чтобы модуль был виден и функционален, нужно выдать права пользователям:

1. В админ-панели перейдите в Система → Пользователи → Группы пользователей.
2. Найдите группу, которой нужно дать доступ (обычно Администратор), и нажмите Изменить.
3. Вкладки:
   • Доступ к модулям (Access Permission)
   • Права на изменение (Modify Permission)
4. В обоих списках поставьте галочку напротив:

tool/image_cleaner

1. Нажмите Сохранить. После этого пользователи группы смогут видеть модуль в меню и использовать его функционал.

5. Проверка прав на папку с изображениями

• Убедитесь, что папка /image/catalog/ имеет права на чтение и запись.
• Обычно достаточно прав 755. Если модуль не видит файлы или не может их удалить, можно временно выставить 777.

6. Очистка кэша

• В админ-панели ocStore перейдите в Система → Инструменты → Очистка кэша.
• Нажмите кнопки очистки кэша системы и кэша шаблонов.

Использование модуля

1. Открытие модуля

• В админ-панели найдите пункт меню «Уборка в картинках».
• Кликните по нему, откроется интерфейс модуля.

2. Сканирование изображений

• Нажмите кнопку «Проверить».
• Модуль просканирует папку /image/catalog/ и проанализирует базу данных, чтобы определить, какие изображения не используются.
• После завершения сканирования появится список неиспользуемых изображений.

3. Удаление изображений

• Если вы уверены, что хотите удалить неиспользуемые изображения, нажмите кнопку «Удалить».
• Появится предупреждение, так как удаление необратимо.
• После подтверждения удалятся файлы, которые не используются, кроме тех, что находятся в белом списке.
• Результаты удаления отобразятся на экране: файлы, удаленные успешно, и файлы, которые не удалось удалить.

4. Резервное копирование

• Перед удалением обязательно сделайте резервную копию папки /image/catalog/.
• Это позволит восстановить файлы, если случайно будут удалены нужные изображения.

Принцип работы модуля

• Модуль проверяет наличие таблиц базы данных: product, product_image, category, banner_image, manufacturer, information_description, product_description, oct_blogarticle, oct_blogarticle_description.
• Извлекает все пути изображений из полей image.
• Анализирует HTML-описания товаров, страниц и блогов для поиска всех <img src> и <a href> с /catalog/.
• Создает список всех используемых изображений и удаляет дубликаты.
• Сравнивает файлы в папке /image/catalog/ с этим списком.
• Файлы, отсутствующие в базе и не входящие в белый список, считаются неиспользуемыми.
• При подтверждении удаления файлы удаляются, если есть права на запись.

Белый список

Файлы, которые никогда не удаляются:

• catalog/placeholder.png
• catalog/no_image.png
• Логотип магазина (config_logo)

Технические детали

• Версия: 2.0.1
• Совместимость: ocStore 3.0.3.7, OpenCart 3.x
• PHP: 7.3
• Использует CSRF-токен (user_token) для защиты от атак
• Проверяет права на файлы перед удалением
• Проверяет наличие таблиц перед выполнением SQL-запросов

Ограничения

• Удаление необратимо — обязательно создавайте резервную копию
• Кастомные модули с изображениями могут не учитываться
• Поддержка OCT Blog только при наличии таблиц oct_blogarticle и oct_blogarticle_description

Структура кода

1. Контроллер: admin/controller/tool/image_cleaner.php

Это "мозг" модуля, написан на PHP.

index()

• Загружает переводы: $this->load->language('tool/image_cleaner').
• Устанавливает заголовок страницы: Очистка неиспользуемых изображений.
• Создаёт ссылки для кнопок:
  • "Проверить" → action=scan
  • "Удалить" → action=delete
• Загружает шаблон страницы: image_cleaner.twig.

scanUnusedImages($delete)

• Собирает все используемые изображения из базы данных: Таблицы: product, product_image, category, banner_image, manufacturer, oct_blogarticle, oct_blogarticle_image.
  Поля: image (например, catalog/product.jpg).
  Описания: information_description, product_description, oct_blogarticle_description (ищет <img src="catalog/...">).
• Сравнивает с файлами в /image/catalog/.
• Если $delete = true, удаляет ненужные файлы.
• Возвращает список результатов (пути файлов или сообщения).

Как работает

• Проверяет таблицы базы данных, например:

  SELECT image FROM oc_product;

   

• Парсит HTML-описания с помощью регулярных выражений (preg_match_all) для поиска путей (src, href).

• Нормализует пути:

  $p = str_replace('\\', '/', $p); // Заменяет \ на /
  $p = ltrim($p, '/'); // Убирает ведущий /
  if (strpos($p, 'image/') === 0) {
   $p = substr($p, strlen('image/')); // Убирает image/
  }

   

  1. Обходит папку /image/catalog/ с помощью RecursiveIteratorIterator.
  2. Игнорирует файлы из белого списка (placeholder.png, no_image.png, логотип).

2. Языковые файлы

Расположение: admin/language/*/tool/image_cleaner.php (ru-ru, en-gb, uk-ua).

Пример (русский):

$_['image_cleaner_title'] = 'Уборка в картинках'; // Название в меню
$_['heading_title'] = 'Очистка неиспользуемых изображений'; // Заголовок
$_['text_check'] = 'Проверить'; // Кнопка
$_['text_delete'] = 'Удалить'; // Кнопка
$_['text_warning'] = 'Удалить все неиспользуемые изображения? Это действие необратимо!';

Для английского и украинского языков аналогично. При добавлении нового языка создайте файл в admin/language/код_языка/tool/.

3. Шаблон: admin/view/template/tool/image_cleaner.twig

• Заголовок: {{ heading_title }}
• Кнопки:
  • "Проверить": {{ scan_url }}
  • "Удалить": {{ delete_url }} с подтверждением
• Область результатов: <pre> с прокруткой
• Предупреждение о бэкапе: {{ text_backup }}
• Ссылка на GitHub: {{ image_cleaner_github }}

4. Интеграция в меню: admin/controller/common/column_left.php

• Добавляет пункт меню в админку.
• Загружает переводы и создаёт ссылку с иконкой корзины (fa-trash-o).

Если модуль не использует OCMOD, файл редактируется вручную.

Технические детали

Сканирование

1. Проверяет таблицы базы данных:
   • Стандартные: product, product_image, category, banner_image, manufacturer
   • Блог OCTemplates: oct_blogarticle, oct_blogarticle_image
2. Извлекает пути изображений (например, catalog/product.jpg) из полей image.
3. Парсит HTML в описаниях:
   • Поля: information_description, product_description, oct_blogarticle_description
   • Ищет <img src="catalog/..."> и href="catalog/..." с помощью preg_match_all
   • Также ищет пути вида image/catalog/...
4. Убирает дубликаты и нормализует пути (см. выше).
5. Сравнивает с файлами в /image/catalog/ с помощью RecursiveIteratorIterator.

Белый список

• Файлы, которые нельзя удалять: catalog/placeholder.png, catalog/no_image.png

• Логотип магазина проверяется так:

  $query_logo = $this->db->query(
   "SELECT value FROM oc_setting WHERE key = 'config_logo' AND store_id = 0 LIMIT 1"
  );

   

  • Логотип добавляется в белый список, если он существует.

Удаление

• Проверяет права файла: is_writable
• Удаляет через unlink
• Статус:
  • ✅ — успешно
  • ❌ — ошибка

Безопасность

• Использует user_token для защиты от CSRF

• Проверяет существование таблиц перед запросами:

  $check = $this->db->query("SHOW TABLES LIKE '" . DB_PREFIX . "table'");

   

  • Игнорирует пустые описания и несуществующие папки

Требования

• ocStore/OpenCart 3.0.3.7
• PHP 7.3 или выше
• Папка /image/catalog/ с правами на чтение и запись
• Необходимые таблицы в базе данных

Команды

• Сканирование: tool/image_cleaner?action=scan&user_token=...
• Удаление: tool/image_cleaner?action=delete&user_token=...

Автор

• webitproff — GitHub
• Дата: 12 октября 2025
• Проект: oc-image_cleaner

Лицензия

BSD License

Поддержка и вклад

• Создавайте issue: GitHub Issues
• Pull request приветствуются

Как работает модуль?

Модуль ищет файлы в папке catalog (место, где хранятся картинки для товаров, категорий, баннеров и т.д.). Он проверяет, используются ли эти файлы на сайте (например, в товарах, статьях или настройках). Если файл нигде не нужен, скрипт может его удалить, а заодно убрать пустые папки, где эти файлы лежали.

Важно: Скрипт работает с любыми файлами в папке catalog (не только с картинками, такими как .jpg или .png, но и с любыми другими файлами, например, .pdf, .txt, или чем угодно ещё). Однако на практике в папке catalog обычно хранятся только картинки, так как это стандартная папка для изображений в ocStore.

Как он работает?

1. Где ищет файлы?
   • Скрипт заходит в папку catalog, которая обычно находится по пути вроде /путь_к_сайту/image/catalog/.
   • Если этой папки нет, он выдаёт сообщение: "Папка catalog не найдена, я не могу ничего сделать!" — и останавливается.
2. Как проверяет, нужен ли файл?
   • Скрипт собирает список используемых файлов (в основном это картинки), которые упомянуты на сайте. Он смотрит в базе данных (это как таблица с данными сайта) и проверяет:
     • Картинки товаров (например, фото в карточке товара).
     • Картинки категорий (фото для разделов, типа "Одежда").
     • Картинки баннеров, производителей и блогов (если они есть).
     • Также он ищет ссылки на файлы в текстах (например, в описании товаров или статей), где могут быть указаны пути вроде <img src="catalog/photo.jpg"> или <a href="catalog/file.pdf">.
   • Все найденные пути (например, catalog/photo.jpg или catalog/file.pdf) он записывает в список "нужных".
   • Есть ещё белый список — файлы, которые удалять нельзя:
     • catalog/placeholder.png и catalog/no_image.png (это стандартные заглушки, типа "нет картинки").
     • Логотип сайта (например, catalog/logo.png), если он указан в настройках.
3. Как находит ненужные файлы?
   • Скрипт проходит по всем файлам в папке catalog и её подпапках. Это как если бы ты открыл папку на компьютере и посмотрел всё, что там есть: картинки, документы, видео — любые файлы.
   • Для каждого файла он проверяет:
     • Есть ли его путь в списке "нужных" (из базы данных или текстов)?
     • Входит ли файл в белый список (заглушки или логотип)?
     • Если файл не в списке нужных и не в белом списке, он считается ненужным.
4. Удаляет только картинки или любые файлы?
   • Ответ: Скрипт может удалить любой файл в папке catalog, если он не используется на сайте и не входит в белый список. Это значит, что он удаляет не только картинки (.jpg, .png, .gif), но и любые другие файлы, например, .pdf, .txt, .mp4, если они там есть.
   • Но в реальной жизни в папке catalog обычно лежат только картинки, потому что это стандартная папка для изображений в ocStore. Если туда кто-то закинул не картинку (например, catalog/document.pdf), скрипт всё равно проверит и, если этот файл не нужен, может его удалить.
5. Как удаляет ненужные файлы?
   • Если ты выбрал режим "просто проверить":
     • Скрипт составляет список ненужных файлов (например, catalog/photo.jpg, catalog/random.txt) и показывает его тебе, ничего не удаляя.
   • Если ты выбрал режим "удалить":
     • Скрипт пытается удалить ненужные файлы. Перед этим он проверяет, можно ли удалить файл (есть ли права на удаление).
     • Если файл удалён успешно, его путь добавляется в список "удалённых".
     • Если удалить не получилось (например, файл защищён от удаления), скрипт просто пропускает его.
6. Что с папками?
   • Если ты выбрал режим удаления, после удаления ненужных файлов скрипт проверяет все подпапки в catalog.
   • Если какая-то подпапка осталась пустой (в ней больше нет файлов), он её удаляет. Это как уборка: если папка пустая, зачем её держать?

Какие файлы и папки трогает?

• Папка:
  • Скрипт работает только с папкой catalog (обычно это /путь_к_сайту/image/catalog/) и всеми её подпапками (например, catalog/banners/, catalog/products/).
  • В режиме удаления он может удалить пустые подпапки в catalog.
• Файлы:
  • Скрипт проверяет все файлы в папке catalog и её подпапках. Это могут быть:
    • Картинки (.jpg, .png, .gif и т.д.).
    • Любые другие файлы (.pdf, .txt, .mp4, .zip и т.д.), если они там есть.
  • Исключения (файлы, которые он не удаляет):
    • catalog/placeholder.png и catalog/no_image.png (заглушки).
    • Логотип сайта (например, catalog/logo.png), если он указан в настройках.
  • Все остальные файлы, которые не используются на сайте (не упоминаются в базе данных или текстах), считаются ненужными и могут быть удалены.

Пример, как это выглядит

Допустим, у тебя есть папка catalog:

catalog/
 photo1.jpg
 document.pdf
 banners/
 banner1.jpg
 random.txt

• Скрипт проверяет базу данных и тексты. Допустим, он нашёл, что photo1.jpg и banner1.jpg используются на сайте (например, в товаре или баннере).
• document.pdf и random.txt нигде не упоминаются.
• Если ты выбрал "просто проверить", скрипт покажет: "Ненужные файлы: catalog/document.pdf, catalog/banners/random.txt".
• Если ты выбрал "удалить":
  • Он попробует удалить document.pdf и random.txt (если они не защищены).
  • Если в папке banners больше ничего не осталось, он удалит и эту папку.

Удаляет только картинки или любые файлы?

• Скрипт проверяет и может удалить любые файлы в папке catalog и её подпапках, если они не используются на сайте и не в белом списке. Это не ограничено только картинками — он удалит всё, что не нужно (например, .pdf, .txt, .mp4).
• Но в реальной жизни в папке catalog обычно лежат только картинки, потому что она предназначена для них. Если там есть другие файлы, они тоже будут проверены и могут быть удалены.

Что важно знать?

• Скрипт аккуратный: он не удалит файл, если он нужен сайту или защищён от удаления.
• Он работает только с папкой catalog и её подпапками, ничего другого не трогает.
• Если ты просто проверяешь, он только покажет список ненужных файлов, ничего не удаляя.
• Если папка catalog не найдена, он выдаст ошибку и остановится.