Greetings!  This is installment number one of the the exiting Magento Custom Module series.  There’s basically two paths to the end of the fairytale:

Path 1: You follow this series and get down and dirty with Magento, learning a lot along the way.

Path 2: You go out and download the Module Creator (http://www.magentocommerce.com/wiki/custom_module_with_custom_database_table) and head straight to GO!

Your choice!

Note: Magento is an MVC application so I’m going to assume you have a basic understanding of MVC.  Also, Magento is built (I believe) on the Zend framework, so there’s some Zend specific syntax that I’m also not going to dive into.  Huzzzah!

The Problem:

You need to create a custom Module in Magento!  Why…?  Hell, I don’t know; you just do.  That’s enough of that, let’s get down to it.

The Solution:

All of your customizations need to go into the [root]\app\code\local folder.  This is where Magento expects to find them and it’s also a factor in maintaining your upgrade path.  When the next version of Magento is released you’ll be able to backup your “local” folder and blow away everything else.

Before we get too far into this let’s setup our development environment, go to:
Admin -> System -> Cache Management: Cache Control – All Cache = Disable

This will save you many hours of self-torture while you’re developing.

A couple of other developer settings that I’ve found helpful:
Admin -> System -> Configuration -> Developer: Debug – Profiler = yes
Log Settings – Enabled = yes

Now open up [root]\index.php and at the very end you’ll see three lines that are commented out; un-comment them and save.

Finally, turn SEO friendly URLs on:
Admin -> System -> Configuration -> Web: Search Engine Optimization – Use Web Server Rewrites = Yes

All of the URLs that I’ll be presenting as examples below assume that SEO friendly URLs are enabled.

Magento is now correctly configured for development so let’s dive into building a custom module.

Sample file structure:
[root]\app\code\local\{Namespace}\{Modulename}
[root]\app\code\local\{Namespace}\{Modulename}\controllers
[root]\app\code\local\{Namespace}\{Modulename}\etc
[root]\app\code\local\{Namespace}\{Modulename}\etc\config.xml
[root]\app\code\local\{Namespace}\{Modulename}\Helper
[root]\app\code\local\{Namespace}\{Modulename}\Helper\Data.php
[root]\app\code\local\{Namespace}\{Modulename}\Model
[root]\app\code\local\{Namespace}\{Modulename}\{Modulename}.php

{Namespace} is a user defined variable.  Basically it’s just a mechanism that allows the user to create disparate classes that would otherwise have the same names.
{Modulename} this is the name of your module.

For my examples I’m going to use “Spinonesolutions” as my namespace and “Helloworld” as my Module.  I’m not entirely sure if it matters or not, but as a general rule I always capitalize the first letter and leave the rest lower case.  Don’t use underscores in your names either, we’ll see why later.

controllers is where all the controllers go, crazy right?  I’ll get into the controller structure in another part of this series.  For now a sample will suffice.

<?php
//IndexController is the default controller
//EG: http://localhost/spinonesolutions/
//Notice there's no parameters being passed as a parameter (Nothing after trailing "/")
//IndexController will be called since it's the default.
//"spinonesolutions" is the frontname as defined in confg.xml
class Spinonesolutions_Helloworld_IndexController extends Mage_Core_Controller_Front_Action {
  //indexAction is the default Action for any controller
  function indexAction() {
    echo "indexAction";
    $helloworld = Mage::getModel("spinonesolutions_helloworld/helloworld");
    $helloworld->helloworld("helloworld");
  }
}

Data.php is just a helper file for the Magento internals, I’m not exactly sure what it does but it appears to be exactly the same in every module except for its class definition.

<?php
class Spinonesolutions_Helloworld_Helper_Data extends Mage_Core_Helper_Abstract {

}

Model holds all of the models for your module.  It’s customary to name your main model after your {Modulename}.  You’ll most likely have at least one model and if you browse through the Magento core you’ll notice that most modules contain many models.

<?php
class Spinonesolutions_Helloworld_Model_Helloworld extends Varien_Object {
  function __construct() {
    parent::__construct();
  }

  function helloworld($arg) {
    echo "<br>Hello World! My argument is : " . $arg;
  }
}

config.xml is where you connect all your code up to Magento.  There’s a lot of voodoo going on in here and I’m not entirely sure how it all works.  I might even write a full post on the config.xml as a forthcoming part of this series.

<?xml version="1.0" encoding="UTF-8" ?>
<config>
 <modules>
   <Spinonesolutions_Helloworld>
   <version>0.1.0</version>
   </Spinonesolutions_Helloworld>
 </modules>
 <frontend>
   <routers>
     <spinonesolutions>    <!-- I make this match my front name but I'm not sure it matters -->
       <use>standard</use>    <!-- Use standard routing as opposed to admin.  IE: frontend vs admin -->
       <args>
         <module>Spinonesolutions_Helloworld</module>    <!-- The module to search for controllers -->
         <frontName>spinonesolutions</frontName>    <!-- The first descriminator in the path.  "spinonesolutions" in http://localhost/spinonesolutions/ -->
       </args>
     </spinonesolutions>
   </routers>
 </frontend>
 <global>
   <models>
     <spinonesolutions_helloworld>    <!-- This is used when istanting your Model EG: Mage::getModel("spinonesolutions_helloworld/hellworld") -->
       <class>Spinonesolutions_Helloworld_Model</class>    <!-- That class to use when isntanting objects of type above. -->
     </spinonesolutions_helloworld>
   </models>
 </global>
</config>

That takes care of all the code needed in the module directory. There’s one more configuration file we need to create and it’s an exception to the local folder rule:
[root]\app\etc\modules\{Namespace}_{Modulename}.xml

<?xml version="1.0"?>
<config>
 <modules>
   <Spinonesolutions_Helloworld>
     <active>true</active>
     <codePool>local</codePool>
   </Spinonesolutions_Helloworld>
 </modules>
</config>

This file tells Magento that there’s a new module out there that it needs to load.  Alternatively, you can name your file [root]\app\etc\modules\{Namespace}_All.xml to tell Magento to load up all the modules in that namespace.

Once you have this file in place you can navigate to Admin->System -> Configuration -> Advanced and you should see your module enabled here.

You now have a functioning custom module, hurray!

Download the source – Helloworld

1. Part I : Custom Module
2. Part II : Models
3. Part III : Controllers
4. Part IV : Extending Models
5. Part V : Data Layer