Over the past summer, I’ve spent a lot of time working with e-commerce software Magento for several clients. Its biggest appeal is also its worst downside for developers: Every part of it is completely extensible without ever needing to touch the core code. That’s great, as long as you don’t look too closely at how that’s actually achieved. I’m not here to rant, though–with a little luck, I’ll save you some of the headaches I ran into when I was starting off.

Fact is, Magento can and probably will be overwhelming on your first time digging through the code, especially if you’re not familiar with the Zend Framework. But then, it does have more than 9,300 files before it’s even installed…

Almost everything you will need to deal with, whether you’re a designer or a developer, is in the /app folder.

/app/etc contains Magento’s basic configuration.

/app/code contains all of Magento’s code, split up by source [community, core or local], publisher, and module. All of the core Magento code is in /app/code/core/Mage. If you ever plan on upgrading, you probably shouldn’t change anything in that folder. If you install a Magento Connect extension, you’ll find the code for it in /app/code/community.

Within each module there are a bunch more subfolders: Block, controllers, etc, Helper, Model, and sql. If you plan on creating your own module you’ll need to understand this better, and there are guides for that; for now, it’s probably enough to know that most of the actual code can be found in the Block folder.

All these underscores… what do they mean? If you’ve glanced at any of the actual code, you might’ve noticed that class names seem like long, repetitive nonsense. In fact, the class name tells you exactly where you can find it. “Mage_Catalog_Block_Navigation” is in the Mage folder, in the Catalog module, it’s a block, and it’s called Navigation. So, you’ll find it at /app/code/core/Mage/Catalog/Block/navigation.php. It works the same way for any other publisher, module, type and class. If the class name has more than four parts, such as “Mage_Catalog_Model_Category_Api_V2″, look for subfolders with those names. That class is at /app/code/core/Mage/Catalog/Model/Category/Api/V2.php.

/app/design contains all of Magento’s templates, split up by frontend/backend, then by base/default, then by theme name and finally by module [mostly corresponding to each of the modules within the code section, above]. If you are working on a new site, one of the first things you’ll want to do is copy the modules you’re working on from /app/design/frontend/base/default into /app/design/frontend/default/default so that you can change the templates without worrying about upgrades.

Within each theme folder there are as many as four subfolders: etc, layout, locale, and template.

  • etc contains basic config files for the theme.
  • layout contains configuration files for each module, which you can use to include blocks and other templates, and in some cases do a whole lot more.
  • locale contains language files, allowing you to translate pages [or change words] without touching the actual templates.
  • template contains the actual HTML for each module, split up into a number of .phtml files.

Looking for the page wrapper? That’s in /app/design/frontend/*/*/template/page. Inner-page templates are there; the header, footer and other includes are in the html subfolder.

If you’re going to change any styles, there’s one more place that will interest you…

/skin contains all CSS, Javascript and image files. The folder structure is exactly like /app/design–follow the folder tree until you get to the files for your skin.

There are three more things you should know before you dig in.

First, Magento’s caches are all enabled by default. I don’t know how many hours I’ve burnt trying to figure out why the heck changes I made weren’t doing what they should… just to realize that it was being cached. You can [and should] disable these while you’re working on the site in Admin > System > Cache Management. Select all, actions -> disable, submit.

Second, there’s an invaluable free extension called the Developer Toolbar. It adds a toolbar to the bottom of the site with a number of handy links that control various settings in Magento. One in particular is incredibly useful: enabling “Frontend Hints” shows you exactly where in the code and in the templates that every single part of the page is coming from. Don’t try to search for where something on the page is coming from–enable the frontend hints and you should be able to figure it out within ten seconds.

Third, everything in Magento will inherit. For templates, Magento will look for a template file within your specific theme. If that doesn’t exist, it’ll try to load it from the default theme; if that doesn’t exist, it’ll fall back to the base skin. The same thing applies to config, layout and locale files. Similarly with classes: You can overload any core class through the community or local folders.

Hopefully this is enough to get you started. I’m not a Magento genius, but if something is unclear, or if you have a specific question, I’d be glad to try helping.