PHPackages                             ksfraser/fa-product-attributes - 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. [Utility & Helpers](/categories/utility)
4. /
5. ksfraser/fa-product-attributes

ActiveLibrary[Utility & Helpers](/categories/utility)

ksfraser/fa-product-attributes
==============================

FrontAccounting-compatible ordered product attributes (royal order of adjectives)

02PHP

Since Jan 21Pushed 3mo agoCompare

[ Source](https://github.com/ksfraser/FA_ProductAttributes)[ Packagist](https://packagist.org/packages/ksfraser/fa-product-attributes)[ RSS](/packages/ksfraser-fa-product-attributes/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

FA\_ProductAttributes
=====================

[](#fa_productattributes)

A core Product Attributes module for FrontAccounting that provides generic attribute infrastructure and enables extensible attribute-based functionality through plugins.

Repository Structure & Inter-relationships
----------------------------------------------

[](#repository-structure--inter-relationships)

This repository contains a modular FA Product Attributes system designed for scalable development and deployment:

### Core Components

[](#core-components)

- **`FA_ProductAttributes`** (this repo): Shared composer library containing core attribute infrastructure

    - Generic attribute categories, values, and assignments
    - Database schema management
    - Common services and utilities
    - Used by all FA modules requiring attribute functionality
- **`FA_ProductAttributes_Core`**: Main FA module providing the admin interface

    - Requires: `ksfraser/fa-product-attributes` (shared library)
    - Provides: Web-based attribute management interface
    - Integrates with FA's item management system
- **`FA_ProductAttributes_Variations`**: Plugin module for product variations

    - Requires: `ksfraser/fa-product-attributes` (shared library)
    - Depends on: `FA_ProductAttributes_Core` (for loading order)
    - Provides: Parent-child product relationships, variation generation
- **`FA_ProductAttributes_Categories`**: Plugin module for category-based attributes

    - Requires: `ksfraser/fa-product-attributes` (shared library)
    - Depends on: `FA_ProductAttributes_Core` (for loading order)
    - Provides: Category-level attribute inheritance

### Deployment Architecture

[](#deployment-architecture)

```
FrontAccounting modules/
├── FA_ProductAttributes_Core/     # Main module (loads first)
│   ├── vendor/
│   │   └── ksfraser/fa-product-attributes/  # Shared library
│   └── _init/config                        # FA module config
├── FA_ProductAttributes_Variations/        # Plugin module
│   ├── vendor/
│   │   └── ksfraser/fa-product-attributes/  # Shared library
│   └── _init/config                        # Depends on Core
└── FA_ProductAttributes_Categories/        # Plugin module
    ├── vendor/
    │   └── ksfraser/fa-product-attributes/  # Shared library
    └── _init/config                        # Depends on Core

```

### Design Principles

[](#design-principles)

- **Shared Library**: Common code lives in `ksfraser/fa-product-attributes` composer package
- **Module Independence**: Each FA module is self-contained with its own vendor dependencies
- **Loading Order**: Core module loads first, plugins depend on it for proper initialization
- **Plugin Architecture**: Clean separation between generic attributes (core) and domain-specific features (plugins)

See `Project Docs/` for detailed business requirements, functional specifications, and architecture documentation.

See `AGENTS-TECH.md` for technical implementation details and agent-specific requirements.

### Core Module Responsibilities

[](#core-module-responsibilities)

The FA\_ProductAttributes core module provides:

- **Attribute Categories & Values**: Generic management of attribute categories and their values
- **Assignment System**: Linking products to attributes (both individual and category-level)
- **STOCK Application Integration**: Hooks into FA's items.php to add attribute functionality
- **Extension Points**: Hook system allowing plugins to extend functionality

### Plugin Architecture

[](#plugin-architecture)

The module supports plugins that can add specific attribute functionality:

- **FA\_ProductAttributes\_Variations**: Adds WooCommerce-style product variations
    - Parent-child product relationships
    - Automatic variation generation from attribute combinations
    - Retroactive pattern analysis for existing products
    - Royal Order attribute sequencing
    - Variation-based pricing rules (fixed, percentage, combined adjustments)
    - Bulk operations for variation management
- **Future Plugins**: Product dimensions, tags, custom attributes, etc.

### Recent Changes (v1.x)

[](#recent-changes-v1x)

- **Plugin Architecture Refactoring**: Moved variation-specific services to FA\_ProductAttributes\_Variations plugin
- **Service Separation**: RetroactiveApplicationService moved from core to variations plugin
- **Clean Separation**: Core module provides generic attributes, plugins add domain-specific functionality
- **Hook Extensions**: Plugin system uses fa-hooks for clean integration

### Database Schema

[](#database-schema)

The core module manages the foundational attribute structure:

- `product_attribute_categories`: Attribute categories (Color, Size, etc.)
- `product_attribute_values`: Values within categories (Red, Blue, XL, etc.)

Plugins can extend the core with additional tables and functionality as needed.

Extended Hook System Architecture
---------------------------------

[](#extended-hook-system-architecture)

The Product Attributes module now includes an extended hook system that enables scalable module development and cross-module integration for FrontAccounting.

### Key Components

[](#key-components)

1. **Container Classes**: Generic containers for managing different types of FA data structures

    - `ArrayContainer`: Abstract base for array-based data
    - `TabContainer`: Specialized for tab management
    - `MenuContainer`: Specialized for menu items
2. **Hook Registry**: Dynamic hook point registration system

    - Modules can register their own hook points
    - Other modules can extend these hook points
    - Priority-based execution control
3. **Version Abstraction**: Automatic handling of FA version differences

    - Transparent adaptation between FA 2.3.x and 2.4.x+
    - Future-proof compatibility
4. **Factory Pattern**: Centralized container creation

    - `ContainerFactory` creates appropriate containers by context
    - Type-safe object instantiation

### Cross-Module Integration

[](#cross-module-integration)

The extended architecture enables modules to integrate with each other:

```
// Supplier module registers hook point
$hooks->registerHookPoint('supplier_tabs', 'supplier_module', function($tabs) {
    $tabs->createTab('general', 'General', 'suppliers.php');
    return $tabs->toArray();
});

// Product Attributes extends supplier tabs
$hooks->registerExtension('supplier_tabs', 'product_attributes', function($tabs) {
    $tabs->createTab('attributes', 'Product Attributes', 'supplier_attributes.php');
}, 10);
```

### Benefits

[](#benefits)

- **Scalability**: Easy to add new modules and extensions
- **Version Agnostic**: Automatic FA version compatibility
- **Decoupling**: Modules don't need to know about each other
- **Type Safety**: Object-oriented design with proper validation
- **Extensible**: Supports any FA module (Suppliers, Customers, Inventory, etc.)

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

[](#installation)

### Prerequisites

[](#prerequisites)

- FrontAccounting 2.3.22 or later
- PHP 7.3+
- MySQL 5.7+ or MariaDB 10.0+
- Composer (for dependency management)

### Step 1: Install FA-Hooks Module (Required)

[](#step-1-install-fa-hooks-module-required)

The Product Attributes module requires the FA-Hooks system for integration:

```
# Install FA-Hooks as a separate module (provides generic hook system for all modules)
cd /path/to/frontaccounting/modules
git clone https://github.com/ksfraser/FA_Hooks.git 0fa-hooks
cd 0fa-hooks
composer install  # Run this BEFORE activating in FA

# Activate 0FA-Hooks in FA (Setup → Install/Update Modules)
```

**Note**: FA-Hooks should be installed once and provides the hook system for ALL your FA modules. The directory is named `0fa-hooks` to ensure it loads first alphabetically.

**Production Deployment**: For production environments, install FA-Hooks as a separate module (not as a submodule). The Product Attributes module will automatically check for this dependency during installation.

### Step 2: Download the Product Attributes Module

[](#step-2-download-the-product-attributes-module)

```
# Clone the repository into your FA modules directory
cd /path/to/frontaccounting/modules
git clone https://github.com/ksfraser/FA_ProductAttributes.git FA_ProductAttributes

# Or download the ZIP and extract to modules/FA_ProductAttributes
```

### Step 3: Install Dependencies

[](#step-3-install-dependencies)

```
cd /path/to/frontaccounting/modules/FA_ProductAttributes
composer install
```

### Step 4: Database Setup

[](#step-4-database-setup)

The module will automatically create its database schema during installation, but you can also run the SQL manually:

```
mysql -u your_username -p your_database call_hook('item_display_tab_headers', null, $stock_id);
$tabs = $tabCollection ? $tabCollection->toArray() : [];
```

#### Replace Tab Content Switch (in the tab content display section)

[](#replace-tab-content-switch-in-the-tab-content-display-section)

Replace the tab content switch statement with:

```
// Generic hook-based tab content system
$content = $hooks->call_hook('item_display_tab_content', '', $stock_id, $selected_tab);

if (!empty($content)) {
    echo $content;
} else {
    // Fallback to original FA tab handling
    switch ($selected_tab) {
        case 'general':
            // Original general tab content
            break;
        case 'settings':
            // Original settings tab content
            break;
        default:
            // Default fallback
            break;
    }
}
```

#### Add Save Operation Hooks (in the POST handling section)

[](#add-save-operation-hooks-in-the-post-handling-section)

```
// Call pre-save hooks
if (isset($hooks)) {
    $hooks->call_hook('pre_item_write', $item_data, $stock_id);
}
```

#### Add Delete Operation Hooks (in the delete handling section)

[](#add-delete-operation-hooks-in-the-delete-handling-section)

```
// Call pre-delete hooks
if (isset($hooks)) {
    $hooks->call_hook('pre_item_delete', $stock_id);
}
```

Plugin Architecture
-------------------

[](#plugin-architecture-1)

The FA\_ProductAttributes core module provides extension points for plugins to add specific attribute functionality:

### Available Plugins

[](#available-plugins)

- **FA\_ProductAttributes\_Variations**: Adds WooCommerce-style product variations with parent-child relationships, pricing rules, and bulk operations
- **Future Plugins**: Product dimensions, tags, custom attributes, etc.

### Installing Plugins

[](#installing-plugins)

1. Install the FA\_ProductAttributes core module first
2. Install desired plugins as separate FA modules
3. Plugins automatically extend the core functionality through hooks

### Developing Plugins

[](#developing-plugins)

Plugins can extend the core module by:

- Registering extensions to `attributes_tab_content` hook to add UI
- Registering extensions to `attributes_save` hook to handle data saving
- Registering extensions to `attributes_delete` hook to handle cleanup

Example plugin structure:

```
FA_ProductAttributes_PluginName/
├── composer.json (depends on FA_ProductAttributes)
├── hooks.php (extends core hooks)
├── src/Ksfraser/FA_ProductAttributes_PluginName/
└── README.md

```

Usage
-----

[](#usage)

### Admin Interface Tabs

[](#admin-interface-tabs)

The Product Attributes module provides a comprehensive admin interface accessible via **Inventory → Product Attributes** with four main tabs:

#### Categories Tab

[](#categories-tab)

1. Go to **Inventory → Product Attributes → Categories**
2. Create attribute categories (Color, Size, Material, etc.)
3. Set display order and activation status

#### Values Tab

[](#values-tab)

1. Go to **Inventory → Product Attributes → Values**
2. Add values to categories (Red, Blue, Green for Color)
3. Set sort order for consistent display

#### Assignments Tab

[](#assignments-tab)

1. Go to **Inventory → Product Attributes → Assignments**
2. Assign entire categories to products (all sizes, all colors)
3. Create child products (variations) from parent products
4. Individual assignments override category assignments

#### Product Types Tab

[](#product-types-tab)

1. Go to **Inventory → Product Attributes → Product Types**
2. Manage product type classifications (Simple, Variable, Variation)
3. Set up parent-child relationships for variations
4. Convert between product types while maintaining relationships

### Product Integration

[](#product-integration)

#### Assigning to Products

[](#assigning-to-products)

1. Open any item in **Inventory → Items**
2. Click the **Product Attributes** tab
3. Assign categories and specific values to the product
4. The system will show possible variation counts

#### Creating Variations

[](#creating-variations)

1. In the **Assignments** tab, select a Variable product
2. Assign attribute categories to the product
3. Click **"Create Child Product"** to generate variations
4. Variations inherit category assignments from their parent

API Reference
-------------

[](#api-reference)

### Hook Points

[](#hook-points)

- `item_display_tab_headers`: Receives `TabCollection` object, returns modified `TabCollection`
- `item_display_tab_content`: Provide content for specific tabs (receives $stock\_id and $selected\_tab parameters)
- `pre_item_write`: Modify item data before saving to database
- `pre_item_delete`: Handle cleanup before item deletion

### Extended Hook System

[](#extended-hook-system)

The module now supports the extended hook architecture for cross-module integration:

#### Dynamic Hook Registration

[](#dynamic-hook-registration)

Modules can register their own hook points:

```
// Register a hook point for other modules to extend
$hooks->registerHookPoint('supplier_tabs', 'supplier_module', function($tabs) {
    $tabs->createTab('general', 'General', 'suppliers.php');
    return $tabs->toArray();
}, ['description' => 'Supplier detail tabs']);
```

#### Hook Extensions

[](#hook-extensions)

Other modules can extend registered hook points:

```
// Extend supplier tabs with product attributes
$hooks->registerExtension('supplier_tabs', 'product_attributes', function($tabs) {
    $tabs->createTab('attributes', 'Product Attributes', 'supplier_attributes.php');
}, 10);
```

#### Container Classes

[](#container-classes)

- **TabContainer**: Manages tabs for items, suppliers, customers, etc.
- **MenuContainer**: Manages menu items
- **ArrayContainer**: Generic container for custom data structures

### RESTful API Endpoints

[](#restful-api-endpoints)

The module provides a complete RESTful API for external integrations:

#### Categories API

[](#categories-api)

- `GET /api/categories` - List all categories
- `POST /api/categories` - Create new category
- `PUT /api/categories/{id}` - Update category
- `DELETE /api/categories/{id}` - Delete category

#### Values API

[](#values-api)

- `GET /api/values` - List all values
- `GET /api/values?category_id={id}` - List values for category
- `POST /api/values` - Create new value
- `PUT /api/values/{id}` - Update value
- `DELETE /api/values/{id}` - Delete value

#### Assignments API

[](#assignments-api)

- `GET /api/assignments/{stock_id}` - Get assignments for product
- `POST /api/assignments` - Create assignment
- `DELETE /api/assignments/{id}` - Delete assignment

#### Product Types API

[](#product-types-api)

- `GET /api/product-types` - List all products with types
- `POST /api/product-types/update` - Update product types

### Classes

[](#classes)

- `ProductAttributesDao`: Data access layer with 20+ methods
- `ActionHandler`: Business logic dispatcher for admin operations
- `ProductAttributesService`: Main service for UI and data operations
- Various Action classes: CreateChildAction, UpdateProductTypesAction, etc.
- UI Tab classes: CategoriesTab, ValuesTab, AssignmentsTab, ProductTypesTab

#### Extended Hook System Classes

[](#extended-hook-system-classes)

- `HookManager`: Main hook system manager with extended capabilities
- `HookRegistry`: Dynamic hook point registration and extension management
- `FAVersionAdapter`: Version abstraction for different FA versions
- `TabDefinition`: Object representation of individual tabs
- `TabCollection`: Collection of tabs with version-aware toArray()
- `TabContainer`: Specialized container for tab management
- `MenuContainer`: Specialized container for menu management
- `ArrayContainer`: Abstract base class for array-based data structures
- `ContainerFactory`: Factory for creating appropriate container instances

Development
-----------

[](#development)

### Testing

[](#testing)

The module includes comprehensive test coverage with 140+ unit tests for the main module and additional tests for the extended hook system:

```
# Run main module tests
cd composer-lib
php vendor/bin/phpunit tests/

# Run extended hook system tests
cd ../fa-hooks
php test_containers.php  # Manual validation tests

# Run specific test suite
php vendor/bin/phpunit tests/ProductAttributesDaoTest.php

# Run with coverage report
php vendor/bin/phpunit tests/ --coverage-html coverage/
```

### Test Structure

[](#test-structure)

- **Unit Tests**: Individual class testing with mocks
- **Integration Tests**: Database and service layer testing
- **Action Tests**: Admin operation testing
- **API Tests**: RESTful endpoint testing
- **Hook System Tests**: Extended architecture validation (ContainerTest.php)

### Test Results

[](#test-results)

✅ **All tests pass** - The extended hook system has been validated with:

- Container class functionality (ArrayContainer, TabContainer, MenuContainer)
- Hook registry dynamic registration and extensions
- Version abstraction across FA versions
- Object-based tab management
- Cross-module integration patterns

### Code Quality

[](#code-quality)

- **PSR-4 Autoloading**: Standard PHP namespace structure
- **SOLID Principles**: Single Responsibility, Open/Closed, etc.
- **Dependency Injection**: Clean architecture with DI container
- **Comprehensive Error Handling**: Proper exception management
- **Input Validation**: All user inputs validated and sanitized
- **Object-Oriented Design**: Type-safe containers and version abstraction

Troubleshooting
---------------

[](#troubleshooting)

### Module Not Appearing

[](#module-not-appearing)

- Ensure the module directory is `modules/FA_ProductAttributes`
- Check file permissions
- Verify composer dependencies are installed

### Database Errors

[](#database-errors)

- Check database connection settings
- Ensure user has CREATE TABLE permissions
- Run schema.sql manually if needed

### Items Integration Not Working

[](#items-integration-not-working)

- Verify hooks.php changes are correct
- Check that fa\_hooks.php is included
- Ensure $stock\_id is available in the scope

License
-------

[](#license)

MIT License - see LICENSE file for details.

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance55

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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/c8870cc04b29a973eed9ad367a936ab274d744de37ff0c35fa0540a932905271?d=identicon)[ksfraser](/maintainers/ksfraser)

---

Top Contributors

[![ksfraser](https://avatars.githubusercontent.com/u/54461925?v=4)](https://github.com/ksfraser "ksfraser (1 commits)")

### Embed Badge

![Health badge](/badges/ksfraser-fa-product-attributes/health.svg)

```
[![Health](https://phpackages.com/badges/ksfraser-fa-product-attributes/health.svg)](https://phpackages.com/packages/ksfraser-fa-product-attributes)
```

###  Alternatives

[hhennes/module-cms

Add canonical tag to magento 2 cms pages

1631.7k](/packages/hhennes-module-cms)

PHPackages © 2026

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