I was trying to understand how all the various Magento internal developer concepts fit together, from the perspective of responding to a HTTP request to the web server.  I wrote this up to make sure I understood the concepts. Let me know if I got anything wrong! I am sharing in case useful to anyone else. This is based on Magento 1 – there are likely changes coming in Magento 2, but they are unlikely to change the overall flow significantly.

This description purposely leaves out details to try and keep this short.  I am not trying to define all the different concepts – just give my perspective on how all the different concepts fit together.

• A HTTP request arrives at web server, which passes it to index.php.
• The path structure of the URL is <front-name>/<controller>/<action>
• Index.php finds a router that recognizes the URL.  Most people don’t need to worry about what a router is, so skipping it here.  (The code loops here to process forward() requests below, URL rewrites, etc.)
• The <front-name> from the URL is mapped (by a router) to a module name.  This allows nicer looking URLs if you want them.
• The module name and <controller> combined identify which controller PHP class to use.
• The <action> identifies which method of the controller to call.  (If <action> is view, the method viewAction() will be called.)
• Inside an action method, one of several things typically occur
  • The forward() method tells Magento to start again using a different path.  It allows a controller to say “that other controller does this – go use that code instead”.
  • The redirect() method tells Magento to tell the browser to go to a different path.  This can be useful with POST requests. After processing a POST (e.g. submitting an order) by redirecting to a ‘view’ style URL it is safe for the user to hit “reload” without redoing the POST by accident.
  • If the action wants to display a page to the user, it will typically call loadLayout(), initLayoutMessages(), and renderLayout().  The layout name by default is worked out from the module name (not front-name), controller name, and action name.
• The action method for POST like requests calls the code to perform the action (like “add item to cart” or “save my postal address”).
• A layout is built by layering all the layout updates of all loaded modules, for a specific layout name.  There is not a single file declaring what a page looks like.  Magento uses update instructions that are layered on top of each other to form the final page layout, as I discussed previously.  This makes it easier to add and remove modules from a site without major redesign.
• There are “page layouts” that define whether the page should be shown as 2 column or 3 column etc. which get referenced when a whole page is being rendered.
• Layouts reference blocks and assemble them to form a complete HTML page.  Blocks are implemented by PHP classes.
• Widgets are a type of block that is parameterized, and you can have multiple instances in a single page.
• Many blocks use a PHTML template file to generate HTML for that block.  The $this variable for a PHTML file is set to the block instance so it can make calls of methods in the block.
• Templates reference text to embed in a page using the __() function, which looks up the real string to use based on Locale.
• Blocks can call PHP helper classes (collections of utility methods) by registered helper name (registered by the module that provides the helper methods).
• Helpers reference [Domain] Models – PHP classes implementing core business logic.
• [Domain] Model classes reference Resource Model classes if they need to do database access.

So, if you want a completely new page for the user to experience

• You need a new controller class.
• You need a layout handle (layout plus set of layout updates from different modules) for the overall page.
• You need to write any special blocks for content you want on that page (plus any controllers to support those blocks).
• You need to write helpers, domain models, resource models etc if needed by blocks for the special purpose of the page.
• You need to adjust various little config files to wire everything together.

Of course after finishing writing this, someone pointed me at some other excellent articles around the place.  That’s OK – I wrote this up for my own understanding, and sometimes reading the same information presented in multiple ways makes this clearer.  Here are the links:

• http://alanstorm.com/magento_controller_hello_world
• http://alanstorm.com/layouts_blocks_and_templates
• More in-depth http://alanstorm.com/category/magento#dispatch
• Flow as a poster: http://blog.belvg.com/magento-request-flow.html
• http://www.amicontech.com/blog/magento-file-structure-and-workflow/

Disclaimer: I work for eBay, Magento is owned by eBay, but any opinions here are my own.