Understanding the file system in Magento 2

Understanding the file system in Magento 2
Magento 2 Exam Series - Magento Architecture & Customization Techniques: Determine how to locate different types of files in Magento.

Published by Rick Daalhuizen

One of the first things you can do to get started with component development is to understand and set up the file system. Each type of component has a different file structure, although all components require certain files. In addition, you can choose the component root directory to start development. The following sections have more information. - Magento DevDocs - About component file structure

Where to find Javascript and PHTML files?

  • view/frontend/web/js
  • view/frontend/requirejs-config.js
  • view/frontend/layout
  • view/frontend/templates

Component root directory

A component root directory can take place in 2 places, /app and /vendor, and it’s the top-level directory for that component.

  1. /app
    • Modules - app/code.
    • Storefront themes - app/design/frontend.
    • Admin themes - app/design/adminhtml.
    • Language packages - app/i18n.
  2. /vendor
    • Modules - vendor/[vendor-name]/[module-module-name]
    • Storefront themes - vendor/[vendor]/theme-[area]-[theme-name]
    • Admin themes - vendor/[vendor-name]/theme-adminhtml-[theme-name]
    • Language packages - vendor/[vendor-name]/language-en_us

Any third party components (and the Magento application itself) are downloaded and stored under the vendor directory. If you are using Git to manage a project, this directory is typically added to the .gitignore file. Therefore, we recommend you do your customization work in app/code, not vendor. – Magento DevDocs - Create your component file structure

Component file structure

A component requires a registration.php, etc/module.xml and a composer.json file. That’s enough for Magento 2 to know that a component exist. See my previous blog about Understanding Magento 2 Modules-Bsed architecture - Module registration

The following files and folders are common to see in Magento 2 Module (Component).

  • Api - Any PHP classes exposed to the API (Service and Data Service contracts).
  • Block - PHP view classes as part of Model View Controller(MVC) vertical implementation of module logic.
  • Console - Console commands
  • Controller - PHP controller classes as part of MVC vertical implementation of module logic.
  • Controller/Adminhtml - Admin controllers
  • Cron - Cron job classes
  • etc - Configuration files; in particular, module.xml, which is required.
  • Helper - Helpers
  • i18n - Localization files in CSV format
  • Model - PHP model classes as part of MVC vertical implementation of module logic.
  • Model/ResourceModel - Database interactions
  • Observer - Event listeners
  • Plugin - Contains any needed plug-ins.
  • Setup - Classes for module database structure and data setup which are invoked when installing or upgrading.
  • Test - Unit tests
  • Ui - UI component classes
  • view - View files, including static view files, design templates, email templates, and layout files.
    • view/{area}/email
    • view/{area}/layout
    • view/{area}/templates
    • view/{area}/ui_component
    • view/{area}/ui_component/templates
    • view/{area}/web
    • view/{area}/web/template
    • view/{area}/requirejs-config.js

Theme file structure

A Magento theme is usually located in app/design/frontend/[Vendor]/, or in vendor/[vendor]/theme-[area]-[theme-name] but can technically be placed anywhere. However, a theme must be placed in a separate folder.

A typical magento theme folder structure looks like this:

[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

To create a theme you basically only need the following, these are required to create a theme.

  • Composer.json - Describes the theme dependencies and metadata. Is required if your theme is a composer package.
  • Registration.php - Is required to register your theme
  • Theme.xml - It contains the basic meta-information, like the theme title and the parent theme name

The following folders are optional:

  • layout/ - Layout files which extend the default module or parent theme layouts.
  • layout/override/base - Layouts that override the default module layouts.
  • layout/override/<parent_theme> - Layouts that override the parent theme layouts for the module.
  • templates - This directory contains theme templates which override the default module templates or parent theme templates for this module. Custom templates are also stored in this directory.
  • etc/view.xml - This file contains configuration for all storefront product images and thumbnails.
  • i18n - .csv files with translations.
  • media - This directory contains a theme preview (a screenshot of your theme).
  • web - Static files that can be loaded directly from the frontend.
    • web/fonts - Theme fonts.
    • web/images - Images that are used in this theme.
    • web/js - Theme JavaScript files.
    • web/css - Theme Less files
      • web/css/source - This directory contains theme less configuration files that invoke mixins for global elements from the Magento UI library, and theme.less file which overrides the default variables values.
      • web/css/source/lib - View files that override the UI library files stored in lib/web/css/source/lib