MediaWiki extensions manual
Release status: stable
Implementation File repository
Description Adds some virtual paths to file URLs, so they can be cached more efficiently
Author(s) Jesús Martínez (Ciencia Al Podertalk)
Latest version 1.2.0
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.35+
License GNU General Public License 2.0

The WikiDexFileRepository extension creates a custom file repository that adds some virtual paths to file URLs, so they can be cached more efficiently (generating sort of permanent URLs), and change when a new version of the file is uploaded (using the file timestamp).

This extension requires custom rewrite rules on the web server to work.

Typical URL of image: http://mycdn/mwuploads/wikisite1/thumb/a/ab/Example.png/200px-Example.png

URL of image with this extension: http://mycdn/mwuploads/wikisite1/thumb/a/ab/latest/20161231182410/Example.png/200px-Example.png


  • Download and place the file(s) in a directory called WikiDexFileRepository in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file:
    wfLoadExtension( 'WikiDexFileRepository' );
    $wgLocalFileRepo = [
        'class' => 'LocalWikiDexRepo',
        'name' => 'local',
        'directory' => $wgUploadDirectory,
        'url' => $wgUploadBaseUrl ? $wgUploadBaseUrl . $wgUploadPath : $wgUploadPath,
        'hashLevels' => 2,
        'thumbScriptUrl' => $wgThumbnailScriptPath,
        'transformVia404' => true,
        'deletedDir' => $wgDeletedDirectory,
        'deletedHashLevels' => 3
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Web Server


Configuration needed on the webserver to translate the URLs generated by the extension to actual file paths.



Rules for nginx.

Images are served from http://mycdn/mwuploads/wikisite1/ to allow for multiple MediaWiki installations on the same domain.

map $mwuploads_longcache $mwuploads_expire {
    default 5m;
    1 30d;

map $uri $images_thumbfallback {
    default @404;
    "~/mwuploads/wikisite1/" @thumb;
    "~/mwuploads/wikisite2/" @thumb;

map $uri $images_mwinstallpath {
    default "/dev/null";
    "~/mwuploads/wikisite1/" "/home/www/wikisite1/mediawiki-1.29.0";
    "~/mwuploads/wikisite2/" "/home/www/wikisite2/mediawiki-1.29.0";

map $request_uri $thumbfile {
    default "xx";
    "~/mwuploads/[a-z0-9]+/thumb/[0-9a-f]/[0-9a-f][0-9a-f]/latest/[0-9]+/(?<xthumbfile>[^/]+)/[0-9]+px-.*$" "$xthumbfile";
    "~/mwuploads/[a-z0-9]+/thumb/[0-9a-f]/[0-9a-f][0-9a-f]/(?<xthumbfile>[^/]+)/[0-9]+px-.*$" "$xthumbfile";
        "~/mwuploads/[a-z0-9]+/thumb/archive/[0-9a-f]/[0-9a-f][0-9a-f]/(?<xthumbfile>[^/]+)/[0-9]+px-.*$" "$xthumbfile";

server {
    location /mwuploads/ {
        alias /data/mwuploads/public/;
        expires $mwuploads_expire;

        # Image with /latest/timestamp/, gets rewritten, long expires
        location ~ "^/mwuploads/[a-z0-9]+/(?:thumb/)?[0-9a-f]/[0-9a-f][0-9a-f]/latest/[0-9]+/.*$" {
            set $mwuploads_longcache 1;
            expires $mwuploads_expire;
            rewrite "^/mwuploads/(?<startpath>[a-z0-9]+/(?:thumb/)?[0-9a-f]/[0-9a-f][0-9a-f]/)latest/[0-9]+/(?<endpath>.*)$" "/mwuploads/$startpath$endpath";

        # Direct file in /archive, long expires
        location ~ "^/mwuploads/[a-z0-9]+/archive" {
            set $mwuploads_longcache 1;
            expires $mwuploads_expire;
        # Thumb image
        # Warning: Regexp variables are used in @thumb
        location ~ "^/mwuploads/[a-z0-9]+/thumb/[0-9a-f]/[0-9a-f][0-9a-f]/[^/]+/(page(?<thumbpage>\d+)-)?(?<thumbwidth>[0-9]+)px-.*$" {
            set $thumbarchived 0;
            expires $mwuploads_expire;
            try_files $uri $images_thumbfallback;
        # Thumb image from archive
        location ~ "^/mwuploads/[a-z0-9]+/thumb/archive/[0-9a-f]/[0-9a-f][0-9a-f]/[^/]+/(page(?<thumbpage>\d+)-)?(?<thumbwidth>[0-9]+)px-.*$" {
            set $mwuploads_longcache 1;
            set $thumbarchived 1;
            expires $mwuploads_expire;
            try_files $uri $images_thumbfallback;

    location @thumb {
        expires $mwuploads_expire;
        # Run the thumb.php script
        include /etc/nginx/fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $images_mwinstallpath/thumb.php;
        fastcgi_param QUERY_STRING f=$thumbfile&width=$thumbwidth&p=$thumbpage&archived=$thumbarchived;
        fastcgi_pass unix:/run/php/php-fpm.sock;

    location @404 {
        return 404;

    location / {
        return 404;