nacento/module-category-thumbnail

Magento 2 module that adds a category thumbnail image attribute and GraphQL thumbnail URL field.

dev-main 2026-03-21 00:33 UTC

Requires

• php: ^8.1 || ^8.2 || ^8.3
• magento/framework: *
• magento/module-catalog: *
• magento/module-catalog-graph-ql: *

Requires (Dev)

• phpunit/phpunit: ^9.5

Apache-2.0

README

Magento 2 module that adds a category thumbnail image attribute (thumbnail_image) to catalog categories, exposes it in the admin category form, and provides a GraphQL field (thumbnail_image_url) that returns a normalized URL ready for frontend consumption.

Module Information

• Magento module name: Nacento_CategoryThumbnail
• Composer package name: nacento/module-category-thumbnail
• Type: magento2-module

What This Module Adds

• A new category EAV image attribute: thumbnail_image
• A category admin form field (image uploader) under the Content fieldset
• A GraphQL field on CategoryTree:
  • thumbnail_image_url: String

Compatibility / Requirements

• PHP: ^8.1 || ^8.2 || ^8.3
• Magento modules:
  • Magento_Catalog
  • Magento_CatalogGraphQl

Installation

Option 1: app/code (local/custom module workflow)

Copy this repository to:

app/code/Nacento/CategoryThumbnail

Then enable and install:

bin/magento module:enable Nacento_CategoryThumbnail
bin/magento setup:upgrade
bin/magento cache:flush

Option 2: Composer package (recommended for shared environments)

If this repository is published to Packagist or a private Composer registry:

composer require nacento/module-category-thumbnail
bin/magento module:enable Nacento_CategoryThumbnail
bin/magento setup:upgrade
bin/magento cache:flush

Admin Usage

After installation:

1. Go to Catalog > Categories
2. Open a category
3. In the Content section, use Thumbnail Image
4. Save the category

The value is stored in the category attribute thumbnail_image.

GraphQL Usage

This module extends CategoryTree with a computed field:

• thumbnail_image_url

Example query

{
  categories(filters: { ids: { in: ["12"] } }) {
    items {
      id
      name
      children {
        id
        name
        thumbnail_image_url
      }
    }
  }
}

Resolver behavior (URL normalization)

The resolver handles different formats commonly found in existing data:

• Absolute URL (https://cdn.example/...) -> returned as-is
• Protocol-relative URL (//cdn.example/...) -> returned as-is
• Root-relative path (/media/catalog/category/x.jpg) -> prefixed with store web base URL
• Relative media path (media/catalog/category/x.jpg) -> normalized to store web base URL without duplicating /media
• Legacy relative path (catalog/category/x.jpg) -> prefixed with store media base URL
• Empty/missing values -> null

Project Structure

.
├── etc/
│   ├── module.xml                  # Module declaration and dependencies
│   └── schema.graphqls             # GraphQL schema extension
├── Model/Resolver/
│   └── CategoryThumbnailUrl.php    # GraphQL resolver for thumbnail_image_url
├── Setup/Patch/Data/
│   └── AddCategoryThumbnailAttribute.php  # Adds category EAV attribute
├── view/adminhtml/ui_component/
│   └── category_form.xml           # Admin category form field
├── Test/Unit/
│   └── Model/Resolver/CategoryThumbnailUrlTest.php
├── composer.json
├── phpunit.xml.dist
└── registration.php

Development

Install dev dependencies

composer install

Run unit tests

vendor/bin/phpunit -c phpunit.xml.dist

Current test coverage

Unit tests cover GraphQL resolver URL normalization scenarios, including:

• Empty/missing values
• Absolute/protocol-relative URLs
• Root-relative and relative media paths
• Legacy relative paths
• Whitespace trimming behavior

Recent Improvements (Quality / Robustness)

This repository was updated to improve maintainability and reliability:

• Added Composer packaging metadata (composer.json)
• Added PHPUnit configuration and unit tests
• Refactored the data patch for cleaner attribute configuration and idempotency clarity
• Hardened GraphQL URL normalization to better handle edge cases (media/..., whitespace, protocol-relative URLs)
• Replaced placeholder README with full project documentation

Notes

• The module is intentionally small and focused on category thumbnail support only.
• Licensed under Apache License 2.0. See LICENSE and NOTICE.
• For production release workflows, consider adding:
  • CI pipeline (lint + unit tests)
  • Magento integration tests for GraphQL schema/response verification
  • Version tags / changelog policy