mediaFal

Virtual folders, usage tracking and stable URLs for media files

Organization: ORG. TEND d.o.o.
Creator: Uroš Likar (theuros)

Need help installing this extra?

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

Supported Versions
3.0 - Current

Downloads
5

Documentation
mediaFal Documentation

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() and setFileMeta($path, $meta, $culture, $overwrite) on the FAL media source. The path can be the source path, the URL or a full URL.
  • Event OnMediaFalFileMoved fires 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 falfile TV 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_source keep 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

Current releases

1.0.0-beta3
View | Download
November 17, 2026
3.0 - Current

1.0.0-beta2
View | Download
November 10, 2026
3.0 - Current