How do I use Magento's collection objects

How do I use Magento's collection objects

August 6, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How do I use Magento's collection objects

Working with Magento Collection Objects: A Comprehensive Guide

Hello developers! Welcome to another technical deep dive into the world of Magento customization. Today, we’re going to explore how to effectively use Magento’s collection objects while building your own admin module. Stick around as I guide you through understanding and resolving a common issue faced by beginners.

The Issue: Deleting from a Custom Collection

Our friend Adde here is working on a custom admin module for Magento CE 1.6 and has encountered an exception when trying to delete rows from a filtered collection:

foreach ($department_collection as $department) {
    $department->delete();
}

This results in a fatal error due to an incorrect directory structure or misunderstanding of the collection object.

Understanding Magento Collection Objects

Before we dive into solving Adde’s problem, let me first provide some context on what Magento collections are and how they work. In Zend Framework (the core framework used by Magento), a collection is simply an array-like class that provides additional functionality for managing data. Magento extends this concept to handle database records.

Every model in Magento has its corresponding collection object responsible for retrieving multiple instances of the same type from the database using SQL queries. The collections provide methods like getData(), getSize(), and load() which you can use to interact with your data.

Resolving Adde’s Directory Structure Issue

Let’s first address Adde’s directory structure:

+app
  +code
     +local
       +Namespace
         +Module
           +Model
             +Mysql4
                +Systemconfig
                   Collection.php
                Systemconfig.php
             Systemconfig.php

The issue seems to lie in the naming convention of your files and directories. Magento uses a specific naming structure for its models, which Adde appears to have missed.

The Correct Directory Structure

For a custom model like Namespace_Module_Model_Systemconfig, you should follow this directory structure:

+app
  +code
     +local
       +Namespace
         +Module
           +Model
             +Systemconfig
               Form.php
               Observer.php
               Systemconfig.php
               Collection.php

Notice the following corrections:

  1. The Mysql4 directory should not be present in your custom models. It’s only used for resource models.
  2. All model files (e.g., Form.php, Observer.php, etc.) reside directly under the main Systemconfig directory.

Fixing Adde’s Configuration XML

Your current configuration XML looks like this:

<models>
  <module>
        <class>Namespace_Module_Model</class>
    <resourceModel>module_mysql4</resourceModel>
  </module>

  <module_mysql4>
    <class>Namespace_Module_Model_Mysql4</class>
    <entities>
        <systemconfig>
            <table>module_systemconfig</table>
        </systemconfig>
    </entities>
  </module_mysql4>
</models>

The problem here is that you’ve declared two models: module and module_mysql4. This causes confusion for Magento’s autoloading mechanism.

The Correct Configuration XML

Your configuration XML should look like this:

<models>
  <namespace_module>
        <class>Namespace_Module_Model</class>
    <resourceModel>namespace_module_mysql4</resourceModel>
  </namespace_module>

  <namespace_module_mysql4>
    <class>Namespace_Module_Model_Mysql4</class>
    <entities>
        <systemconfig>
            <table>module_systemconfig</table>
        </systemconfig>
    </entities>
  </namespace_module_mysql4>
</models>

I’ve renamed the module model to namespace_module. The resource model should match this new name. This ensures that Magento can properly autoload your custom models.

Revisiting Adde’s Code

Now let’s revisit Adde’s code with the correct directory structure and configuration:

// file: ../Model/Systemconfig.php
class Namespace_Module_Model_Systemconfig extends Mage_Core_Model_Abstract {
    protected function _construct() {
        $this->_init('namespace/module_systemconfig');
    }
}
// file: ../Model/Collection.php
class Namespace_Module_Model_Systemconfig_Collection extends Mage_Core_Model_Mysql4_Collection_Abstract {
    protected function _construct() {
        $this->_init('namespace/module_systemconfig');
    }
}

Notice that I’ve replaced module with namespace/module. This correction ensures that your models are correctly associated with the new configuration.

Deleting from a Custom Collection: The Proper Way

Adde’s initial approach was almost correct. To delete rows from a filtered collection, you should use the following code:

$department_collection = Mage::getModel('namespace/module_systemconfig')
                            ->getCollection()
                            ->addFilter('name', 'departments');

foreach ($department_collection as $department) {
    $department->delete();
}

The key difference is that I’ve used Mage::getModel with the correct model name, which ensures that Magento can properly load your custom collection.

Conclusion

In conclusion, when working with custom collections in Magento:

  1. Ensure you follow the correct naming conventions for your directory structure.
  2. Configure your XML correctly to match your models.
  3. Use Mage::getModel with the proper model name to load your custom collections.

By following these best practices, you’ll avoid common pitfalls and be well on your way to mastering Magento’s collection objects. If you have any further questions or need additional guidance, feel free to reach out in the comments below!

Happy coding!

Database Extensions Admin Errors

Our network