How to add a category to Magento via Setup script?

How to add a category to Magento via Setup script?

July 8, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How to add a category to Magento via Setup script?

Solving Category Field Issues After Setup Script in Magento

The Problem: Inconsistent Category Data Between Admin and Frontend

You’re facing a frustrating issue where some category fields set via the setup script aren’t persisting correctly, leading to inconsistencies between the admin interface and frontend display.

Your current script is creating categories with specified values, but key properties like displayMode, landingPage, pageLayout, and customLayoutUpdate are missing from the flat table even after re-indexing. Even more puzzling, these fields appear correctly in the admin but are ignored in the frontend.

Understanding the Magento Setup Process

To resolve this issue, let’s first ensure we understand how Magento processes setup scripts:

  1. The script is executed with Mage::register('isSecureArea', 1); to allow access to restricted areas.
  2. You create a new category instance and set various properties using the fluent interface (->setProperty(value)).
  3. Finally, you save the category object and end the setup process.

The problem likely lies in how Magento handles flat table indexing or the specifics of setting certain category attributes.

Fixing Display Mode, Landing Page, and Layout Issues

Step 1: Ensuring Correct Indexing

First, ensure that your flat table indexes are up-to-date. Run the following commands:

php bin/magento indexer:reindex catalog_category_flat
php bin/magento cache:flush

Step 2: Setting Specific Category Attributes

For certain attributes like displayMode, landingPage, and pageLayout, Magento requires explicit handling. Update your script as follows:

$this->startSetup();
Mage::register('isSecureArea', 1);

$category = Mage::getModel('catalog/category');
$category->setPath('1/2') // set parent to be root category
    ->setName('Category Name')
    ->setUrlKey('category-name')
    ->setIsActive(0)
    ->setIncludeInMenu(1)
    ->setInfinitescroll(1);

$customOptions = array(
    'display_mode' => 'PAGE',
    'landing_page' => $idToCmsBlock,
    'page_layout' => 'anotherLayoutThanDefault',
    'custom_update' => '<reference name="head"><action method="addCss"><stylesheet>css/somecss.css</stylesheet></action></reference>'
);

$category->setData('custom_options', serialize($customOptions))
         ->save();

$this->endSetup();

In this updated version, we’re setting the display_mode, landing_page, and page_layout attributes through a $customOptions array. These options are then serialized and set as the custom_options attribute on the category.

Step 3: Re-indexing the Category Tree

After saving the category with these custom options, re-index the category tree:

php bin/magento indexer:reindex catalog_category_tree

Ensuring Category Visibility in the Frontend

Regarding your is_enabled issue, Magento 2 uses the is_active attribute to determine whether a category is visible in the frontend.

To ensure a category is enabled and visible:

  1. Set ->setIsActive(1) in your setup script.
  2. In the admin interface, check the “Enable” box next to the category.

Final Thoughts

When working with Magento setup scripts for categories, it’s crucial to understand how specific attributes are handled. Always double-check your indexation status and ensure that you’re using the correct attribute names and formats.

Remember to test your script thoroughly in a development environment before deploying it to a live site.

For more advanced category management techniques and best practices in Magento 2, feel free to explore our Magento Development Guide at Laravel Company.

Catalog Cache Indexing Database

Our network