Media in Joomla

1. The Basics

1.1 What Makes Media Different

The first thing to understand is that the Media Manager does not behave like the other components you may already know. The difference is fundamental:

The most important consequence: there is no #__media table. Your "media data" is simply the directory tree on disk. This single fact explains almost everything else in this article, including backups, search speed, and migration.

1.2 The Moving Parts

It helps to see the whole chain at once. From the screen you click on, down to the bytes on disk:

Media Manager UI (Vue single-page app)
   │  talks over REST / AJAX
   ▼
ApiModel  →  ProviderManager  →  Adapter  →  storage
                                    (local)      (images/ on disk)

• The UI is a single-page JavaScript (Vue) application in the backend.
• An Adapter knows how to read and write one storage backend.
• A Provider is a filesystem plugin that supplies one or more adapters.
• The Storage is where the bytes actually live. By default that is the images/ folder on your local disk.

Keep this picture in mind. When we reach the developer section, every part of it becomes a place you can extend.

1.3 Where to Find It

In the Joomla 6 backend, the Media Manager and its settings live in two places:

Content → Media                              (the manager itself)
System  → Global Configuration → Media       (the options)

The manager also appears embedded wherever a Media form field is used. The "Select" button next to an image field opens the very same manager inside a modal window. So most editors never open Content → Media directly - they meet it through the image button in their editor.

1.4 Two Roots: /images and /files

For years, Joomla surfaced a single images/ folder. Modern Joomla ships two roots, so that documents do not get mixed in with pictures:

The split is purely organisational: keep visitor-facing pictures in /images and downloadable documents in /files. Both folders live under the Joomla root.

1.5 Two Layers Configure Those Roots

This detail trips many people up, so it is worth slowing down. The roots are set in two different places, and they do two different jobs:

1. Local filesystem plugin  (plg_filesystem_local)
   param "directories" = [{"directory":"images"}, {"directory":"files"}]
   → each entry becomes a SEPARATE adapter (a top node in the tree)
   → each can have its own thumbnails toggle
   → add more here to expose extra folders (for example "downloads")

2. com_media Options  (System → Global Config → Media)
   image_path = images   ← which root image fields default to
   file_path  = files    ← the documents root

In short: the plugin decides which folders appear as adapters; the component options decide which one counts as "images" versus "files" for the pickers. Both are validated, and core directories such as administrator, libraries, and cache are excluded. You cannot point a root at them.

3. File Types: Images, Office, Audio, Video, and SVG

3.1 The Four Extension Lists

Beyond the master list of allowed uploads, the Options screen sorts extensions into four buckets. The bucket decides how the manager previews and handles a file once it is uploaded:

The rule to remember: an extension must be in Allowed to upload at all. The other three lists only decide how the file is displayed once it is there.

3.2 Audio and Video: MP3 and MP4 Just Work

The good news is that mp3 and mp4 are in the default whitelist and in the audio/video lists, so they work out of the box:

upload interview.mp3  → allowed → audio_extensions → inline <audio> player
upload promo.mp4      → allowed → video_extensions → inline <video> player

• Drop them in /files (or /images), pick them with a Media field, and they play in the preview.
• mp4 is listed as both audio and video - Joomla shows the appropriate player.
• Want webm, mov, or ogg? They are already in the audio/video lists, but you may need to add them to the Allowed list before you can upload them.

3.3 MS Office and OpenDocument: A Real Gotcha

Look closely at the defaults, because this one causes regular support tickets:

Out of the box you can upload an old .doc but not a modern .docx. The x formats are missing from both the extension whitelist and the MIME whitelist.

To allow modern Office documents you must add both the extension and the MIME type:

restrict_uploads_extensions:  …,docx,xlsx,pptx

upload_mime: add the OOXML MIME types, for example
  application/vnd.openxmlformats-officedocument.wordprocessingml.document     (docx)
  application/vnd.openxmlformats-officedocument.spreadsheetml.sheet           (xlsx)
  application/vnd.openxmlformats-officedocument.presentationml.presentation   (pptx)

If you add the extension but forget the MIME type, the Check MIME step rejects the upload. That is the classic "my docx will not upload" ticket.

3.4 SVG: Deliberately Blocked

The svg extension is not in any default list - not Allowed, not Image, and image/svg+xml is not in the MIME whitelist. This is on purpose, and it is worth understanding why:

An .svg file is XML. XML can contain:
   <script>…</script>            → stored XSS
   <a xlink:href="javascript:">   → script execution
   external entity references     → SSRF / data exfiltration

Because an SVG renders like an image but executes like a document, uploading one straight into your webroot is a stored cross-site-scripting (XSS) vector. Joomla blocks it by default.

If you genuinely need SVG (for example, a trusted icon set), enable it carefully:

1. Add  svg  to restrict_uploads_extensions  AND  image_extensions
2. Add  image/svg+xml  to upload_mime
3. Allow ONLY trusted groups to upload (use ACL - see Security)
4. Sanitise the SVGs (strip <script>, event handlers, external refs)
   before they reach the webroot

Treat enabling SVG the same way you would treat enabling custom HTML banners: it is control traded for safety. Restrict it to staff and sanitise the files.

3.5 Adding a New File Type: The Checklist

Whenever an upload is refused, walk through this list in order:

1. Is the extension in  restrict_uploads_extensions ?   (if not, it is blocked)
2. Is Check MIME on?  → the real MIME must be in  upload_mime
3. Want a thumbnail or the editor?  → add it to  image_extensions
4. Want a player?                   → add it to  audio_extensions / video_extensions
5. Is the file within  upload_maxsize  AND PHP's upload_max_filesize / post_max_size ?

The extension and the MIME type must both pass. Adding one without the other is the number-one cause of "it still will not upload".

5. The Adapter Architecture (The Clever Bit)

5.1 One UI, Pluggable Storage

The whole component is built around a single contract called AdapterInterface. It defines twelve methods:

getFile       getFiles      getResource
createFolder  createFile    updateFile
copy          move          delete
getUrl        search        getAdapterName

Implement those twelve methods and the entire Media Manager UI works against your storage: Amazon S3, Azure Blob, a digital asset manager (DAM), anything you like.

5.2 Providers Supply Adapters

An adapter does not appear by itself. A provider supplies it:

Filesystem plugin (provider)  →  one or more Adapters
plg_filesystem_local          →  LocalAdapter (one per configured root)

• A filesystem provider is a plugin in the filesystem group.
• Core ships exactly one: Local (plugins/filesystem/local).
• Its configuration lists the roots (such as images and files), and each root becomes a selectable adapter in the tree.

5.3 The ProviderManager

A small registry ties it all together:

ProviderManager
  ├─ registers every enabled filesystem plugin
  ├─ each plugin returns its adapter(s)
  └─ the UI lists them as  provider-adapter  nodes

An adapter is addressed as provider:adapter:/path, for example:

local-images:/headshots/peter.png
local-files:/contracts/2026.pdf

That provider-adapter prefix is how the UI and the API know which storage a path lives on.

5.4 Writing a Cloud Adapter (Concept)

To picture how extensible this is, here is the skeleton of an S3 adapter:

class S3Adapter implements AdapterInterface
{
    public function getFiles(string $path = '/'): array { /* list bucket */ }
    public function createFile(string $name, string $path, $data): string { /* putObject */ }
    public function getUrl(string $path): string { /* signed URL */ }
    // … the other nine methods
}

Wrap it in a filesystem plugin that returns the adapter, enable the plugin, and a new root appears in the manager - with zero changes to the UI. This is the single most important architectural idea in com_media: storage is a plugin.

7. Under the Hood (Developer View)

7.1 No Table, a Service Stack

Because there is no database table, the component is a stack of services and plugins:

administrator/components/com_media/
  src/Adapter/AdapterInterface.php      the 12-method contract
  src/Provider/ProviderManager.php      registers providers / adapters
  src/Model/ApiModel.php                CRUD orchestration
  src/Model/MediaModel.php              the SPA-backing model
  src/Controller/ApiController.php      AJAX endpoints for the Vue UI
  src/Controller/DisplayController.php  renders the SPA shell

plugins/filesystem/local/   the one core provider
  src/Adapter/LocalAdapter.php

plugins/media-action/        crop / resize / rotate
media/com_media/js/          media-manager.js + edit-images.js (Vue)

7.2 The Request Flow

When you open the manager, two things happen: first the page shell loads, then the JavaScript app takes over and talks to the API:

1. Content → Media
   → DisplayController renders the Vue SPA shell (one <div> + assets)

2. The Vue app boots → calls the internal API:
   → ApiController (com_media&task=api.*)  OR  /api/index.php/v1/media/...
   → ApiModel → ProviderManager → Adapter → storage
   → JSON back to Vue → the grid re-renders

The PHP side is a thin JSON service; the manager itself is a JavaScript app. That has a practical consequence: to change the look, you override with CSS and JavaScript layout, not with PHP template overrides.

7.3 The Web Services / Internal REST API

The component is API-first. The same routes power the single-page app and any headless client:

GET    /api/index.php/v1/media/adapters            list storage adapters
GET    /api/index.php/v1/media/adapters/{id}       one adapter
GET    /api/index.php/v1/media/files?path=...      list files / folders
GET    /api/index.php/v1/media/files/{path}        one file (meta / content)
POST   /api/index.php/v1/media/files               upload / create
PATCH  /api/index.php/v1/media/files/{path}        rename / move / edit
DELETE /api/index.php/v1/media/files/{path}        delete

These routes are registered by the webservices/media plugin. Because the UI uses these exact endpoints, anything the manager can do, a script can do too - which is great for automation and integration, and another reason to keep ACL tight.

7.4 The Adapter Contract in Full

For developers who want to build their own storage backend, here is the complete interface:

interface AdapterInterface
{
    public function getFile(string $path = '/'): \stdClass;
    public function getFiles(string $path = '/'): array;
    public function getResource(string $path);          // stream
    public function createFolder(string $name, string $path): string;
    public function createFile(string $name, string $path, $data): string;
    public function updateFile(string $name, string $path, $data): void;
    public function delete(string $path): void;
    public function copy(string $source, string $destination, bool $force = false): string;
    public function move(string $source, string $destination, bool $force = false): string;
    public function getUrl(string $path): string;
    public function getAdapterName(): string;
    public function search(string $path, string $needle, bool $recursive = false): array;
}

Twelve methods are the entire surface area. That is the contract a cloud adapter must satisfy - no more, no less.

7.5 Three Plugin Groups

The component is extensible without touching core code, thanks to three plugin groups:

filesystem      → add storage backends
media-action    → add image-editor tools
webservices     → expose / extend the REST API

7.6 Thumbnails and Image Handling

Previews and thumbnails are generated through Joomla's Image library (libraries/src/Image/Image.php), which sits on top of GD or Imagick. The editor's crop, resize, and rotate operations run through the same layer, and EXIF orientation, dimensions, and resampling are handled on the server. This is the same Image class you can call from your own code - Media just wraps it in a user interface.

7.7 At Scale

A filesystem-backed manager behaves differently from a database component, and that changes how you operate it:

A reminder for operations: a database dump does not contain your media. The bytes are on the filesystem (or in a cloud bucket), and you must back them up separately.

9. Best Practices

If you only remember a few things from this article, remember these:

• Media lives on the filesystem, not in the database. Back up the folders separately.
• Keep Restrict Uploads and Check MIME switched on. Never turn them off to force an upload.
• Plan your folder convention before editors start uploading - pictures in /images, documents in /files.
• Keep folders small; split large collections into date or context subfolders.
• To add a file type, add the extension and the MIME type, not just one.
• Grant core.create only to trusted groups.
• For storage beyond local disk, write a filesystem plugin that implements the 12-method adapter contract.

11. Summary

The Media Manager is Joomla's file layer: a storage-agnostic, plugin-driven manager that every other component borrows as its file picker. It is a different shape from the rest of Joomla, and once you see that shape, the whole component makes sense.

To summarise what it gives you:

• One manager - upload, browse, and organise, reached from every edit screen.
• In-browser editing - crop, resize, and rotate, each a swappable plugin.
• Pluggable storage - a 12-method adapter contract; local disk today, cloud tomorrow.
• API-first design - the same REST endpoints power the Vue UI and headless clients.
• Layered security - extension and real-MIME checks, size limits, root confinement, and ACL.
• A different shape - files on disk, not rows in a table; folders, not categories.

Understanding these points helps you avoid the everyday traps (the rejected .docx, the missing backup, the over-shared upload permission) and gives you a clear path when you need to scale storage to the cloud.

If you are planning a new Joomla site, migrating an old one, or troubleshooting stubborn uploads or media that went missing after a move, it pays to treat the Media Manager as the foundation it really is - and to handle its files with the same care you give your database.