Mappenstructuur

In dit blog bericht ga ik dieper in op de mappenstructuur van Magento 2. Welke bestanden en mappen staan er in de Root directory van Magento 2? En welke mappen en bestanden bevatten een module, een theme en een language package? Het mappenstructuur van Magento 2 zal ik in deze 4 onderdelen uitleggen.

Root directory	De root directory van Magento 2.
Module	Een module is een structureel deel van Magento 2. Het hele systeem is opgebouwd uit modules. De standaard functionaliteiten van Magento 2 zijn ook opgebouwd uit modules. Om op een module in te haken zul je daarvoor een module moeten maken. Modules interacteren met andere delen van de applicatie om de applicatie van bepaalde functionaliteiten of features te voorzien. Een module kan een gebruikersinterface bevatten voor het weergeven van informatie of interactie met de gebruiker.
Theme	Met themes kun je het uiterlijk en de look en feel van de storefront (voorkant) en de admin (beheer kant) veranderen en personaliseren met bijvoorbeeld sjablonen, layouts, styling en afbeeldingen. Met een thema kun je de Magento 2 weergave laag overschrijven of aanpassen. Bij de Magento 2 installatie worden de Luma Theme een demo theme en de Blank Theme als basis theme standaard bijgevoegd. Het wordt aangeraden om deze thema’s niet aan te passen. Wil je deze themes gebruiken dan dien je een nieuwe theme aan te maken. Het theme kan een zelfstandige theme zijn, maar het kan ook erven van een andere theme (een parent theme). Dit heet het “theme inheritance concept”.
Language package	Een taalpakket is een verzameling van vertalingen voor een bepaalde taal. Dit zijn komma gescheiden .csv bestanden met ten minste 2 kolommen: de originele waarde uit de en_US locale en de vertalende waarde uit een andere locale (voor Nederlands is dit bijvoorbeeld nl_NL). Er zijn 2 type vertalingen: module of thema specifieke vertalingen. Deze vertalingen kun je in de i18n map vinden van de module of theme. Een stand alone taalpakket. Dit is een zelfstandig component dat vergelijkbaar is met een module of theme.

Root directory

Hieronder een overzicht van de mappenstructuur van Magento 2. Een hoop bestanden of mappen zal ik niet behandelen. Ik zal even de belangrijkste benoemen en inhoudelijk uitleg geven. (In het grijs de dingen die even minder belangrijk zijn).

<root_dir>/
|– app/
| |– code/
| |– design/
| | |– adminhtml/
| | |– frontend/
| |– etc/
| | |– config.php
| | |– env.php
|– bin/
| |– magento
|– dev/
| |– tests/
| |– tools/
| | |– grunt/
| | |– Magento/
|– lib/
|– phpserver/
|– pub/
| |– media/
| |– static/
| |– index.php
|– setup/
|– var/
| |– cache/
| |– composer_home/
| |– di/
| |– generation/
| |– log/
| |– page_cache/
| |– view_preprocessed
|– vendor/
|– .gitignore
|– .htaccess
|– auth.json
|– composer.json
|– composer.lock
|– Gruntfile.js
|– index.php
|– nginx.conf
|– package.json

.gitignore	Hierin staan de mappen of bestanden die je niet wil meenemen in je GIT commits.
.htaccess	Dit bestand is de configuratie bestand als je gebruik maakt van Apache Web Server.
auth.json	Sommige repositories hebben authenticatie nodig als je packages via composer wil laten ophalen. Dan krijg je een “prompt” bericht. In de auth.json kun je deze credentials plaatsen zodat je niet elke keer je gegevens hoeft in te vullen.
composer.json	Zie composer.json
composer.lock	Zie composer.lock
Gruntfile.js	De Gruntfile.js wordt gebruikt voor de Grunt configuratie, om de Grunt tasks te bepalen en om Grunt plugins in te laden. Grunt is een javascript task runner en wordt in Magento gebruikt om less bestanden te compilen.
index.php
nginx.conf	Dit bestand is de configuratie bestand als je gebruik maakt van Nginx Web Server.
package.json	Npm is een package manager voor JavaScript. Je kunt het vergelijken met composer maar dan is npm voor JavaScript. In de package.json staat de configuratie voor npm en welke packages en afhankelijkheden geladen moeten worden.

App

In de app folder kun je de omgeving en database configuratie, de applicatie specifieke modules en themes vinden. Er wordt geadviseerd om aanpassingen in de /app/code folder te doen en niet in de /app/vendor map. Modules die je dus maakt dien je dus toe te voegen in de app/code. De storefront of admin themes kun je toevoegen in app/design. Zo kun je ook vertalingen toevoegen in de app/i18n map. In de etc map kun je het env.php bestand vinden en de config.php. De config.php bestaat uit een array van al je in- en uitgeschakelde Magento 2 modules die in je applicatie aanwezig zijn.

Modules	<root_dir>/app/code
Module binnen de app/code map. Hierin is <Vendor> de folder dat de verzamelnaam is van de eigenaar / verkoper of makers van de module. Dit wordt weer vervolgd door een folder dat de naam is van de module. Bijv <root_dir>/app/code/Company/Client.	<root_dir>/app/code/<Vendor>/<module_naam>/
Storefront themes	<root_dir>/app/design/frontend
Admin themes	<root_dir>/app/design/adminhtml
Language packages	<root_dir>/app/i18n

Bin

De bin folder bestaat uit het “magento” CLI script. Dit wordt gebruikt voor de Magento 2 command line tool, met verschillende opties en functies die je vanuit de command line kunt uitvoeren. Alle commando’s voor Magento 2 staan in het mapje bin en roep je aan met “magento”. Om alle commando’s te zien voer je de volgende commando uit:

php bin/magento --list

De volgende commando is om uitleg of hulp te krijgen voor een specifieke commando

php bin/magento --help <command>

Bijvoorbeeld:

php bin/magento --help setup:install
php bin/magento --help cache:enable

Dev

Een folder dat bestaat uit een aantal test tools en andere developer tools. Om tools om tests voor je applicatie uit te voeren staan in de dev map. Dit is nodig voor het uitvoeren van unit tests, functionele en acceptatie tests. Om JavaScript te testen zit de javascript tool Jasmine al standaard in Magento 2. Ook zit het Selenium framework ook in Magento 2 voor het doorvoeren van acceptatie tests. Daarnaast gebruikt Magento 2 PHPUnit voor het doorvoeren van unit tests voor het testen van de PHP code. In de dev/tools map vind je ook de grunt map en logica wanneer je Grunt gebruikt als javascript task-runner voor het compilen van je less bestanden. Meer over Grunt volgt later.

Lib

Dit is de folder waarin de Magento UI Library staat (lib/web). De Magento UI Library is een flexibele modulaire frontend bibliotheek voor theming dat bestaat uit een aantal basis elementen / componenten bestaande uit css, fonts en icons, afbeeldingen en jquery elementen. Bekijk hier. Deze componenten zijn makkelijk aan te passen en te beheren. Eventueel te beheren via LESS. Responsive en accessible. Hieronder een overzicht van de elementen:

actions-toolbar
breadcrumbs
buttons
components
drop-downs
forms
icons
layout
loaders
messages
pagination
popups
ratings
resets
responsive
sections – tabs and accordions
tables
tooltips
typography
utilities
list of theme variables

css/ folder voor de library bestanden
fonts/ folder voor de fonts en icons
images/ folder voor de default afbeeldingen
jquery/ folder voor jQuery en jQuery widgets

Phpserver

Hierin zit een bestand, de Router.php en is gemaakt voor de Built-in web server. Hier zul je niet veel mee te maken krijgen, maar mocht je meer willen weten: lees hier meer.

Pub

De pub folder is de publieke map (in productie mode) van de shop. Dit is een security laag, en zorgt ervoor dat er geen public root access is. Daarom zijn er ook 2 index.php bestanden te vinden. Een in de root, en een in de pub map. Je kunt de webroot (voor development) dus op 2 manieren instellen “/”, dit kijkt dus naar de index.php in je root. Of “/pub”, dit kijkt naar de index.php bestand in de pub map. In product mode is de “pub” map de webroot en is de pub map alleen toegankelijk van buitenaf. Zo worden geen enkele Magento configuraties, templates of andere bestanden rechtstreeks toegankelijk gemaakt van buitenaf.

Verder bestaat de pub map uit gegenereerde “static files”. Dit zijn theme assets zoals CSS, fonts, afbeeldingen en JavaScript. Deze assets worden over heel de applicatie verzameld in de pub/static map. In de default of developer mode worden deze bestanden automatisch gegenereerd. In productie mode kun je ze alleen via een commando (bin/magento setup:static-content:deploy) laten aanmaken. Deze bestanden kunnen in productie mode niet automatisch gegenereerd of gecached worden.

Het pad ziet er meestal zo uit: /pub/static/frontend/<Vendor>/<theme>/<language>/css/, en is bereikbaar voor de browser.

De pub folder bestaat ook nog uit de “media” folder. Dit bevat alle media die door de gebruiker is geüpload via de admin.

Setup

De setup folder bevat een performance toolkit genaamt “jMeter” dat gebruikt wordt voor benchmarking, het meten van de performance.

Voor de rest bevat de setup folder ook de setup wizard die je aan het begin kan doorlopen om een Magento omgeving op te zetten.

Var

De var map bestaat uit de volgende mappen:

cache/	Alles wat gecached wordt (m.u.v. de page cache) wordt hierin opgeslagen.
composer_home/	Wordt gebruikt voor de setup wizard.
di/	Gecompilede dependency injectionconfiguratie voor alle modules.
generation/	Bevat code generation.
log/	Alle log bestanden (system.log, exception.log etc.) en reports.
page_cache/	Dit zijn gecachede pagina’s vanuit de full page cache. Als je varnish cache gebruikt dan zal dit map leeg zijn.
view_preprocessed	Alle .less bestanden worden gekopieerd naar de view_preprocessed/less folder en zet alle (geïmporteerde) paden in de less bestanden om naar relatieve paden om het werkelijk compilen naar css mogelijk te maken. Lees hier meer.

Vendor

Magento applicatie (Magento core modules en components) & third party modules wanneer je composer gebruikt	<root_dir>/vendor
Magento core modules, language packs en themes.	<root_dir>/vendor/magento
Module binnen de vendor map. Hierin is <Vendor> de folder dat de verzamelnaam is van de eigenaar / verkoper of makers van de module. Dit wordt weer vervolgd door een folder dat de naam is van de module. Bijv <root_dir>/vendor/company/module-widget. Deze benaming is meestal in kleine letters en staat niet gelijk aan de modules in de app/code folder.	<root_dir>/vendor/<Vendor>/<module_naam>/

Zodra je packages zoals Magento of third party modules, language packs of thema’s via composer inlaadt dan worden deze aan de vendor map toegevoegd. Er wordt geadviseerd om de vendor map dan ook niet aan te passen en ook niet mee te committen, maar eerder de composer.lock te committen. De vendor map staat dan ook standaard in de .gitignore.

Module

Magento 2 is opgebouwd uit modules, zo ook de Magento core. Wil je een module aanpassen (in code) dan zal je dit moeten doen door een module te maken. Modules in de “client” worden geplaatst in de <root>/app/code folder. Bijvoorbeeld <root>/app/code/Company/CustomModule/.

Modules kun je ook via composer (packages) inladen. Deze komen dan in <root>/vendor/<Vendor>/<module_naam>/. Bijvoorbeeld <root>/vendor/company/module-custom-module.

Klik hier voor een filmpje voor het maken van een module.

Voor alle componenten (Module, Theme, Language packs) zijn het volgende noodzakelijk:

registration.php	Het component moet geregistreerd worden via de Magento “ComponentRegistrar” class. ComponentRegistrar::register(ComponentRegistrar::MODULE, ‘<VendorName_ModuleName>’, __DIR__);   VendorName is de naam van de maker of bedrijf van de module en ModuleName is de naam van de module.
composer.json	Hierin staan de configuratie voor composer en de composer dependencies beschreven. De composer manager gebruikt dit bestand om te kijken welke versie de module is en kan de module en dependencies installeren.

<root_dir>/app/code/<VendorName>/

Lees hier en hier meer over module file structure.

Block	Bevat de PHP view classes (onderdeel van MVC) van de module. Om de Blocks, Controllers en Models van Magento te begrijpen dien je MVC te snappen. Lees hier meer over MVC.
Controller	Bevat de PHP controller classes (onderdeel van MVC) van de module.
etc	Bevat configuratie bestanden. De module.xml is een verplicht bestand en bevat de registratie van de module.
Model	Bevat de PHP model (onderdeel van MVC) classes van de module.
Setup	Bevat classes om de database structuur en data setup van de module te installeren of upgraden.

 

Api	Bevat PHP classes m.b.t. de Magento API.
Helper	Bevat PHP helper classes.
i18n	Bevat vertaal bestanden.
Plugin	Bevat benodigde plugins (interceptors).
view	Bevat static view files (css, js), design templates (.phtml), e-mail templates en layout xml bestanden.

Theme

Een theme bevat de grafische elementen van een Magento applicatie. Je kunt met een theme de look en feel van een shop aanpassen.

<theme_dir>/
|– <Vendor>_<Module>/
| |– web/
| | |– css/
| | | |– source/
| |– layout/
| | |– override/
| |– templates/
|– etc/
|– i18n/
|– media/
|– web/
| |– css/
| | |– source/
| |– fonts/
| |– images/
| |– js/
|– composer.json
|– registration.php
|– theme.xml

composer.json
registration.php	Dit is hetzelfde als voor modules. Voor themes: ComponentRegistrar::register(ComponentRegistrar::THEME, ‘frontend/Magento/luma’, __DIR__);
theme.xml
etc/	Bevat configuratie bestanden zoals de view.xml. Dit bestand bevat alle configuraties voor afbeeldingen, thumbnails, en de zoom functionaliteit (magnifier) op product afbeelding op de detailpagina.
i18n/	Bevat theme specifieke vertalingen.
media/	Bevat de preview afbeelding (preview.jpg).
web/	Bevat de static files. Dit zijn de assets zoals less, css, fonts, afbeeldingen en javascript bestanden.
web/css/source/	Bevat de less bestanden van een theme. In het _theme.less en _variables.less bestand plaats je variabelen en de less styling die de default overschrijven (als je theme van de blank theme override).
web/css/source/lib/	In deze folder kun je de less bestanden UI library (in lib/web/css/source/liv) overschrijven.
web/fonts/	De folder voor je theme fonts.
web/images/	De folder voor je theme afbeeldingen.
web/js/	De folder voor je theme javascript bestanden.
<Vendor>_<Module>/	De folder om assets, layout bestanden en/of templates van een module te overschrijven of uit te breiden.
<Vendor>_<Module>/web/	Hierin komen de uitbreidende of aangepaste assets zoals css, less en javascript van de module.
<Vendor>_<Module>/layout/	Hierin komen de layout.xml bestanden van de module. Hiermee vul je de layout.xml aan.
<Vendor>_<Module>/layout/override	In het mapje override, overschrijf je ook echt de layout bestanden. Er wordt afgeraden om dit te gebruiken.
<Vendor>_<Module>/templates/	Hier komen de template bestanden die je wil overschrijven van de module.

Theme inheritance

Theme inheritance is het overerven van theme’s en is gebaseerd op het fallback mechanisme van Magento. Als een bestand niet gevonden wordt in het huidige theme zal het systeem verder zoeken in de parent theme(s) of eventueel in modules of libraries waarvan het overerft wordt. Er is geen limiet aan het aantal te overerven theme’s.

De parent theme wordt gedeclareerd in de child theme’s theme.xml bestand. Bijvoorbeeld in app/design/frontend/OrangeCo/orange/theme.xml:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Orange</title>
    <parent>Magento/blank</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

Language pack

|– <VendorName>/<LanguagePackageName>
| |– composer.json
| |– nl_NL.csv
| |– language.xml
| |– LICENSE_AFL.txt
| |– LICENSE.txt
| |– registration.php

composer.json	Bevat composer configuratie en dependencies voor de language package.
language.xml	In de language.xml plaats je de configuratie van de language package zoals code, en naam. Je kunt language packages ook overerven van andere language packages (Language Inheritance).
registration.php	ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, ‘magento_de_de’, __DIR__);
nl_NL.csv	Dit bestand bestaat uit de taalcode en de landcode van de taal. Zo kun je ook een en_US of en_GB hebben.