Magento’s project & directory structure
It’s time to dive into Magento’s directory structure. After you install Magento, if you just look around at the files & folders, things can seem… daunting. Looking beyond the initial top-level directories, Magento has over 100,000 files and folders. This large number of directories stems from Magento's extensibility and flexibility features.
The amount of folders exist purely just to organize the codebase. You actually won’t be dealing with most of them, but it’s still important to know what the purpose is of each of these folders, if nothing else than to make you aware of what’s going on at a high-level.
Let’s look at the most important directories, which are app, pub, var and vendor.
Modules in app & vendor
The app
directory contains custom modules & themes that you’ll be building. The app/code
directory is for modules, and app/design
is for themes.
It may surprise you to find these directories empty in new projects but don't worry - it's totally normal because we haven't started coding yet. Now you might wonder, how does Magento function if these directories are empty?”
The vendor
directory contains all third-party modules installed with Composer, including Magento code. This is considered an “ephemeral” directory, which means that it is somewhat temporary. You shouldn’t ever place your files within this directory — that’s what the app
directory is for. When Magento is deployed to staging & production servers, the vendor
directory may be completely rebuilt from the configuration defined within the composer.json
file, which is why we don’t place files here that are meant to stick around.
The vendor/magento
directory contains all of the modules related to Magento, and they start with module-
. Within each module directory you’ll find common subdirectories such as Block
, Controller
, etc
, Model
, and so on. Magento uniformly uses naming conventions, ensuring files are predictably placed. This is particularly crucial when navigating Magento's extensive filesystem.
The Magento Framework
The Magento Framework isn’t considered a module, but a separate set of core PHP classes and interfaces that provide the foundational functionality for building Magento modules.
The framework is located within the vendor/magento/framework
directory, and contains code for things like routing, dependency injection, the data layer, events, plugins, caching, logging, configuration, and many other lower-level components. These classes don’t directly implement functionality, but provide an API and tools for modules to build on top of.
Much like other files in the vendor
directory, you'll never modify these files. However, you will frequently reference them when building out your own modules.
Public Assets
The pub
directory is known as the “web root”, which is the main directory the web server should point to. Rather than pointing to an index.php
file in the core of your app, it’s a common practice to segregate web requests within a public directory. Segregating web requests enhances security by ensuring they can't access private files in the filesystem. Abiding by this best practice, Magento designates pub/index.php
as the actual web entry point.
This setup means that the web server can't access static assets, like images or CSS, unless they're housed in the pub
directory. Magento uses pub/static
as the main directory that contains CSS and JavaScript that is requested by the server. These files are also generated from the source files located in app/design
and vendor
in a process called “static content deployment”. This just means that these files are generated from a script runs during code deployments, and keeping it separated like this will decrease page loading speeds.
Transient Data
The var
directory contains generated data that changes often such as cache files, logs, and session files. This is a truly ephemeral directory and is just meant to store transient data. It’s best practice to have a separate directory like this for this temp data.
Other Folders
The other folders aren’t really used on a day-to-day basis, so you should breath a sigh of relief that you only really need to worry about those few main folders we talked about. While these important directories form the core, feel free to explore the rest of the filesystem, including the bin
directory with the bin/magento
CLI tool, the dev
directory for unit tests, the lib
directory for other frameworks, and the setup
directory with install & upgrade scripts.
But don’t get overwhelmed with Magento’s giant codebase. Knowing about app
, pub
, var
and vendor
will usually be enough to get you through 95% of your daily Magento duties.