Joomla bestandsstructuur uitgelegd: wat elke map doet
Als je een Joomla-installatie opent in een bestandsbeheerder, zie je zo’n twintig mappen met korte, op elkaar lijkende namen: components, modules, media, images, libraries, includes. In welke mappen staat jouw inhoud? Welke mappen worden bij een update overschreven? Waar mag je dingen plaatsen, en waar mag je absoluut niets aan raken? De meeste Joomla-problemen waarbij sprake is van "een bestand op de verkeerde plek" zijn terug te voeren op onbekendheid met deze structuur.
Dit artikel legt de bestands- en mappenstructuur van Joomla van boven tot onder uit. Het behandelt waar elke map voor is en welke van jou zijn voor site-eigenaren, de praktische wat-hoort-waar-beslissingen voor beheerders, en de padconstanten, het opstartproces en het autoladen voor ontwikkelaars. Het sluit aan op de Focus On-artikelen over templates, overrides, security hardening en troubleshooting - veel van hun regels worden vanzelfsprekend zodra je de kaart kunt lezen waarop ze opereren.
De mappenstructuur van Joomla is geen rommel. Het is een afspraak: elke map heeft één functie, en als je die functies kent, wordt het hele systeem voorspelbaar.
Het doel is eenvoudig: je naar elk pad in een Joomla-installatie laten kijken en weten wat het is, van wie het is, en of het daar thuishoort.
1. De basis
1.1 De root in een oogopslag
Een standaard Joomla 6-installatie heeft deze root (afgezien van je uploads en een eventueel verplaatste logs-map hoort er niets anders te staan):
administrator/ de backend-applicatie
api/ de Web Services-applicatie
cache/ gegenereerde pagina-/systeemcache
cli/ het commandline-toegangspunt
components/ frontend-componenten (de paginabouwers)
files/ JOUW geuploade documenten (bestandengebied mediabeheer)
images/ JOUW geuploade media
includes/ opstartbestanden voor de frontend
language/ frontend-taalbestanden
layouts/ gedeelde render-layouts (JLayout)
libraries/ het Joomla-framework + vendor-pakketten
media/ extensie-assets: css, js, fonts
modules/ frontend-modules
plugins/ alle plugins, gegroepeerd op type
templates/ frontend-templates
tmp/ kladruimte voor installaties en uploads
configuration.php je instellingen + inloggegevens
index.php het frontend-toegangspunt
htaccess.txt Apache-regels (hernoemen naar .htaccess)
web.config.txt het IIS-equivalent
robots.txt crawler-instructies
LICENSE.txt, README.txt documentatie1.2 Drie soorten dingen
| Soort | Mappen | Wie schrijft hier |
|---|---|---|
| Toegangspunten | index.php, administrator/, api/, cli/, includes/ |
Alleen Joomla. |
| Code | components/, modules/, plugins/, templates/, libraries/, layouts/, media/, language/ |
Joomla en extensie-installers - nooit jij, met een uitzondering: de map html/ van je template. |
| Data | images/, files/, cache/, tmp/, administrator/logs/, configuration.php |
Jij en Joomla tijdens runtime. Dit is het deel dat in elke back-up moet zitten. |
1.3 De ene regel achter elke andere regel
Updates vervangen code; ze raken nooit datamappen of je template-overrides aan. Dat ene feit verklaart het advies dat door deze hele artikelserie heen terugkeert: aanpassingen horen in overrides en user.css (overleven updates), uploads horen in images/ (overleven updates), en bewerkingen binnen codemappen verdampen bij de volgende release.
2. De toegangspunten: vier deuren, een huis
2.1 Vier applicaties
Joomla is een codebase die vier applicaties draait, elk met een eigen voordeur:
| Toegangspunt | Applicatie |
|---|---|
index.php |
De website die je bezoekers zien. |
administrator/index.php |
De backend. |
api/index.php |
De Web Services API (REST). |
cli/joomla.php |
De commandoregel - geen webserver nodig. |
Daarom zijn in het authenticatie-artikel site-login en API-login aparte rechten, en daarom werkt de CLI-reddingskit uit het troubleshooting-artikel terwijl de website plat ligt: verschillende deuren naar hetzelfde huis.
2.2 De map includes/
De includes/ van de frontend bevat drie kleine opstartbestanden: defines.php (de padconstanten uit sectie 9), framework.php (laadt het framework) en app.php (start de applicatie). index.php is maar een paar regels die deze binnenhalen - de toegangspunten zijn dunne deuren, niet het huis.
3. De extensiemappen
3.1 Een extensie, veel huizen
Een extensie is niet een map - haar onderdelen wonen waar hun functie het voorschrijft. Neem com_content, het artikelsysteem:
components/com_content/ frontend-code + layouts
administrator/components/com_content/ backend-code, formulieren, access.xml
media/com_content/ de css/js-assets
language/en-GB/com_content.ini frontend-taalstrings
administrator/language/en-GB/... backend-taalstrings
api/components/com_content/ de API-endpointsModules volgen dezelfde splitsing (modules/ en administrator/modules/), templates ook (templates/ en administrator/templates/). Plugins zijn de uitzondering: alle plugins wonen op een plek, plugins/{groep}/{naam}/, gegroepeerd op hun type - system, content, authentication, task, en de andere groepen die je door deze serie heen bent tegengekomen.
Binnen elk van die huizen volgt een moderne extensie een intern patroon:
src/ namespaced PHP-klassen (het doel van de autoload-kaart)
tmpl/ de layouts - overridebaar, zie het overrides-artikel
services/provider.php registreert de services van de extensie (DI-bedrading)
forms/ XML-formulierdefinities voor bewerkschermenEn hoe weet de installer in welke mappen een extensie schrijft? Elke extensie levert een manifest-XML mee (de templateDetails.xml uit het Cassiopeia-artikel is er een) die haar bestanden, mappen, taalbestanden en media declareert - de installer leest hem bij installatie, update en deinstallatie. Pas hier op met oude tutorials: extensies van voor Joomla 4 gebruikten helper.php-bestanden en assets in hun eigen mappen; het patroon src/-plus-services/ is het huidige.
3.2 layouts/: de gedeelde
De map layouts/ in de root bevat render-layouts die door alles gedeeld worden - paginering, aangepaste velden, formuliervelden. Het overrides-artikel behandelt hoe LayoutHelper ze vindt en hoe je template elk ervan kan overriden.
3.3 language/ en overrides
Taalbestanden installeren in language/{tag}/ per client. Je eigen tekstwijzigingen horen niet in die bestanden (updates vervangen ze) maar in taal-overrides, beheerd in de backend en opgeslagen onder language/overrides/ - hetzelfde overleef-de-update-patroon als template-overrides.
4. media/ versus images/: het onderscheid dat het meest telt
4.1 Twee mappen, twee eigenaren
De verwarring met de grootste gevolgen in de hele boom:
| Map | Bevat | Eigenaar |
|---|---|---|
images/ |
Jouw uploads: foto's, PDF's, logo's. Wat het mediabeheer toont. | Jij. Updates blijven er altijd vanaf. |
media/ |
Extensie-assets: de css, js, fonts en iconen die extensies en templates meeleveren. | Installers. Updates vervangen de inhoud per extensie. |
Upload de brochure van een klant naar media/ en hij kan verdwijnen met de volgende update van de map waarin hij belandde. Zet eigen CSS los in images/ en het werkt - maar zonder asset-beheer, zonder versionering, en met verbaasde opvolgers. Elke map doet zijn eigen taak goed en de taak van de ander slecht.
images/ heeft een broertje: files/, het aparte gebied van het mediabeheer voor niet-afbeelding-uploads (documenten, downloads), instelbaar via de optie file_path in de Media-instellingen. Dezelfde eigendomsregel geldt: het is van jou, updates blijven er vanaf, en het hoort in elke back-up.
4.2 De uitzonderingen die de regel bevestigen
Twee plekken in media/ zijn wel van jou, met opzet: media/templates/site/{template}/css/user.css en js/user.js (de update-bestendige eigen bestanden uit het Cassiopeia-artikel), en de mediamap van je eigen child template. Ze zijn van jou, juist omdat geen installer daar ooit schrijft.
4.3 Verkeerd verbonden
Sinds Joomla 4.1 wonen template-assets onder media/templates/ in plaats van in templates/{naam}/. De map templates/ houdt de PHP-kant - index.php, overrides in html/, het manifest - terwijl de browser-gerichte bestanden in media/ wonen. Als een tutorial je vertelt templates/cassiopeia/css/ te bewerken, beschrijft hij Joomla 3.
5. De datamappen
5.1 Wat runtime schrijft
cache/enadministrator/cache/: gegenereerde cache. Veilig te legen (Systeem → Cache legen), maar verwijder nooit de mappen zelf. Een speciaal bestand woont hier:administrator/cache/autoload_psr4.php, de class-map uit het troubleshooting-artikel.tmp/: kladruimte voor extensie-installaties en uploads. Leeg hem gerust; een verkeerdtmp_pathis de klassieke installatiefout.administrator/logs/: de logbestanden van Joomla - update-logs, het log van mislukte logins, alles wat de taakrotatelogsroteert.
5.2 Verplaats ze naar buiten (het beveiligingsartikel, toegepast)
De paden van tmp/ en de logmap zijn instelbaar in de Algemene configuratie, juist zodat je ze buiten de webroot kunt zetten, en het artikel over security hardening raadt precies dat aan. De publieke-map-indeling in sectie 9.3 trekt hetzelfde idee door tot zijn conclusie.
5.3 configuration.php
Een bestand is de identiteit van de site: databasegegevens, de $secret-sleutel, elke waarde uit de Algemene configuratie. Het staat in de root, het zit in elke back-up, het gaat nooit in versiebeheer of een supportticket, en het advies uit het beveiligingsartikel om het alleen-lezen te maken (444) geldt. Als configuration.php plus images/ plus de database het overleven, overleeft je site.
6. administrator/ en api/: de spiegels
6.1 De backend is een tweede Joomla
administrator/ spiegelt de vorm van de root: eigen components/, modules/, templates/ (Atum woont hier), language/, includes/ en cache/. Twee mappen bestaan alleen hier: manifests/, de XML-manifesten van core-pakketten en -libraries (wat het extensiebeheer leest om te weten wat er geinstalleerd is), en help/ voor de helpschermen. En logs/, zoals hierboven behandeld.
6.2 api/ is een dunne spiegel
De api/-applicatie is bewust klein: index.php, includes/, language/ en components/ met alleen de API-endpoints van componenten die ze ondersteunen. Geen templates, geen modules - een API heeft geen van beide nodig. Die slankheid is het punt: het "alleen ruwe data"-gedrag uit het Web Services-artikel is direct zichtbaar in de maplijst.
7. libraries/: het framework zelf
7.1 Twee helften
libraries/src/: de Joomla CMS-klassen - elkeJoomla\CMS\...-klasse die je in deze serie zag (Authentication,Access,LayoutHelper,Log) verwijst naar een bestand hier.libraries/vendor/: pakketten van derden, beheerd via Composer - de Joomla Framework-pakketten, de databaselaag, PSR-interfaces en libraries zoals TUF voor update-verificatie.
7.2 Vrij lezen, nooit schrijven
libraries/ is de beste Joomla-documentatie die er is - deze hele artikelserie verifieerde zijn beweringen door deze bestanden te lezen. Maar het is ook de map waar "snelle fixes" de meeste schade aanrichten: een bewerking hier raakt alles, verdwijnt bij een update, en (zoals het troubleshooting-artikel zegt) een gewijzigd core-bestand is in een audit niet te onderscheiden van een hack. Dagelijks lezen; nooit schrijven.
8. Wat hoort waar: de praktische kaart
8.1 "Ik wil…"
| Ik wil… | Het hoort in… |
|---|---|
| Foto's en documenten uploaden | images/, via het mediabeheer. |
| Eigen CSS of JS toevoegen | media/templates/site/{child}/css/user.css - de manier van het Cassiopeia-artikel. |
| Extensie-markup wijzigen | templates/{child}/html/ - de manier van het overrides-artikel. |
| Interfacetekst wijzigen | Taal-overrides in de backend (language/overrides/). |
| Functionaliteit toevoegen | Een geinstalleerde extensie - nooit losse bestanden in codemappen. |
| Back-ups opslaan | Helemaal niet in de boom. Buiten de webroot, weg van de server (back-upartikel). |
8.2 De gezonde-root-test
Een goed onderhouden Joomla-root bevat exact de items uit sectie 1.1 - niets meer. Elk extra item is een vraag waard: een backup.zip (beveiligingsrisico), een test.php (vergeten experiment of webshell), een map old/ (een complete tweede site met eigen verouderde kwetsbaarheden). De kwartaalcontrole op bestandsintegriteit uit het onderhoudsartikel is in wezen deze test, geautomatiseerd.
9. Onder de motorkap (ontwikkelaarsblik)
9.1 De JPATH-constanten
includes/defines.php benoemt elke locatie een keer, en alle core-code gebruikt de namen - en daarom werkt het verplaatsen van mappen uberhaupt:
JPATH_ROOT de installatieroot
JPATH_SITE root van de frontend-applicatie
JPATH_ADMINISTRATOR de map administrator/
JPATH_API de map api/
JPATH_LIBRARIES libraries/
JPATH_PLUGINS plugins/
JPATH_THEMES de templatemap van de actieve client
JPATH_CACHE de cachemap van de actieve client
JPATH_MANIFESTS administrator/manifests/
JPATH_PUBLIC de web-geserveerde root (standaard JPATH_ROOT)Bouw in je eigen code paden altijd op vanuit deze constanten - JPATH_ROOT . '/images/...' - nooit vanuit geraden relatieve paden.
9.2 Van namespace naar bestand
Joomla laadt klassen automatisch door namespaces op mappen af te beelden. De gegenereerde kaart in administrator/cache/autoload_psr4.php toont het patroon letterlijk:
Joomla\CMS\... → libraries/src/...
Joomla\Component\Content\Site\... → components/com_content/src/...
Joomla\Component\Content\Administrator\ → administrator/components/com_content/src/...
Joomla\Plugin\System\Debug\... → plugins/system/debug/src/...Lees een namespace en je kent het bestand; lees een pad en je kent de namespace. Deze afbeelding is ook waarom het verwijderen van de verouderde kaart de "class not found"-mysteries uit het troubleshooting-artikel oplost: de kaart zei het ene, de schijf het andere.
9.3 JPATH_PUBLIC en de publieke-map-indeling
JPATH_PUBLIC bestaat voor de indeling die het beveiligingsartikel voor nieuwe sites aanraadt: alleen de toegangspunten en web-assets in de geserveerde map, al het andere - code, configuratie, logs - een niveau boven de webroot, buiten bereik van elke URL. Op een klassieke installatie is de constante simpelweg gelijk aan JPATH_ROOT; de boom in dit artikel is de klassieke indeling.
10. De Web Services API
De structuur zelf is hier de les: api/components/ bevat een map per component die endpoints aanbiedt, en de webservices-plugingroep (in plugins/webservices/) registreert hun routes. Toen het API-artikel zei dat routes zoals v1/content/articles naar componentcode verwijzen, is dit de code waarnaar ze verwijzen. Een component zonder aanwezigheid in api/components/ heeft geen REST-oppervlak - de map controleren is de snelste manier om het te weten.
Niets in de bestandsboom wordt door de API geserveerd - die geeft database-content terug, geen bestanden. Bestanden die via het web bereikbaar zijn, serveert de webserver direct, en precies daarom zijn verdwaalde bestanden in de boom (sectie 8.2) een beveiligings- en SEO-zorg in plaats van een API-zorg.
Naar boven11. SEO en metadata
De bestandsboom raakt SEO aan de randen, en de randen doen ertoe. Alles onder de webroot is potentieel crawlbaar: een vergeten old/-kopie van de site wordt geindexeerd als duplicate content, een verdwaalde databasedump kan in zoekresultaten belanden (het gebeurt - en het is eerst een datalek, daarna pas een SEO-probleem), en robots.txt - in de root, zoals behandeld in zijn eigen artikel - is je instrument om crawlers weg te sturen van wat niet geindexeerd hoort te worden.
De positieve kant woont in images/: beschrijvende map- en bestandsnamen (images/producten/blauwe-widget.webp verslaat images/IMG_4711.jpg) tellen mee voor beeldzoekresultaten, en een opgeruimde afbeeldingenboom laat redacteuren het juiste, geoptimaliseerde bestand kiezen in plaats van duplicaten opnieuw te uploaden - de afbeeldingsdiscipline uit het prestatie-artikel begint met mapdiscipline.
12. Veelvoorkomende fouten en valkuilen
12.1 Uploads in media/, assets in images/
Symptoom: documenten verdwijnen na een extensie-update, of eigen CSS zweeft onbeheerd in de uploadmap.
Oplossing: de regel van sectie 4: images/ is van jou, media/ is van de installers - behalve user.css/user.js en de mediamap van je child template.
12.2 Bestanden bewerken in codemappen
Symptoom: een aanpassing direct in components/, media/ of libraries/ verdwijnt na een update.
Oplossing: het contract van sectie 1.3: updates vervangen code. Doe de wijziging opnieuw als override, als user.css-regel of als nette extensie.
12.3 Back-ups en dumps binnen de boom
Symptoom: site-backup.zip of dump.sql in de root - downloadbaar voor iedereen die de naam raadt.
Oplossing: back-ups wonen buiten de webroot, punt. Het back-up- en het beveiligingsartikel staan er beide op, en de bestandsboom laat zien waarom: alles in de boom is potentieel publiek.
12.4 Mappen verwijderen in plaats van inhoud
Symptoom: na het "opruimen" overal cache- of tmp-fouten - de map zelf is weg.
Oplossing: cache/ en tmp/ moeten bestaan en beschrijfbaar zijn; alleen hun inhoud is wegwerpbaar. Maak de map opnieuw aan, zet maprechten 755, en gebruik volgende keer Systeem → Cache legen.
12.5 Onverklaarde bestanden als onschuldig behandelen
Symptoom: een test.php of vreemd genoemd bestand in de root "dat er waarschijnlijk altijd al stond".
Oplossing: niets in een Joomla-boom is onverklaard. Vergelijk met sectie 1.1 en een schone download; kun je een bestand niet verklaren, behandel het dan als incident response-terrein uit het beveiligingsartikel, niet als rommel.
12.6 De verkeerde configuration.php bewerken
Symptoom: configuratiewijzigingen hebben geen effect - bij inspectie bewaarde een editor een kopie (configuration.php.bak, of een in een submap) in plaats van het echte rootbestand.
Oplossing: het live bestand is exact JPATH_ROOT/configuration.php. Verwijder verdwaalde kopieen - ze bevatten inloggegevens en horen nergens anders.
13. Best practices
Als je maar een paar dingen uit dit artikel onthoudt, onthoud dan deze:
- Ken de drie soorten: toegangspunten en code zijn van Joomla;
images/,configuration.phpen de runtime-mappen zijn de data van de site. - Uploads in
images/, eigen assets in deuser.cssvan je child template, markup-wijzigingen inhtml/-overrides, tekstwijzigingen in taal-overrides. - Schrijf nooit binnen codemappen -
libraries/is om te lezen. - Houd de root exact zoals geleverd: elk extra bestand is een vraag, en back-ups wonen volledig buiten de boom.
- Verplaats
tmp/en logs uit de webroot; overweeg de publieke-map-indeling voor nieuwe sites. - Bouw paden in code op uit
JPATH_*-constanten, en lees namespaces als routebeschrijvingen naar bestanden. - Bij twijfel van wie een map is: kijk of een update of installer er zou schrijven.
14. In het kort
VAN JOU images/ + files/ uploads (mediabeheer)
configuration.php instellingen + inloggegevens (444, back-up!)
templates/{child}/html/ overrides
media/templates/site/{child}/ user.css, user.js
language/overrides/ tekstwijzigingen
VAN JOOMLA components/ modules/ plugins/ templates/ layouts/
libraries/ (src = CMS-klassen, vendor = pakketten)
media/ (extensie-assets - GEEN uploads)
includes/ + index.php toegangspunten
RUNTIME cache/ + administrator/cache/ (legen, nooit verwijderen)
tmp/ (klad, verplaatsbaar)
administrator/logs/ (logs, verplaatsbaar)
SPIEGELS administrator/ volledige backend (+ manifests/, help/, logs/)
api/ dun: alleen componenten met REST-endpoints
cli/joomla.php de vierde deur
START index.php > includes/defines|framework|app.php
PADEN JPATH_ROOT SITE ADMINISTRATOR API LIBRARIES
PLUGINS THEMES CACHE MANIFESTS PUBLIC
namespace → pad: Joomla\Component\X\Site\
= components/com_x/src (kaart: autoload_psr4.php)
REGELS updates vervangen code, nooit data of overrides
root = alleen de geleverde lijst; extra's zijn vragen
back-ups BUITEN de boom; media/ is niet images/15. Samenvatting
De bestandsstructuur van Joomla is een klein systeem van contracten:
- Drie soorten inhoud: toegangspunten, code en data - en alleen data (plus je overrides) is van jou om te beschrijven.
- Vier deuren: site, administrator, API, CLI - een codebase, vier dunne toegangspunten.
- Extensies wonen verspreid: frontend-, backend-, media-, taal- en API-delen elk in de map die hun functie voorschrijft; plugins gegroepeerd op type in een boom.
- Het kritieke onderscheid:
images/is jouw media,media/is extensie-assets - metuser.cssen child-templatemappen als de bewuste uitzonderingen. - Runtime-mappen (
cache/,tmp/, logs) zijn wegwerpbaar in inhoud, onmisbaar in bestaan, en het best verplaatst uit de webroot. - Voor ontwikkelaars:
JPATH_*-constanten benoemen elke locatie, namespaces verwijzen naar paden, en de publieke-map-indeling haalt de webserver weg bij alles behalve de toegangspunten.
Zodra de kaart in je hoofd zit, wordt de helft van deze artikelserie eenvoudiger: overrides, hardening, back-ups en troubleshooting worden allemaal toepassingen van "van wie is deze map, en wie schrijft hier?".
En is de boom van een site door de jaren heen mysterieus geworden - verdwaalde bestanden, dubbele kopieen, aanpassingen die niemand kan plaatsen - dan is een bestandsstructuur-audit tegen een schone Joomla methodisch, bevredigend werk: alles verklaard, verplaatst of verwijderd. Het is precies het soort voorjaarsschoonmaak dat een Joomla-specialist voor elke migratie doet, en de site is daarna veiliger en lichter.
Naar boven
