.. _usage: ===== Usage ===== .. contents:: :local: :depth: 1 .. _usage-mimefix: MIME Fix inside the file list ============================= No separate module to learn. A :guilabel:`Scan MIME` button is injected into the toolbar of the TYPO3 :guilabel:`File > Filelist` module for the folder you are viewing. It reports every file in that folder where: * the **actual file content** does not match what the **extension** claims it is (``finfo`` vs. extension), or * the **database** :sql:`mime_type` is out of sync with what it should be. Supported types: ``jpg``, ``jpeg``, ``png``, ``gif``, ``webp``, ``bmp``, ``tiff``/``tif``, plus the text-based ``css``, ``js``, ``yaml``/``yml`` and ``dotx``. .. list-table:: How fixing works :header-rows: 1 :widths: 40 60 * - Situation - What happens * - Image content does not match extension (for example a PNG saved as :file:`.jpg`) - Converted in place via ImageMagick / GraphicsMagick, written to a temp file first so a failed conversion never corrupts the original. * - Photoshop file (:file:`.psd` content, wrong extension) - Converted via the PHP ``Imagick`` extension if available; falls back to ImageMagick ``convert``, reading only the merged/composite layer. * - ``css`` / ``js`` / ``yaml`` / ``yml`` / ``dotx`` - ``finfo`` cannot detect these correctly, so only the :sql:`sys_file.mime_type` record is corrected. Select the issues, click :guilabel:`Fix selected`. The FAL index is re-read afterwards so TYPO3 immediately reflects the corrected type. .. _usage-cleanup: File Cleanup ============ :guilabel:`File > File Cleanup`. For when you trust the result and want the files gone. * Lists files with **zero active** :sql:`sys_file_reference` and **zero soft references** (:sql:`sys_refindex`), that is, unreferenced by any page, content element or FlexForm. * Filter by :guilabel:`Present on disk` / :guilabel:`Physically missing` / :guilabel:`All`, by extension and by folder depth (level 1 to 3, or unlimited). * :guilabel:`Download as ZIP` before deleting, per-file download links and per-row "physically missing" badges. * :guilabel:`Delete selected` or :guilabel:`Delete all filtered`. The bulk delete requires typing the exact file count to confirm. * Uses the file storage tree on the left, the same as the file list. .. warning:: File Cleanup deletes physical files **and** their :sql:`sys_file` / :sql:`sys_file_reference` rows immediately. There is no undo. Double-check your filters before running a bulk delete. .. _usage-duplicates: Duplicate report ================ :guilabel:`File > Filelist` → :guilabel:`Find duplicates` button in the toolbar (admins only). Lists every group of files in the storage with identical content (same :sql:`sys_file.sha1`) where at least one copy lies in the current folder or below; the other copies are looked up in the whole storage. * **Only real copies count.** Each copy is checked on disk and sizes are read from disk; :sql:`sys_file.missing` and :sql:`sys_file.size` are not trusted. Records whose file is gone are left out and counted in the summary. Several :sql:`sys_file` records pointing to the same path count as one copy (their usages are added up). * **Sorted by wasted space** (``(copies − 1) × size``), 25 groups per page, with lazy-loaded thumbnails. * **Per copy:** path, file-level metadata (title, alternative, description), number of file references and soft references (for example ``t3://file`` links in RTE fields). Click the usage count to see each reference with edit links that return to the report. * **Suggested keeper** (star icon): the copy with the most usages, then the oldest one. * **Badges** when copies carry different file-level metadata or when soft references exist. * **CSV export** of the folder's groups: one row per file reference (or per copy without references). .. _usage-duplicates-deepcheck: Deep check and delete --------------------- Each copy has a :guilabel:`Deep check` that searches the whole database live for usages of that one file: #. :sql:`sys_file_reference` (every workspace and language), #. the reference index :sql:`sys_refindex` (relation fields, links in RTE/link fields, form definitions), #. a text search in every string/text/JSON column of every table for the public path (also URL-encoded), the combined identifier (``1:/path/file.jpg``), ``t3://file?uid=N`` and the legacy ``file:N`` syntax, exact-matched, #. other :sql:`sys_file` records indexing the same physical file. Technical tables (caches, logs, history, ``sys_file*``, :sql:`sys_refindex`, sessions, ``tx_filefix_*``) are skipped and listed. Usages by deleted records are shown but do not block deletion. Text matches stop at 50. Only when the check finds **zero active usages** does a :guilabel:`Delete file` button appear. After a second confirmation the server runs the deep check **again** and refuses (HTTP 409) if the file is in use. Deletion goes through FAL (physical file, :sql:`sys_file`, metadata, processed files) and is written to :sql:`tx_filefix_log` as ``delete_duplicate``. The report itself is read-only; nothing is merged or re-linked automatically. .. _usage-oversized: Oversized images ================ :guilabel:`File > Filelist` → :guilabel:`Oversized images` button in the toolbar (admins only). Lists images in the current folder (subfolders optional) whose width or height exceeds the configured maximum, with the estimated saving if resized to fit. * Maximum width/height from the :ref:`extension configuration ` (default 1900 × 1900 px). Checked types: ``jpg``, ``jpeg``, ``jfif``, ``png``, ``webp``, ``tif``, ``tiff``, ``bmp`` (``gif`` is left out because it may be animated). Max width/height and :guilabel:`Include subfolders` can be changed in the report for that view only. * Dimensions come from :sql:`sys_file_metadata`; files are checked on disk and sizes read from disk. Images missing on disk or without known dimensions are left out and counted in the summary. * **Estimated saving** = ``size × (new pixels / old pixels)``. Sorted by largest saving, 25 per page. .. _usage-oversized-resize: Resize ------ #. :guilabel:`Dry run`: the image is converted on the server, the result is measured and discarded. A modal shows before/after dimensions and size. #. :guilabel:`Resize now`: the server checks the file again and replaces it via FAL ``replaceFile()``. * **Same file name, same** :sql:`sys_file` **uid, same format**: references, crops and links keep working. ``size``, ``sha1`` and dimensions are updated; processed files are regenerated. * Resizes to the limits from the extension configuration (not the values typed into the report form), aspect ratio kept. JPEG quality follows :php:`$GLOBALS['TYPO3_CONF_VARS']['GFX']['jpg_quality']`. The embedded colour profile is always kept. * The result is only kept when it is at least **10 KB** smaller. * Refused for: types other than ``jpg``, ``jpeg``, ``png``; files indexed by more than one :sql:`sys_file` record; non-Local storage drivers; missing or non-writable files; images already within the limits. .. warning:: Resizing overwrites the original file. There is **no backup and no entry in** :sql:`tx_filefix_log`. Back up :file:`fileadmin` first if you may need the originals. .. _usage-dashboard: Dashboard widgets ================= Requires :composer:`typo3/cms-dashboard` (optional). Widget group :guilabel:`filefix` with four widgets: .. list-table:: :header-rows: 1 :widths: 30 70 * - Widget - Shows * - Unused files - Number of unused files on disk * - Reclaimable space - Disk space deleting them would free (for example ``6.4 GB``) * - Unused files by type - Doughnut chart by extension * - Unused space by type - Same chart, by size Each physical file is counted once, only when **all** its :sql:`sys_file` records are unused, only when it exists on disk, with its size read from disk. The result is cached in :sql:`sys_registry` (namespace ``tx_filefix``, key ``stats.storage.``) and rebuilt when older than **1 hour**, or on demand via the schedulable :ref:`filefix:stats:update ` command. Widgets use the default storage.