# FlowFiles Documentation *By James Hills — Updated October 2026* FlowFiles is a fast, two-pane file manager for Joomla administrators. Move folders, edit config files and clean up uploads without leaving the admin or reaching for FTP. This page explains how to install it, who can use it, what each part does and what to do when something goes wrong. ## Requirements - Joomla 5 (the component is built for the Joomla 5 administrator and styled to match the Atum template). - A web server that honors `.htaccess` access rules, such as LiteSpeed Enterprise or Apache with `AllowOverride`. See "Server Requirement for the Trash and Backups" below. - A filesystem that allows hard links. Backups and Trash restores depend on them. ## Install and Update FlowFiles installs as one package, `pkg_flowfiles`. The package contains the file manager, the Space and Logs add-ons and a scheduled task that runs add-on jobs. Updating the package updates all of them. 1. In the Joomla administrator, open System, then Install, then Extensions. 2. Upload the `pkg_flowfiles` package. 3. Open Components, then FlowFiles. If you installed FlowFiles, Space and Logs separately on an older version, install the package over them. Your Trash, Space scans, add-on on/off choices and the download key you already entered are kept. The package carries the update stream and the download key, so Joomla's normal Update screen offers new versions once the key is entered. ## Who Can Use It Everything in FlowFiles, including browsing, requires the **core.admin** permission on the FlowFiles component. There is one level of access, not two. The reason is that writing into the site folder can plant executable code, and reading it can expose `configuration.php`, which holds the database password and the site secret. Neither is a lesser privilege than the other. **Granting the Full File Access permission is equivalent to granting Super User.** You can delegate it to any group from the Permissions tab in the FlowFiles options. Do not grant it to anyone you would not make a Super User. ## A Tour of the Main Tasks ### Browse The left pane is a folder tree that loads as you open it. The right pane shows the folder listing, or a preview when you select an image. The splitter between them can be resized or collapsed. Breadcrumbs show where you are. - Select with the mouse, with the keyboard, with Shift-click and Ctrl-click ranges, or with the checkbox on every row. The header checkbox selects every loaded row. - Large folders load 200 items at a time (adjustable in the settings). Use Load more in the list or the tree to reach the rest. Folders of up to 100,000 entries are read and sorted as a whole. - Search this folder is a case-insensitive name search across the whole folder, not just the rows already loaded. - Go to path accepts a path or a full URL such as `https://example.com/images/stories/photo.jpg`. If the path names a file, FlowFiles opens its folder and searches down to that file. - Sort by Name, Size, Modified or Permissions, in either direction, and filter by type. Both run across the whole folder and are remembered. ### Move and Copy Drag items to move them, or Ctrl-drag to copy. You can also use Move to... and Copy to... from any row's menu and type the destination folder. FlowFiles checks that the folder exists and is not where the item already is. ### Edit Files Text files open in a code editor with syntax highlighting. This includes `.htaccess`, `.ini`, `.conf`, `.env` and files with no extension such as `error_log` and `README`. Line endings are preserved exactly. - Save with the Save button or Ctrl/Cmd+S. If you try to leave with unsaved changes, FlowFiles asks first. - When you open a file the server runs (PHP, `.htaccess`), a warning banner appears. You can turn this off in the settings. - Saving a `.php` file checks it first. If PHP finds a syntax error, the file is not saved, the editor shows PHP's message and the line number, and the file on the site stays as it was. Save anyway is available and is logged. - A status line shows line and column, language, encoding and line endings. - Files larger than the editable size limit open in a read-only viewer instead (see Large Files and Logs). ### Upload Use the Upload button or drop files from your computer onto the pane. A visible drop zone shows where they will land. An existing file is replaced only if you explicitly choose to overwrite it. ### Create, Rename and Properties New folder and Rename are on the toolbar and the row menu. Properties shows any item's folder, type, exact size, image dimensions, dates and permissions in words, for example "0664 - owner and group can write". ### Delete and the Trash Delete does not destroy anything straight away. Files and folders move into the Trash, and an Undo link appears in the notice. A bulk delete is one batch, so one Undo puts everything back. - The Trash page lists each item with where it came from, who trashed it and when. It has search, sorting, Restore and Delete forever for the items you select, and Empty Trash. - Restore never overwrites. If the original path is taken again, the item comes back as `name (restored)` beside it. - Items are deleted forever after the number of days set in the options (30 by default). - Only Delete forever and Empty Trash destroy anything. ### Work on Many Files at Once Select files and folders, or choose "Select all N in this folder", and move them to the Trash together. Before anything moves, FlowFiles shows how many items, how large, where, and which items are site code (`.php` files, Joomla's own folders and `configuration.php`). If site code is included, you must tick "I understand this includes site code" before the button works. Large selections move in steps. If a step fails, the rest stays where it is, and "Trash the remaining" picks up exactly what is left. ### Large Files and Logs A file above the editable size limit opens in a viewer that shows one window at a time, newest end first, and pages by position in the file. A multi-gigabyte `error_log` opens in under a second. The viewer is read-only and refuses binary files. The Shrink dialog makes a file smaller. Each choice says what the file becomes and what is removed for good. You can keep only the end of the file or empty it. For a Joomla log, the protective header at the top is always kept. Shrinking is crash-safe: if the request is interrupted, the original file is untouched. ### Site Tools Tools that cover the whole site sit in a "Site tools" row above the file list: Findings, Space, Logs, Trash, Backups and Add-ons. Each has its own full page with a Back to files button. They also appear under Components, then FlowFiles, in the Joomla admin menu. - **Space** answers "what is using my disk". It scans a folder and reports where the space is, the largest files, a breakdown by type and by age. Results older than 7 days are shown in amber. "Analyze this folder" on the toolbar opens a quick summary for the current folder. From the Space page you can Show in folder, Download or Move to Trash on the largest files. - **Logs** understands log files: their size and share of all logs, a "View newest entries" view, and Shrink options such as "Keep the last 7 days", "Keep only the newest entries" and "Start a fresh log". "Back up first" saves a copy before shrinking. - **Findings** lists things worth a look, such as large files, leftovers, duplicates and logs that grew. Each card has Show in FlowFiles, Select these and Move to Trash. A finding you dismiss stays away until it grows by more than a fifth, becomes more serious or something new is found. Findings stays hidden until an add-on that finds things is switched on. - **Backups** lists the copies FlowFiles has made, with Download, Restore as a copy and Delete. Restore as a copy always creates a new file next to the original and never overwrites the current file. - **Add-ons** shows installed add-ons with their version and state, and lets you switch them on or off. ## Settings Open Components, then FlowFiles, then Options. | Setting | Default | What it does | | --- | --- | --- | | Managed root | Site root | Which folder tree FlowFiles may reach. Choose "Images folder only" to limit it to the images folder. Nothing outside the chosen root is reachable. | | Maximum upload size (MB) | 16 | Larger uploads are refused. PHP's own upload limits still apply on top. Range 1 to 512. | | Maximum editable file size (KB) | 2048 | Larger files open in the read-only viewer instead of the editor. Range 1 to 16384. | | Keep trashed items (days) | 30 | Trashed items are deleted forever after this many days. 0 keeps them until you empty the Trash. | | Keep backups for (days) | 30 | Older backups are deleted. 0 keeps them until you delete them. | | Most space backups may use (MB) | 1024 | When backups pass this total, the oldest are removed first, and each removal is logged. A single backup larger than the limit is refused. 0 means no limit beyond free disk space. | | Items per page | 200 | How many items load at a time. Range 25 to 1000. | | Warn on executable files | Yes | Shows a warning when you open a file the server runs, such as PHP or `.htaccess`. | The Permissions tab controls who has access. See "Who Can Use It". ## Safety Notes ### What FlowFiles Stays Inside Every path is confined to the managed root. Folder-traversal tricks such as `../` are discarded, and the final location is verified on disk, including through symbolic links. A link that points outside the root is refused. The Trash, the Backups folder and, where it is used, the FlowDB snapshot folder are protected stores. FlowFiles never lists, reads, downloads or moves anything inside them through the file list. FlowFiles has no blocklist of file types. It exists partly to edit `.php` and `.htaccess`, so access is controlled by Joomla permissions alone. ### Server Requirement for the Trash and Backups The Trash (`administrator/flowfiles-trash`) and Backups (`administrator/flowfiles-backups`) are kept from the web by a deny-all `.htaccess`, an `index.html` and random, extensionless file names. That works on LiteSpeed Enterprise and on Apache with `AllowOverride`. OpenLiteSpeed ignores `.htaccess` access rules. On OpenLiteSpeed, nginx or any other server that ignores them, deny both folders in the server's own configuration, or files in them can be downloaded. ### Backups Backups are never stored beside the original. They go to `administrator/flowfiles-backups`. Each records the file it came from, who made it, its size and when. Before making a copy, FlowFiles checks free disk space and refuses if the copy would leave too little. Only one copy of a given file is made at a time. Old copies that earlier versions left beside logs can be found and moved into Backups with one click. ### The Audit Log Every change, every refused operation and every read is written to Joomla's log. Joomla's default log folder, `administrator/logs/`, is inside the site root. With the Managed root set to Site root, the log can be browsed, edited and deleted through FlowFiles itself, by the same people it records. It is good for reconstructing what happened, but it is not evidence against a hostile administrator. If you need that, set `log_path` in Joomla's Global Configuration to a folder outside the web root. ### Confirmations Questions such as move, copy, rename, delete forever, emptying the Trash, replacing on upload and discarding changes are asked in FlowFiles' own dialog. The dialog says what will happen and to how many items. ## The Review Queue An AI agent connected to your site can find files worth cleaning up and propose them to FlowFiles instead of just listing them in a chat. The proposal appears on a Review page under Site tools. The tab shows a count, for example "Review 2", when something is waiting. The page stays hidden until something has been proposed once. - Each proposal shows who proposed it, why, how many items and how large, and when it expires. - Open a proposal to see every row with its size, date and the agent's reason, with Show in folder and Download on each row. - Rows start ticked. A row whose file has changed since it was proposed, or that no longer exists, is flagged and starts unticked. - Untick anything you want to keep, then click Go. Go runs the normal Move to Trash with Undo. Site code needs the same "I understand" tick as an ordinary bulk Trash. You can also Reject a proposal and leave a note the agent can read. - The agent never moves anything. Only your click does. - FlowFiles measures size and date itself and does not trust the agent's numbers. - Proposals nobody decides within 14 days expire. Decided, withdrawn or expired proposals are deleted after 90 days. Only users who can use FlowFiles can act on a proposal. ## Troubleshooting and FAQ ### The Screen Looks Unchanged After an Update Hard-refresh the page (Ctrl+F5). Since version 0.10.1 each script and stylesheet carries the component version in its address, so an update should reach the browser, but a cached tab can still hold the old one. ### Why Is the Edit Button Replaced by View? The file is larger than the "Maximum editable file size" setting, or it is a type the editor does not handle. The viewer is read-only. Raise the limit in the options if you need to edit it. ### My PHP File Will Not Save PHP found a syntax error. The message names the line, and the file on the site is unchanged. Fix the error, or use Save anyway if you are sure. ### An Upload Is Refused Check the "Maximum upload size" option. PHP's `upload_max_filesize` and `post_max_size` limits apply on top of it. If the file already exists, you must choose to overwrite it. ### I Deleted Something by Mistake Click Undo in the notice, or open the Trash and Restore it. If the original path has been taken again, the item returns as `name (restored)`. ### Deleting Did Not Free Any Disk Space Trashed items still use space. Space is freed when an item leaves the Trash, either by Delete forever, Empty Trash or the automatic clean-up after the configured number of days. ### Making a Backup Fails With a Permissions Message Backups use hard links. On a filesystem that refuses them, "back up first" cannot work. Ask your host whether hard links are allowed. ### The Findings or Review Tab Is Missing Both are hidden until they have something to show. Findings appears once an add-on that finds things is switched on. Review appears after the first proposal. ### A Link to a Tool Opens FlowFiles With a Note The tool's add-on is switched off. Open the Add-ons page and switch it on. ### Is FlowFiles Safe for My Editors? No. It gives Super User level reach. Keep access to people you would trust with the whole site. ## License FlowFiles is released under the GNU General Public License version 3 or later. Its path-containment algorithm derives from eXtplorer 3 by Soeren Eberhardt-Biermann (MIT license). Details Written by: James Hills Last Updated: 30 October 2026 Hits: 10 ### Latest News Updates: ### Download Our "Content Marketing For Travel Advisors" Ebook! #### Stop Reading Spec Sheets. Start Thinking About Infrastructure Independence [Stop Reading Spec Sheets. Start Thinking About Infrastructure Independence](https://flowmediamarketing.com/blog/stop-reading-spec-sheets-start-thinking-about-infrastructure-independence.html) #### Who Programs Your Agent's Taste? Why Brand Marketing Matters More in an Agentic Future [Who Programs Your Agent's Taste? Why Brand Marketing Matters More in an Agentic Future](https://flowmediamarketing.com/blog/who-programs-your-agents-taste-why-brand-marketing-matters-more-in-an-agentic-future.html) #### The Cruise Industry's Mega-Ship Bet Makes Perfect Sense - If You Understand Gen Z [The Cruise Industry's Mega-Ship Bet Makes Perfect Sense - If You Understand Gen Z](https://flowmediamarketing.com/blog/cruise-industry-mega-ship-bet-makes-perfect-sense-if-you-understand-gen-z.html) #### How I Turned My UGREEN NAS Into a Dev Server for Vibe Coding (And Stopped Breaking Production) [How I Turned My UGREEN NAS Into a Dev Server for Vibe Coding (And Stopped Breaking Production)](https://flowmediamarketing.com/blog/how-i-turned-my-ugreen-nas-into-a-dev-server-for-vibe-coding-and-stopped-breaking-production.html) - - Flow Media Marketing is based in Southwest Michigan. Learn More About Our People and Brands: - [James Hills](https://flowmediamarketing.com/james-hills.html) - [Heather Hills](https://flowmediamarketing.com/heather-hills.html) - [Flow Media Marketing](https://flowmediamarketing.com/flow-media-marketing.html) - [Flow Voyages](https://flowmediamarketing.com/flow-voyages.html) - [Cruise West Coast](https://flowmediamarketing.com/cruise-west-coast.html) - [Couple Places](https://flowmediamarketing.com/couple-places.html) - [MenWhoBlog](https://flowmediamarketing.com/menwhoblog.html) - [ManTripping](https://flowmediamarketing.com/mantripping.html) - [The Grape Stomp](https://flowmediamarketing.com/the-grape-stomp.html) --- *Source: [FlowFiles Documentation](https://flowmediamarketing.com/flowfiles-documentation.html)*