Magento Dev Best Practices: Module Naming Conventions

In Magento 1.x modules, there’s the potential to have files and folders dispersed all over the Magento file structure. Much of this will be resolved in Magento 2, but we don’t know when that will happen yet, and we will still be supporting and writing for 1.x for a while after 2 is released. Given that, I’d like to suggest some helpful file/folder naming conventions:

Module Name

Modules consist of a 2-part name: Namespace_Modulename. For the purpose of this article (and for all the modules I write for the community) I will be using a module named Prattski_Example, which I would put in app/code/community/Prattski/Example.

Module Blocks, Helpers, and Models

In your module’s config.xml file, you get to define the namespace used when calling blocks, helpers, and models. In many cases, people will only use the module name and exclude the module namespace. If you only use the module name, calling a model for this module would look like this: Mage::getModel(‘example/modelname’). I always suggest making it a convention to always use the namespace and module name. That way in the code, there’s no question as to what module is being used. In that case, calling the model would look like this: Mage::getModel(‘prattski_example/modelname’).

Layout XML Files

If your module introduces a new layout xml file, I always name it the full namespace and module name. As with the rest of these conventions, it makes determining which modules these files belong to really simple. If I needed a layout xml file for my module, I would name it like this: app/design/frontend/base/default/layout/prattski_example.xml

Template Folders

Just like with the above layout xml files, I always name my folders with the full namespace and module name. If I was adding some frontend template files, I would put them here: app/design/frontend/base/default/template/prattski_example/

Conclusion

The whole point here is making the code/files/folders in such a way that it keeps things more organized and clear. If you include the full module namespace and module name, it really doesn’t get much more clear what modules are responsible for your different files/folders.

If you are working on a project and creating a lot of modules for it, you’ll notice some nice benefits of all of this as well. All of your modules layout files and template folders will all be in the same place together, making finding what you are looking for much easier and more organized.

This entry was posted in Best Practices, Magento. Bookmark the permalink.

7 Responses to Magento Dev Best Practices: Module Naming Conventions

  1. Pingback: Mejores practicas para desarrollo de extensiones en Magento @MagentoExtensiones

  2. Tim says:

    To my mind the idea of using namespace_module format for defining sortcode for models/blocks/helpers is not that obvious.

    On one hand it was designed as a shortcut and can save you some grey hair while working with long namespaces/module names. On the other hand full naming really makes it more transparent and also will prepare you in some way for shorcodes deprecation in M2.

    So to me it is hard to call it “a must”.

  3. I do agree on module-specific directories with beeplogic and Fabrizio for the very same reasons. Good list Josh, should be standard for all Magento developers.

  4. Hi,

    thank you for this blog post.

    I’d suggest to always have a module specific directory for layout files as well (also for js, skin, …and everything). Even if it is only one single file:

    app/design/frontend/base/default/layout/prattski_example/prattski_example.xml
    instead of app/design/frontend/base/default/layout/prattski_example.xml

    This looks like some overhead, but I think it’s much cleaner and makes working with modman easier, because you won’t care about files anymore but you will handle custom module specific folders everywhere instead.

    Bye, and have a nice day,

    Fabrizio

    • Josh Pratt says:

      Wether or not you choose to use a directory, we agree it’s a good idea to use the full module namespace and module name :)

  5. beeplogic says:

    Good stuff, although I create a directory for the layout files: layout/prattski/example.xml. Matter of preference and not much of a difference.

    • Josh Pratt says:

      Thanks @beeplogic. If my modules needed more than 1 layout file for some reason, then I would use a folder. None of mine ever have, so I found it easier to just have the file in the layout directory.