PHPackages                             nacento/module-category-thumbnail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. nacento/module-category-thumbnail

ActiveMagento2-module[File & Storage](/categories/file-storage)

nacento/module-category-thumbnail
=================================

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

00PHP

Since Mar 21Pushed 1mo agoCompare

[ Source](https://github.com/nacento-conn/nacento-category-thumbnail)[ Packagist](https://packagist.org/packages/nacento/module-category-thumbnail)[ RSS](/packages/nacento-module-category-thumbnail/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Nacento Category Thumbnail (Magento 2)
======================================

[](#nacento-category-thumbnail-magento-2)

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
------------------

[](#module-information)

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

What This Module Adds
---------------------

[](#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
----------------------------

[](#compatibility--requirements)

- PHP: `^8.1 || ^8.2 || ^8.3`
- Magento modules:
    - `Magento_Catalog`
    - `Magento_CatalogGraphQl`

Installation
------------

[](#installation)

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

[](#option-1-appcode-localcustom-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)

[](#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
-----------

[](#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
-------------

[](#graphql-usage)

This module extends `CategoryTree` with a computed field:

- `thumbnail_image_url`

### Example query

[](#example-query)

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

### Resolver behavior (URL normalization)

[](#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
-----------------

[](#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
-----------

[](#development)

### Install dev dependencies

[](#install-dev-dependencies)

```
composer install
```

### Run unit tests

[](#run-unit-tests)

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

### Current test coverage

[](#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)
------------------------------------------

[](#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
-----

[](#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

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance63

Regular maintenance activity

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/d70ab1934ec108f3f839aaa16ec5a0ec501367730d10b41d937d375a28c1b116?d=identicon)[nacento](/maintainers/nacento)

### Embed Badge

![Health badge](/badges/nacento-module-category-thumbnail/health.svg)

```
[![Health](https://phpackages.com/badges/nacento-module-category-thumbnail/health.svg)](https://phpackages.com/packages/nacento-module-category-thumbnail)
```

###  Alternatives

[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k39.8M123](/packages/knplabs-gaufrette)[google/cloud-storage

Cloud Storage Client for PHP

34390.8M123](/packages/google-cloud-storage)[illuminate/filesystem

The Illuminate Filesystem package.

15261.6M2.6k](/packages/illuminate-filesystem)[superbalist/flysystem-google-storage

Flysystem adapter for Google Cloud Storage

26320.6M30](/packages/superbalist-flysystem-google-storage)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M61](/packages/creocoder-yii2-flysystem)[flowjs/flow-php-server

PHP library for handling chunk uploads. Works with flow.js html5 file uploads.

2451.6M15](/packages/flowjs-flow-php-server)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)