Category Management

Purpose and Scope

This document covers the category management system in GP247/Shop, which provides hierarchical organization of products in the catalog. Categories support multi-level parent-child relationships, internationalized content, and multi-store availability control.

For information about product catalog management, see Product Model and Business Logic. For frontend display of categories, see Product Frontend Display.

---

Data Model and Relationships

The category system uses three core database tables that work together to support hierarchical organization, localization, and multi-store functionality.

Core Tables

Table	Purpose	Key Fields
shop_category	Main category records	id, parent, alias, image, top, status, sort
shop_category_description	Localized content	category_id, lang, title, keyword, description
shop_category_store	Multi-store junction	category_id, store_id

ShopCategory Model Relationships

The ShopCategory model defines three primary relationships:

Diagram: ShopCategory Model Relationships

Sources: src/Models/ShopCategory.php23-35

Key Relationship Methods:

• products() src/Models/ShopCategory.php23-26 - Returns products associated with this category via the shop_product_category junction table
• stores() src/Models/ShopCategory.php27-30 - Returns stores where this category is available via ShopCategoryStore junction table
• descriptions() src/Models/ShopCategory.php32-35 - Returns all localized descriptions for this category
• getText() src/Models/ShopCategory.php37-40 - Retrieves the description for the current locale
• getParent() src/Models/ShopCategory.php58-61 - Retrieves the parent category using the parent field

---

Hierarchical Structure

Categories support a three-level hierarchy using a self-referencing parent field. The system distinguishes between root categories (parent is null or empty) and child categories (parent references another category ID).

Category Tree Structure

Diagram: Three-Level Category Hierarchy

Sources: src/Models/ShopCategory.php291-296

Hierarchy Query Methods

The model provides methods to navigate and query the hierarchy:

Root Category Selection:

src/Models/ShopCategory.php195-199

Top Category Flag:

src/Models/ShopCategory.php203-208

Get Subcategories:

src/Models/ShopCategory.php291-296

The getListSub() method returns a flattened array containing the category itself plus all child and grandchild category IDs, useful for querying products across an entire category branch.

Sources: src/Models/ShopCategory.php172-208 src/Models/ShopCategory.php291-296

---

Localization System

Categories store their textual content (title, keyword, description) separately per language using the shop_category_description table.

Description Storage Pattern

Diagram: Localized Description Storage

Sources: src/Models/ShopCategory.php32-53

Text Retrieval Methods

Method	Return Value	Description
getText()	ShopCategoryDescription object	Returns description for current locale
getTitle()	string	Returns title field for current locale
getDescription()	string	Returns description field for current locale
getKeyword()	string	Returns SEO keyword for current locale

src/Models/ShopCategory.php37-53

Query Integration

When querying categories, the buildQuery() method automatically joins the description table filtered by locale:

src/Models/ShopCategory.php218-221

Sources: src/Models/ShopCategory.php32-53 src/Models/ShopCategory.php216-221

---

Multi-Store Architecture

The category system uses a junction table pattern to control which categories appear in which stores when multi-store functionality is enabled.

Store Association Flow

Diagram: Multi-Store Query Filtering Logic

Sources: src/Models/ShopCategory.php138-145 src/Models/ShopCategory.php231-238

Store Assignment in Admin

When creating or editing categories, administrators can assign them to multiple stores:

src/Admin/Controllers/AdminCategoryController.php242-249 src/Admin/Controllers/AdminCategoryController.php355-362

Store Filtering Behavior

Scenario	Behavior
Multi-store disabled	No store filtering applied to queries
Root store session	All categories visible (marketplace admin view)
Vendor store session	Only categories assigned to current store visible

The filtering is applied consistently in:

• getDetail() method src/Models/ShopCategory.php138-145
• buildQuery() method src/Models/ShopCategory.php231-238

Sources: src/Models/ShopCategory.php138-145 src/Models/ShopCategory.php231-238 src/Admin/Controllers/AdminCategoryController.php242-249 src/Admin/Controllers/AdminCategoryController.php355-362

---

Admin CRUD Operations

The AdminCategoryController provides complete CRUD functionality for category management through a standard admin interface pattern.

Controller Action Flow

Diagram: AdminCategoryController Action Flow

Sources: src/Admin/Controllers/AdminCategoryController.php20-406

Key Controller Methods

Method	Route	Purpose
index()	admin_category.index	Display paginated category list with search/sort
create()	admin_category.create (GET)	Display creation form
postCreate()	admin_category.create (POST)	Process form submission and create category
edit($id)	admin_category.edit (GET)	Display edit form for existing category
postEdit($id)	admin_category.edit (POST)	Process form submission and update category
deleteList()	admin_category.delete	Handle AJAX bulk deletion

src/Admin/Controllers/AdminCategoryController.php20-406

Validation Rules

The system applies comprehensive validation during create and edit operations:

src/Admin/Controllers/AdminCategoryController.php189-195 src/Admin/Controllers/AdminCategoryController.php301-307

Automatic Alias Generation:

If no alias is provided, it's generated from the title of the first active language:

src/Admin/Controllers/AdminCategoryController.php185-188 src/Admin/Controllers/AdminCategoryController.php297-300

Data Processing Pipeline

Create Operation:

1. Validate input data
2. Create main category record with sanitized data
3. Insert localized descriptions for all active languages
4. Attach to stores (if multi-store enabled)
5. Update custom fields
6. Clear cache

src/Admin/Controllers/AdminCategoryController.php181-257

Update Operation:

1. Validate input data
2. Update main category record
3. Delete existing descriptions
4. Insert updated descriptions
5. Sync store associations
6. Update custom fields
7. Clear cache

src/Admin/Controllers/AdminCategoryController.php288-371

Model Deletion Hooks

When a category is deleted, the model's deleting event ensures cleanup:

src/Models/ShopCategory.php67-81

Sources: src/Admin/Controllers/AdminCategoryController.php20-406 src/Models/ShopCategory.php63-88

---

Query Building and Filtering

The ShopCategory model uses a fluent query builder pattern through the buildQuery() method, which is inherited from ModelTrait.

Query Builder Architecture

Diagram: buildQuery() Processing Flow

Sources: src/Models/ShopCategory.php213-282

Query Method Pattern

The model uses inherited traits that provide a consistent query building pattern:

src/Models/ShopCategory.php165-168 src/Models/ShopCategory.php195-208

Keyword Search

When a keyword is set via setKeyword() (inherited from ModelTrait), the buildQuery() method searches across localized fields:

src/Models/ShopCategory.php223-229

Sorting Logic

The query builder supports multiple sorting strategies:

Strategy	Implementation
Random	setRandom(true) → inRandomOrder()
Custom fields	setSort([['field', 'direction']]) → Multiple orderBy() calls
Default	sort ASC, then created_at DESC

src/Models/ShopCategory.php259-279

Sources: src/Models/ShopCategory.php213-282

---

URL Generation and Frontend Integration

Categories provide methods for generating SEO-friendly URLs and retrieving display images.

URL and Asset Methods

Method	Return Value	Purpose
getUrl($lang)	string	Returns frontend category detail URL
getImage()	string	Returns full image path
getThumb()	string	Returns thumbnail image path

URL Generation:

src/Models/ShopCategory.php106-109

Image Retrieval:

src/Models/ShopCategory.php93-104

Admin List Display Integration

The admin controller uses these methods to display category information in the list view:

src/Admin/Controllers/AdminCategoryController.php82-89

Frontend Link in Admin

The admin list includes a link to view the category on the frontend:

src/Admin/Controllers/AdminCategoryController.php109

Sources: src/Models/ShopCategory.php93-109 src/Admin/Controllers/AdminCategoryController.php82-109

---

Cache Management

Category operations clear the cache_category cache key to ensure fresh data after modifications:

This cache clearing occurs after:

• Creating a new category src/Admin/Controllers/AdminCategoryController.php254
• Updating an existing category src/Admin/Controllers/AdminCategoryController.php367
• Deleting categories src/Admin/Controllers/AdminCategoryController.php394

Sources: src/Admin/Controllers/AdminCategoryController.php254 src/Admin/Controllers/AdminCategoryController.php367 src/Admin/Controllers/AdminCategoryController.php394

---

Custom Fields Integration

Categories support custom fields through the AdminCustomField system, allowing administrators to extend category data with additional fields.

Custom Field Rendering

The admin form includes custom fields:

src/Views/admin/screen/category.blade.php266-268

Custom Field Validation

Required custom fields are validated during create/edit:

src/Admin/Controllers/AdminCategoryController.php197-204

Custom Field Storage

Custom field values are saved using the helper function:

src/Admin/Controllers/AdminCategoryController.php251-252

Custom Field Cleanup

When a category is deleted, associated custom fields are removed:

src/Models/ShopCategory.php74-78

Sources: src/Views/admin/screen/category.blade.php266-268 src/Admin/Controllers/AdminCategoryController.php197-204 src/Admin/Controllers/AdminCategoryController.php251-252 src/Models/ShopCategory.php74-78

---

Admin View Structure

The admin form (category.blade.php) follows a consistent structure for category management.

Form Sections

Diagram: Admin Form Structure

Sources: src/Views/admin/screen/category.blade.php1-305

Key Form Elements

Element	Field Name	Input Type	Description
Title	descriptions[{lang}][title]	Text	Localized category name (max 200 chars)
Keyword	descriptions[{lang}][keyword]	Text	SEO keywords (max 200 chars)
Description	descriptions[{lang}][description]	Textarea	Category description (max 500 chars)
Parent	parent	Select	Parent category or ROOT
Store	shop_store[]	Multi-select	Store assignments (multi-store only)
Alias	alias	Text	URL-friendly identifier (max 100 chars)
Image	image	File picker	Category image
Sort	sort	Number	Display order
Top	top	Checkbox	Show in top navigation
Status	status	Checkbox	Active/inactive

src/Views/admin/screen/category.blade.php28-264

Parent Category Selection

The parent dropdown is populated using the getTreeCategoriesAdmin() method from AdminCategory:

src/Views/admin/screen/category.blade.php119-126

This prevents creating circular parent-child relationships and provides a clear hierarchical view.

Sources: src/Views/admin/screen/category.blade.php1-305