Magento 1.x Directory Structure Guide

Because it might not make sense at first, second, third, nth, ... glances.

This past week, I’ve been taking a crash-course in Magento 1.x. I’ve been thoroughly impressed that it runs a fairly sophisticated ORM that implements an ActiveRecord-like API in an otherwise DataMapped pattern. It only calls a record’s resource handler (which saves the data to the database) when you call a row’s save() method. Pretty cool stuff.

But holy moly, what a complex, spaghetti-like system.

It took me forever (nearly 4 solid days) to finally figure out where I could find a module’s code, view files, and configuration. So I decided to share the guide I wrote up on it.

TLDR; Magento makes you put your modules in three primary places:

  • Definition: app/etc/modules/[Your Module].xml
  • Code: app/code/[Code Pool]/[Namespace]/[Module Name]/
  • Views: app/design/[Area]/[Store]/(layout|template)

Magento is a system for building and managing what it calls modules (which, by default, form an e-commerce website). Modules are collections of functionality, blocks, and models that make up your website. Modules live in namespaces, which describe bundles of modules. Namespaces, in turn, all live in code pools, which house collections of namespaces that can be overwritten by other code pools in a linear sequence.

When a module is called, Magento looks for the module in the code pools in the following order. If it can’t find the module in the first code pool, it tries the second, then the third, and so on, throwing an error if it cannot find it.

  1. (Any custom code pools defined in the project)
  2. Local
  3. Community
  4. Core

So where are my modules?!

Modules are spread across the filesystem in Magento.

First, a module is defined at the most basic level in:

app/etc/modules/[Your Module].xml

Magento won’t be able to find your module if you don’t define its configuration. Through configuration here, you can usually figure out where the rest of the module lives.

Cool, so where’s the code?

The actual code for a model (that is, the Controllers, Observers, Methods, Collections, Resources, and so on) is in:

app/code/[Code Pool]/[Namespace]/[Module Name]/

Your code pool will most likely be local, but could be custom ones if set by your configuration. Node that in your module’s namespace, some directories are capitalized, others aren’t. This is because when Magento builds paths with its autoloading function, everything in the scope of the autoloader will begin with a capital letter, everything outside the scope of the autoloader (and typically loaded through Magento internals) begin with lowercase letters.

Common directories and their purposes in your code pool (note the casing):

            Block/        block template classes
            controllers/    controller files
            data/        data to be loaded to the DB
            etc/        module configuration XML files
            Helper/
            Model/        model classes
            Model/Resource/    resources classes for models
            Model/Resource/Collection    collection classes for models
            sql/        module installation and upgrade files

You will likely spend the bulk of your time in this directory.

The view files for your module can live in a number of places, but they are centrally located in:

app/design/[Area]/[Store]/

There are two areas your templates and block definition files live: frontend, and adminhtml. As you may expect, frontend contains files that are user/customer-facing, while adminhtml are files that correspond to behavior in the administration menu.

The store is the store that you define in Magento’s store manager. Each store can have its own templates, and fall back in a linear fashion similar to code pools. The order that Magento searches for templates and blocks is: Store > Default > Base. If it cannot locate the designated layout files in base, it throws a 404.

Your module’s blocks are defined in separate XML files from their templates within your design namespace:

app/design/[Area]/[Store]/layout/[Your Module].xml
                       /template/[Your Module]/

The XML file is the configuration for your blocks that stitch together your block code and templates, and your templates directory contains all of the block’s .phtml file.