With so many people also searching for a clever solution, I decided disabling the feature was an unacceptable solution, and took the challenge.

First you have to enable the “Use categories path for product URLs” feature under System > Configuration > Catalog > Search Engine Optimization.

Use categories path for product URLs – This determines how the URL Rewrites autogenerate. If you choose Yes, the URL rewrite for products will include the associated category, and a separate rewrite will generate for each associated category. If you choose No, the URL Rewrites will include only the product name, and there will be only one rewrite, regardless of how many categories the product is associated to.

Once this feature is enabled, you’ll be to use any of these URLs to visit the same product page:

• /catalog/product/view/id/<product_id>
  example: http://www.domain.tld/catalog/product/view/id/6
  Internal to Magento; never actually exposed.

• /catalog/product/view/id/<product_id>/category/<category_id>
  example: http://www.domain.tld/catalog/product/view/id/6/category/10
  Internal to Magento; never actually exposed.

• /name-of-product
  example: http://www.domain.tld/super-dee-duper-tent-1000-olive
  Normally used on the front page, in content blocks, or anywhere other than a category page. This is because without being on a category page, Magento doesn’t know which category would be appropriate to display in the URL (since it provides the ability to have multiple categories per product). Therefore it opts to not display any category at all. A bad decision in my opinion.

• /category-1/sub-category-1/name-of-product
  example: http://www.domain.tld/sporting-goods/camping-hiking/super-dee-duper-tent-1000-olive
  Used from category pages.

• /category-2/name-of-product
  example: http://www.domain.tld/affordable-housing/super-dee-duper-tent-1000-olive
  Used from category pages.

• etc.
  Depending on how many categories per product.

Personally, I don’t like my products having multiple URLs. Between the front page and the category pages, two separate URLs are introduced to GoogleBot as it crawls through the pages. Even though you may not be seriously penalized for duplicate content, which page do you want to appear in Google SERPs? Which one do you want your customers to link at? You’re splitting your link juice and causing confusion.

When I saw this feature for the first time, all I really expected was a single URL like:

http://www.domain.tld/sporting-goods/camping-hiking/super-dee-duper-tent-1000-olive

Well, it took about four hours to find, but I finally came up with a patch to Magento core that delivers this result. Check it out below in unified diff / patch file format:

Index: app/code/core/Mage/Catalog/Model/Resource/Eav/Mysql4/Product/Collection.php
===================================================================
--- app/code/core/Mage/Catalog/Model/Resource/Eav/Mysql4/Product/Collection.php	(revision 2102)
+++ app/code/core/Mage/Catalog/Model/Resource/Eav/Mysql4/Product/Collection.php	(working copy)
@@ -553,7 +553,11 @@
                 ->from($this->getTable('core/url_rewrite'), array('product_id', 'request_path'))
                 ->where('store_id=?', Mage::app()->getStore()->getId())
                 ->where('is_system=?', 1)
-                ->where('category_id=? OR category_id is NULL', $this->_urlRewriteCategory)
+//                excluding this clause to facilitate one URL per product, and one that includes the category
+//                if a product has multiple categories, the first one (by category_id) will be used
+//                in most cases you'll probably only have one category because you only want one page per product for SEO reasons
+//                for maximum link juice, no possibility of duplicate content, and a less confusing store
+//                ->where('category_id=? OR category_id is NULL', $this->_urlRewriteCategory)
                 ->where('product_id IN(?)', $productIds)
                 ->order('category_id DESC'); // more priority is data with category id
             $urlRewrites = array();

In my setup, each product only has one category. Although this will also work if you specify multiple categories per product, you won’t have complete control over which category is used for the official link.

So, rather than manually attempting to reorder 68 categories across 3 levels one-by-one using the tools provided in the Magento back-end, I decided to write a simple MySQL script that would do it all for me automatically. Here it is, for anyone else who may be running into this problem.

DISCLAIMER: This script is provided as-is with no warranty or support. It works for me on the latest version of Magento [as of this writing] which is v1.2.1.2, but not guaranteed to work forever. As always, it is strongly recommended to backup first and test this in a development environment before you attempt to apply it to your live server. You alone are responsible for any damages it may cause in your hands. Use at your own risk.

# adjusted order of categories
SET # init vars, set defaults
 @pos = 0,
 @last_parent = 0,
 @last_level = 0
;
DROP TABLE IF EXISTS cce_adjusted;
CREATE TEMPORARY TABLE cce_adjusted # output to temp table for review before commit
SELECT
 a.entity_id,
 a.level,
 a.parent_id,
 a.value,
 a.position,
 @pos := (IF((@last_parent != a.parent_id) OR (@last_level != a.level), 0, @pos) + 1) `new_position`,
 @last_level `last_level`,
 @last_parent `last_parent`,
 @last_level := CAST(a.level AS UNSIGNED) `new_last_level`,
 @last_parent := CAST(a.parent_id AS UNSIGNED) `new_last_parent`
FROM (
 SELECT
  cce.entity_id,
  cce.level,
  cce.parent_id,
  ccev.value,
  cce.position
 FROM catalog_category_entity cce
 INNER JOIN catalog_category_entity_varchar ccev
  ON cce.entity_id = ccev.entity_id
   AND ccev.store_id = 0 # Root Store
   AND ccev.attribute_id = 31 # Category Name
 ORDER BY cce.level, cce.parent_id, ccev.value
) a
;
SELECT * FROM cce_adjusted;

/*
# commit changes
UPDATE catalog_category_entity cce
INNER JOIN cce_adjusted a
 ON cce.entity_id = a.entity_id
SET cce.position = a.new_position
;
*/

/*
# current order of categories
SELECT
 cce.entity_id,
 cce.level,
 cce.position,
 cce.parent_id,
 ccev.value,
 1 `new_position`
FROM catalog_category_entity cce
INNER JOIN catalog_category_entity_varchar ccev
 ON cce.entity_id = ccev.entity_id
  AND ccev.store_id = 0 # Root Store
  AND ccev.attribute_id = 31 # Category Name
ORDER BY cce.level, IF(cce.level<3, cce.position, cce.parent_id), cce.position
*/

I like to save it as a .sql file and execute it in a MySQL GUI like SQLYog whenever I need, but I suppose it would also work from the CLI if you were applying it to your live server via SSH. The first section previews the changes. The middle section saves changes, and is commented out to prevent accidental changes. You would just uncomment the middle part to make it work. The last section that is commented-out is just for debugging, in case you need to make any changes to this script to get it to work with a customized/non-standard Magento configuration. Also, remember to reset your cache if you have it enabled after you apply this.

Drop me a comment if this script saved you time or you found it useful in any way. Maybe link at it if you think others may also find it useful. It's all that I ask! Keep the open-source spirit alive. Peace.

This guide is meant to be a quick-start supplement for the official Magento Design Guide, and not a replacement for it. It assumes you are already familiar with and have completed themes for Drupal and/or WordPress.

Introduction: Working with Magento

The first thing you’ll notice about Magento is its size: 15.7MB zipped, and 58.8MB unpacked: 7,231 files across 2,482 folders (as of Magento 1.2.0.1). This may be one of the largest web applications you’ve worked with–and not only you, but your IDE, too. Don’t even think about letting Notepad++, UltraEdit, Textpad, or one of those programs touch this baby. The “Made with Notepad” days are long gone, man. Get yourself a decent IDE. I even had to upgrade my Eclipse IDE to 2.1.0M5 “Galileo” and switch my PHP stack to Zend Core 2.5 just to handle Magento without slowness and crashing.

The second thing you’ll notice is that it’s fully object-oriented with PHP5, and if there seems to be no rhyme or reason to the directory hierarchy, you may also need to take some time to introduce yourself to Zend Framework for PHP. What’s really happening here is Varien is using architectural and design patterns you’ve probably seen before but never fully understood such as Model View Controller (MVC), the Front Controller pattern implemented by Zend_Controller object, the Two Step View pattern, the Application Controller pattern, etc.

Later when you begin writing Magento extensions, you’ll also notice you don’t have to write any SQL anymore because Zend_Db implements the Data Mapper pattern.

So for now bookmark the Zend Framework Reference Guide, Designer’s Guide to Magento, Magento Documentation, and lets get started.

Getting Started: Jump-start with pre-existing Blank Theme

The first thing I would do is download the Blank Theme from Magento Connect; it’s a good blank canvas starting point for theme developers. As I recall, the Drupal community also had one of these–it was called Zen by John Wilkins. In WordPress I suppose it is the equivalent to the Kubrick theme by Michael Heilemann. If you are building your own standards-compliant theme, you will find it much easier to start with Blank Theme than to start with the default Tealo theme packaged with Magento core. This theme is also well commented.

Before we go any further, I want to emphasize that one primary difference you’ll realize with Magento is that there are many many pages you or your client may decide to potentially theme individually. (e.g. front page (2 col), catalog pages (3 col), product pages (2 col), about pages (1 col), my cart, checkout–even the email templates are individually themed) Not only that, but there are over 270 unique XHTML template files as well as the CSS for each content block (e.g. my cart, compare products, newsletter, advertisements, etc.) which come with the stock installation of Magento.

So when quoting you have to take into consideration just how far you’re planning on deviating from the Magento defaults because it could potentially take you a considerable amount of time to customize all these things. In most cases, though, clients only want to pay to have up to five unique pages designed, so it’s no biggie to reuse a lot of the default code on the rest of the pages. By starting with the Blank Theme, we already have all of the base XHTML and CSS we’re going to need, and all we have to do is write the code to override it and only where change is required.

Terminology: Identifying the different LEGO™ pieces

So the Magento Design Guide does a pretty good job of explaining this but I want to draw some comparisons using proportional analogies. (i.e. “A in Magento is to B in Drupal and C in WordPress”)

• A “Theme” in Magento is just like any theme in Drupal or WordPress, with two exceptions. One, the front-end and back-end of Magento are treated as separate themes. And two, for security reasons each theme is split into a public directory (e.g. css, js, images, and index.php front controller) and private directory (e.g. all .php files including XHTML templates which are saved as .phtml files).

• “Structural Blocks” in Magento are known as regions in Drupal, and similar to sidebars in WordPress.

• “Content Blocks” in Magento are just called blocks in Drupal, and widgets in WordPress. However, unlike Drupal and WordPress, they cannot yet be positioned on the page using simple JavaScript drag-and-drop techniques. They can’t even be specified with weights like in Drupal 5. They are specified only in .XML layout files, which are part of your theme, and can optionally be assigned an order which is an integer but are otherwise displayed in the order that the .XML files are included. However, unlike Drupal and WordPress where blocks and widgets would normally be relegated to only sidebars and you cannot control the position of the actual content, in Magento, content blocks are used for everything. For example, to render the XHTML for individual products, comparable in Drupal to nodes, or in WordPress to posts and pages.

• “Layouts” in Magento have no equivalent in Drupal or WordPress. It’s a relatively clever concept. There are also some other clever concepts involved like overriding of template files that I won’t go into here but are explained in the design guide. You won’t need to worry about that much, if at all, to complete this theme.

• “Templates” in Magento are the individual XHTML files and they are saved with a .phtml extension inside the ./app/design/frontend/default/YOUR_THEME/template/page/ directory. In Drupal these files end with .tpl.php and are saved in ./sites/all/themes/YOUR_THEME/, and in WordPress these files end with good old .php and are saved in ./wp-content/themes/YOUR_THEME/. These are the files containing XHTML markup for pages, including header, footer, as well as individual content blocks.

Ok, great. Now that you are acclimated to the terminology most people will be using as you read further into the subject, let’s move on.

Touring the Directory Structure: What goes where?

Now I am going to take you on an overview of the Magento directory structure, highlighting only the files you need to be concerned about along the way to complete your first theme. Feel free to find these files and directories in your own Magento installation and follow along with me as I explain what each file is for.

./app/ - private dir
  design/
    frontend/
      default/ - interface (worry about later)
        YOUR_THEME/
          layout/ - .XML here control which content blocks appear and in what order
            page.xml - content blocks that appear on all pages
          template/
            page/
              html/
                head.phtml - DOCTYPE & <HEAD> tag
                header.phtml - page header incl. logo
                footer.phtml - page footer
              1column.phtml - e.g. about page
              2columns-left.phtml
              2columns-right.phtml - e.g. product page
              3columns.phtml - e.g. catalog page

./skin/ - public dir
  frontend/
    default/ - interface (worry about later)
      YOUR_THEME/
        css/
          styles.css - screen styles
          print.css - print styles
          reset.css - CSS reset
          clears.css - .clear { clear:both }
          styles-ie.css - ie-only styles
        images/
        js/
        favicon.ico

I think the way I have presented it to you here, if you have ever completed a theme for WordPress or Drupal before, you will immediately recognize these files and be well on your way. By making changes to these XHTML and CSS files alone you will have drastic control over 90% of the theme.

Enabling Magento Debugging Tools

Of course, there are more files than this that make a theme. Sometimes you will wonder what file controls a specific content block when you want to edit its XHTML template. For that you will want to know about this handy developer tool provided with Magento.

Here it is step-by-step:

1. Login to back-end > System > Configuration
2. Choose your store from the “Current Configuration Scope” drop-down menu on the top-left
3. Continue navigating to Advanced > Developer
4. Open the Debug drawer
5. Uncheck “Use website” for “Template Path Hints” and set its drop-down to “Yes“
6. Uncheck “Use website” for “Add Block Names to Hints” and set its drop-down to “Yes“
7. Click the Save Config button and refresh the front page

This will display the location of the .phtml template at the top of each content block. It does come in handy.

To Be Continued

While there are more advanced subtleties, nuances, and quirks you will undoubtedly encounter as you complete more and more themes for the Magento e-Commerce platform, this is the meat and potatoes. Should you run into any question not answered here, I find that the Magento Forum, Magento Wiki, and #magento on irc.freenode.net, as well as a fair amount of Googling can turn up those answers with relative ease.

Please feel free to drop me a note in the comments if this tutorial saved you some time, or if you’d like to point out anything I may have missed or any necessary corrections to be made. Otherwise, thanks for visiting and good luck on your theme!

Bonus

I recently completed a Magento theme of my own and it took me about 40 hours to do, work which includes the creative time for custom artwork. All-in-all, it turned out excellent and I am very proud. Check it out:

Front page

Product Catalog

Product Page

Also, I have posted an in-depth case study explaining most everything that went into the project, should you be interested in reading further:

Magento case study at Smullin Design

Thanks again!

No offense to Apache Friends because I love XAMPP and have been using it for years. Something bigger is definitely going on here, because my Eclipse PDT 3.2 IDE was having trouble with Magento, too. Contrary to what you might think, from what I’ve read it looks like it’s actually Zend’s fault; specifically, the Zend Framework has revolutionized the way PHP programmers think and the way PHP5 web applications are written. Truly object-oriented! Imagine that. Even the highly acclaimed Drupal project [which I also love, don't get me wrong] is still 99.9% procedural programming. Eclipse was fine with these, but now you need the new Ganymede release to ride with ZF and Magento.

So in a way this unexpected behavior now between Magento and XAMPP is self-serving because, if you research the problem, the solution recommended just about everywhere is to download Zend Core as an alternative to XAMPP.

Well XAMPP, my friend, it was fun while it lasted, but the cards are stacked against you now. It has been days since I made the switch and Magento hasn’t crashed at all. Not even once! So, if you’re having the same problem as I was, just save yourself some time and try Zend Core. You’ll thank yourself later.

To give you a brief overview of the timeline so far: In July, Magento was awarded “Best New Open Source Project” by the 2008 SourceForge.net Community Choice Awards. In August, Magento was awarded “Best of Open Source Enterprise Applications” by the 2008 InfoWorld.com BOSSIE Awards. This year Forrester Research, the leading technology and market research firm, named Magento as an “Emerging Player To Watch” in its Forrester Wave™: B2C eCommerce Platforms Report, Q1 2009. The growth has just been incredible! Check out the blog for a full in-depth history.

Personally, I have been using this platform for a little over 4 months now (running version 1.2.1 as of this writing) and can’t say enough good things about it. The feature-set is truly an amazing combination of technology. If I had one complaint, I wish there were more documentation, and more extensions, but it’s still pretty early for all that and I know the community is actively working on this with the wiki, screencasts, phpdocs, etc. If there is ever anything you can’t find there, I have always found supportive folks in the #magento chatroom on irc.freenode.net.

Check out their store demo and in the meantime stay tuned for updates, Q&A, tips, tricks, and hacks as I continue benefiting from and contributing back to the platform.