mediaFal
Virtual folders, usage tracking and stable URLs for media files
Organization: ORG. TEND d.o.o.
Creator: Uroš Likar (theuros)
Screenshots
About mediaFal
A file abstraction layer media source for MODX 3. Each file is stored once on a fixed path, editors organise files in virtual folders, so renaming or moving never breaks links. Tracks where every file is used, protects used files from deletion, keeps alt/title per language and adds a media library, resource attachments, a multi-file TV with crop and migration with 301 redirects.
Information
Released
November 17, 2026
Supported Database
MySQL
License
GPLv2
Instructions
Requirements: MODX 3.0+, PHP 8.1+, GD or Imagick (Imagick recommended).
Installation
Install through Package Management. On the first install a form offers (all checked by default):
- create a FAL media source Images (
assets/media/images/) and Files (assets/media/files/), - make the Images source the default media source,
- hide
assets/media/in the core Filesystem source (recommended), so nobody uploads past mediaFal.
After installation
- Cron: add a nightly job for the full usage scan and trash clean-up:
php core/components/mediafal/cli/scan.php. Without cron, run Extras > mediaFal: scan usage from time to time. - Media sources: set the media source of your TVs, ContentBlocks fields and rich text editors to a FAL source.
- Existing files: Media > Migration to mediaFal moves them into a FAL source, rewrites the links in content and TVs and adds 301 redirects.
- Attachments: enable the tab per template (template tab Attachment groups).
- Output:
[[falFiles]]lists the attachments of the current resource;[[falFiles? &filter=`images`]]shows images only.
Test on a copy of your site first and keep a backup of the database and the assets/ folder.
Full documentation: https://modx.tend.si/mediafal/
New in 1.0.0-beta3
New
- File metadata API for other extras (Image+, Agenda …):
getFileMeta(),hasFileMeta()andsetFileMeta($path, $meta, $culture, $overwrite)on the FAL media source. The path can be the source path, the URL or a full URL. - Event
OnMediaFalFileMovedfires when a file URL is renamed or the migration rewrites references, so extras with their own tables can update their stored paths. - The crop window, the
falfileTV and the “Edit metadata” window now use the standard MODX manager style.
Fixes
- Uninstall converts FAL media sources to file system sources on the same folder, so links, TVs and
default_media_sourcekeep working. Installing mediaFal again switches them back. - Uploads: two concurrent uploads of the same file no longer create a duplicate, and a file is removed from disk again if it cannot be added to the index.
- Blocked extensions: executable extensions (
php3–php8,phtml,phar,asp,jsp,shtml…) are always blocked. - Trash: a file that content still references cannot be deleted permanently from the trash.
- Upload folders: two resources with the same aliases in different contexts no longer share or take over an upload folder.
- Migration: reserved old paths are resolved through symlinks, and “Finish” never moves a live FAL file.
- Performance: faster 301 lookup for missing files and faster folder binding on upgrade.
- Permissions:
- Attachments and file details only show files from sources the user may list.
- Attachment groups are validated.
- The template tab checks the template's access policy.
Full changelog and documentation: modx.tend.si/mediafal