Media in Joomla

1. De basis

1.1 Wat maakt media anders?

Het eerste dat je moet begrijpen, is dat de Media Manager zich fundamenteel anders gedraagt dan de meeste andere componenten in Joomla:

De belangrijkste consequentie hiervan is dat er geen #__media-tabel bestaat. Je mediagegevens zijn simpelweg de mappenstructuur op schijf. Dat ene feit verklaart vrijwel alles in dit artikel, van back-ups en prestaties tot migraties.

1.2 De onderdelen

Het helpt om de volledige keten in één overzicht te zien, van de interface tot de daadwerkelijke bestanden:

Media Manager-interface (Vue single-page app)
   │  communiceert via REST / AJAX
   ▼
ApiModel  →  ProviderManager  →  Adapter  →  opslag
                                    (lokaal)      (bestanden op schijf)

• De interface is een Vue-gebaseerde single-page applicatie in de backend.
• Een adapter weet hoe bestanden gelezen en geschreven moeten worden op één opslagplatform.
• Een provider is een bestandssysteemplugin die één of meerdere adapters levert.
• De opslag is de plek waar de bytes daadwerkelijk staan. Standaard is dat de map images/ op de lokale schijf.

Houd dit schema in gedachten. In het technische deel van dit artikel komt elk onderdeel terug als een uitbreidingspunt.

1.3 Waar vind je de Media Manager?

In Joomla 6 vind je de Media Manager en de instellingen op twee plaatsen:

Content → Media                              (de Media Manager zelf)
System  → Global Configuration → Media       (de instellingen)

De Media Manager verschijnt ook ingebed in formulieren die een mediaveld gebruiken. De knop "Selecteren" naast een afbeeldingsveld opent dezelfde Media Manager in een modaal venster. Veel redacteuren openen daarom nooit rechtstreeks Content → Media, maar gebruiken hem via een afbeeldingsknop in de editor.

1.4 Twee hoofdlocaties: /images en /files

Jarenlang gebruikte Joomla alleen de map images/. Moderne Joomla-versies bieden standaard twee hoofdlocaties, zodat documenten niet tussen afbeeldingen terechtkomen:

De scheiding is puur organisatorisch: plaats afbeeldingen in /images en downloadbare documenten in /files. Beide mappen bevinden zich in de hoofdmap van Joomla.

1.5 Twee configuratielagen bepalen deze hoofdlocaties

Dit detail zorgt vaak voor verwarring omdat de hoofdlocaties op twee verschillende plaatsen worden geconfigureerd, elk met een eigen doel:

1. Lokale bestandssysteemplugin (plg_filesystem_local)
   parameter "directories" = [{"directory":"images"}, {"directory":"files"}]
   → elke invoer wordt een APARTE adapter (een hoofdniveau in de boomstructuur)
   → elke adapter kan eigen thumbnailinstellingen hebben
   → voeg hier extra mappen toe, bijvoorbeeld "downloads"

2. com_media-instellingen (System → Global Configuration → Media)
   image_path = images   ← standaardlocatie voor afbeeldingsvelden
   file_path  = files    ← standaardlocatie voor documenten

Kort samengevat: de plugin bepaalt welke mappen zichtbaar worden als adapters; de componentinstellingen bepalen welke daarvan als "afbeeldingen" of "bestanden" worden gebruikt in mediakiezers. Beide worden gecontroleerd op geldigheid. Systeemmappen zoals administrator, libraries en cache zijn expliciet uitgesloten en kunnen niet als hoofdlocatie worden ingesteld.

3. Bestandstypen: afbeeldingen, Office, audio, video en SVG

3.1 De vier extensielijsten

Naast de hoofdwhitelist voor uploads verdeelt het scherm Opties bestandsextensies in vier groepen. Deze groepen bepalen hoe de Media Manager een bestand verwerkt en weergeeft nadat het is geüpload:

De belangrijkste regel: een extensie moet in de lijst Toegestaan staan om überhaupt geüpload te kunnen worden. De andere lijsten bepalen alleen hoe het bestand daarna wordt weergegeven.

3.2 Audio en video: MP3 en MP4 werken direct

Goed nieuws: mp3 en mp4 staan standaard zowel in de whitelist als in de audio- en videolijsten. Ze werken dus direct na installatie:

upload interview.mp3  → toegestaan → audio_extensions → ingebouwde <audio>-speler
upload promo.mp4      → toegestaan → video_extensions → ingebouwde <video>-speler

• Plaats ze in /files of /images, selecteer ze via een mediaveld en ze worden automatisch weergegeven in de preview.
• mp4 staat zowel in de audio- als videolijst; Joomla kiest automatisch de juiste speler.
• Wil je webm, mov of ogg gebruiken? Deze staan al in de audio- of videolijsten, maar moeten mogelijk nog worden toegevoegd aan de lijst Toegestaan voordat uploads werken.

3.3 Microsoft Office en OpenDocument: een veelvoorkomende valkuil

Let goed op de standaardinstellingen, want dit veroorzaakt regelmatig supportvragen:

Standaard kun je dus een oude .doc uploaden, maar geen moderne .docx. De moderne Office-formaten ontbreken zowel in de extensiewhitelist als in de MIME-whitelist.

Om moderne Office-documenten toe te staan, moet je zowel de extensies als de MIME-types toevoegen:

restrict_uploads_extensions:  …,docx,xlsx,pptx

upload_mime: voeg de OOXML MIME-types toe, bijvoorbeeld

application/vnd.openxmlformats-officedocument.wordprocessingml.document     (docx)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet           (xlsx)
application/vnd.openxmlformats-officedocument.presentationml.presentation   (pptx)

Voeg je alleen de extensie toe maar niet het MIME-type, dan zal de controle Check MIME de upload alsnog blokkeren. Dit is de klassieke "mijn docx wil niet uploaden"-melding.

3.4 SVG: bewust geblokkeerd

De extensie svg staat standaard niet in één van de lijsten. Niet bij Toegestaan, niet bij Afbeeldingen en ook image/svg+xml ontbreekt in de MIME-whitelist. Dat is een bewuste beveiligingskeuze:

Een .svg-bestand is XML. XML kan bevatten:

   <script>…</script>             → opgeslagen XSS
   <a xlink:href="javascript:">   → uitvoering van scripts
   externe entity-referenties     → SSRF / datalekken

Een SVG gedraagt zich als een afbeelding, maar kan zich ook gedragen als een document met uitvoerbare code. Daardoor vormt een SVG-bestand een mogelijk risico voor opgeslagen cross-site scripting (XSS). Joomla blokkeert SVG daarom standaard.

Heb je SVG echt nodig, bijvoorbeeld voor een vertrouwde iconenset, schakel het dan zorgvuldig in:

1. Voeg svg toe aan restrict_uploads_extensions EN image_extensions
2. Voeg image/svg+xml toe aan upload_mime
3. Geef alleen vertrouwde gebruikers uploadrechten (ACL)
4. Reinig SVG-bestanden vooraf
   (verwijder scripts, event-handlers en externe verwijzingen)

Zie het inschakelen van SVG op dezelfde manier als het toestaan van eigen HTML-code: meer flexibiliteit, maar ook meer verantwoordelijkheid. Beperk dit tot vertrouwde gebruikers en controleer de bestanden.

3.5 Een nieuw bestandstype toevoegen: de checklist

Wanneer een upload wordt geweigerd, controleer dan deze punten in volgorde:

1. Staat de extensie in restrict_uploads_extensions?
   (zo niet, dan wordt het bestand direct geblokkeerd)

2. Staat Check MIME aan?
   → het echte MIME-type moet voorkomen in upload_mime

3. Wil je miniaturen of de afbeeldingseditor gebruiken?
   → voeg de extensie toe aan image_extensions

4. Wil je een audio- of videospeler?
   → voeg de extensie toe aan audio_extensions of video_extensions

5. Is het bestand kleiner dan upload_maxsize én PHP's
   upload_max_filesize en post_max_size?

Zowel de extensie als het MIME-type moeten worden goedgekeurd. Slechts één van beide aanpassen is de meest voorkomende reden waarom een bestand nog steeds niet geüpload kan worden.

5. De adapterarchitectuur (het slimme deel)

5.1 Eén interface, verwisselbare opslag

De volledige component is gebouwd rond één contract: AdapterInterface. Dit definieert twaalf methoden:

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

Implementeer deze twaalf methoden en de volledige Media Manager werkt direct met jouw opslagplatform, of dat nu Amazon S3, Azure Blob Storage, een DAM-systeem of iets anders is.

5.2 Providers leveren adapters

Een adapter verschijnt niet vanzelf. Een provider levert één of meer adapters aan:

Bestandssysteemplugin (provider)  →  één of meer adapters
plg_filesystem_local              →  LocalAdapter (één per geconfigureerde hoofdlocatie)

• Een bestandssysteemprovider is een plugin uit de groep filesystem.
• De Joomla-core levert standaard slechts één provider: Local (plugins/filesystem/local).
• De configuratie van deze plugin bevat de hoofdlocaties, bijvoorbeeld images en files. Elke hoofdlocatie wordt een afzonderlijke adapter in de boomstructuur.

5.3 De ProviderManager

Een kleine registry bindt alles aan elkaar:

ProviderManager
  ├─ registreert alle ingeschakelde filesystem-plugins
  ├─ elke plugin levert zijn adapter(s)
  └─ de interface toont deze als provider-adapter-nodes

Een adapter wordt aangesproken via het formaat provider:adapter:/pad, bijvoorbeeld:

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

Dankzij het voorvoegsel provider-adapter weten zowel de API als de gebruikersinterface op welke opslaglocatie een bestand zich bevindt.

5.4 Een cloudadapter schrijven (conceptueel)

Om te laten zien hoe uitbreidbaar dit systeem is, volgt hier een vereenvoudigd voorbeeld van een S3-adapter:

class S3Adapter implements AdapterInterface
{
    public function getFiles(string $path = '/'): array { /* bucket uitlezen */ }

    public function createFile(string $name, string $path, $data): string
    {
        /* putObject */
    }

    public function getUrl(string $path): string
    {
        /* gesigneerde URL */
    }

    // ... de overige negen methoden
}

Verpak deze adapter in een plugin uit de groep filesystem, activeer de plugin en er verschijnt automatisch een nieuwe hoofdlocatie in de Media Manager. De gebruikersinterface hoeft hiervoor niet aangepast te worden.

Dit is misschien wel het belangrijkste architecturale principe van com_media: opslag is een plugin.

7. Achter de schermen (voor ontwikkelaars)

7.1 Geen tabel, maar een servicelaag

Omdat er geen databasetabel bestaat, is de component opgebouwd uit services en plugins:

administrator/components/com_media/
  src/Adapter/AdapterInterface.php      het contract met 12 methoden
  src/Provider/ProviderManager.php      registreert providers / adapters
  src/Model/ApiModel.php                coördineert CRUD-acties
  src/Model/MediaModel.php              model achter de SPA
  src/Controller/ApiController.php      AJAX-endpoints voor de Vue-interface
  src/Controller/DisplayController.php  rendert de SPA-shell

plugins/filesystem/local/   de enige provider uit de core
  src/Adapter/LocalAdapter.php

plugins/media-action/       bijsnijden / formaat wijzigen / roteren
media/com_media/js/         media-manager.js + edit-images.js (Vue)

7.2 De aanvraagstroom

Wanneer je de Media Manager opent, gebeuren er twee dingen: eerst wordt de pagina geladen, daarna neemt de JavaScript-applicatie het over en communiceert met de API:

1. Content → Media
   → DisplayController rendert de Vue SPA-shell
     (één <div> + assets)

2. De Vue-app start → roept de interne API aan:
   → ApiController (com_media&task=api.*)
      of /api/index.php/v1/media/...
   → ApiModel → ProviderManager → Adapter → opslag
   → JSON terug naar Vue → raster wordt opnieuw opgebouwd

De PHP-kant is in feite een lichte JSON-service. De manager zelf is vooral een JavaScript-applicatie. Dat heeft een praktisch gevolg: wil je het uiterlijk aanpassen, dan werk je met CSS en JavaScript-layouts, niet met traditionele PHP-template-overrides.

7.3 De Web Services / interne REST API

De component is API-first. Dezelfde routes worden gebruikt door zowel de single-page app als externe of headless clients:

GET    /api/index.php/v1/media/adapters            lijst met opslagadapters
GET    /api/index.php/v1/media/adapters/{id}       één adapter
GET    /api/index.php/v1/media/files?path=...      lijst met bestanden / mappen
GET    /api/index.php/v1/media/files/{path}        één bestand (metadata / inhoud)
POST   /api/index.php/v1/media/files               uploaden / aanmaken
PATCH  /api/index.php/v1/media/files/{path}        hernoemen / verplaatsen / bewerken
DELETE /api/index.php/v1/media/files/{path}        verwijderen

Deze routes worden geregistreerd door de plugin webservices/media. Omdat de gebruikersinterface exact dezelfde eindpunten gebruikt, kan alles wat de Media Manager kan ook via scripts worden geautomatiseerd. Dat maakt integraties eenvoudig, maar benadrukt ook waarom ACL-rechten strikt moeten worden beheerd.

7.4 Het volledige adaptercontract

Voor ontwikkelaars die een eigen opslagbackend willen bouwen, volgt hier de volledige 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;
}

Deze twaalf methoden vormen het volledige contract. Een cloudadapter hoeft niet meer en niet minder te implementeren.

7.5 Drie plugingroepen

De component is uitbreidbaar zonder corebestanden aan te passen dankzij drie plugingroepen:

filesystem      → nieuwe opslagbackends toevoegen
media-action    → nieuwe gereedschappen voor de afbeeldingseditor
webservices     → de REST API uitbreiden of beschikbaar maken

7.6 Miniaturen en afbeeldingsverwerking

Voorvertoningen en miniaturen worden gegenereerd via Joomla's Image-bibliotheek (libraries/src/Image/Image.php), die gebruikmaakt van GD of Imagick. De functies voor bijsnijden, schalen en roteren in de afbeeldingseditor gebruiken dezelfde laag. Ook EXIF-oriëntatie, afmetingen en resampling worden server-side verwerkt.

Het gaat om dezelfde Image-klasse die je ook vanuit je eigen extensies kunt gebruiken. De Media Manager voegt daar alleen een gebruikersinterface bovenop toe.

7.7 Op grotere schaal

Een bestandsgebaseerde beheerder gedraagt zich anders dan een component die op een database draait. Dat heeft gevolgen voor beheer en prestaties:

Een belangrijke herinnering voor beheerders: een databaseback-up bevat geen mediabestanden. Die staan op het bestandssysteem of in een cloudopslag en moeten afzonderlijk worden meegenomen in je back-upstrategie.

9. Best practices

Als je maar een paar dingen uit dit artikel onthoudt, laat het dan deze zijn:

• Media staat op het bestandssysteem, niet in de database. Maak daarom aparte back-ups van de mediamappen.
• Laat Restrict Uploads en Check MIME altijd ingeschakeld. Schakel ze nooit uit om een upload te forceren.
• Bepaal je mappenstructuur voordat redacteuren bestanden gaan uploaden, afbeeldingen in /images, documenten in /files.
• Houd mappen klein en overzichtelijk. Verdeel grote verzamelingen over submappen per jaar, campagne of onderwerp.
• Bij het toevoegen van een nieuw bestandstype moet je zowel de extensie als het MIME-type toevoegen.
• Geef core.create alleen aan vertrouwde gebruikersgroepen.
• Wil je opslag buiten de lokale schijf gebruiken, maak dan een plugin in de groep filesystem die het adaptercontract met twaalf methoden implementeert.

11. Samenvatting

De Media Manager vormt de bestandslaag van Joomla: een opslagonafhankelijke, plugin-gestuurde beheeromgeving die door vrijwel alle andere componenten wordt gebruikt als bestandskiezer. Het werkt anders dan de meeste onderdelen van Joomla, en zodra je dat verschil begrijpt, valt de hele architectuur op zijn plaats.

Kort samengevat biedt de Media Manager:

• Eén centrale beheeromgeving, voor uploaden, bladeren en organiseren van bestanden vanuit vrijwel elk bewerkscherm.
• Bewerken in de browser, zoals bijsnijden, schalen en roteren van afbeeldingen, waarbij elk gereedschap een vervangbare plugin is.
• Uitbreidbare opslag, dankzij een adaptercontract met twaalf methoden, waardoor je vandaag lokale opslag en morgen cloudopslag kunt gebruiken.
• Een API-first ontwerp, waarbij dezelfde REST-endpoints worden gebruikt door zowel de Vue-interface als headless toepassingen.
• Meerdere beveiligingslagen, waaronder extensie- en MIME-controles, uploadlimieten, afgeschermde hoofdlocaties en ACL-rechten.
• Een fundamenteel andere structuur, bestanden op schijf in plaats van records in een tabel, en mappen in plaats van categorieën.

Met dit inzicht voorkom je veelvoorkomende problemen zoals een geweigerde .docx-upload, ontbrekende mediabestanden na een migratie of te ruim ingestelde uploadrechten. Tegelijk krijg je een duidelijk beeld van hoe je opslag later kunt uitbreiden naar cloudplatformen.

Of je nu een nieuwe Joomla-site bouwt, een bestaande website migreert of onderzoekt waarom uploads mislukken of mediabestanden verdwenen lijken, het loont om de Media Manager te behandelen als de fundering die hij werkelijk is, en om net zo zorgvuldig met je mediabestanden om te gaan als met je database.