README

English | 中文

A comprehensive user tagging system for Symfony applications, supporting static tags, smart tags, and SQL-based tags with category management.

Features
Installation
Configuration
Quick Start
Advanced Usage
API Reference
Requirements
License

Features

Static Tags: Manual assignment of tags to users
Smart Tags: Automatic tag assignment based on JSON rules and cron expressions
SQL Tags: Dynamic tag assignment using custom SQL queries
Category Management: Hierarchical organization of tags
Assignment Tracking: Complete audit trail of tag assignments
EasyAdmin Integration: Ready-to-use admin interface
JSON-RPC API: RESTful API for tag management

Installation

composer require tourze/user-tag-bundle

Configuration

The bundle works out of the box with minimal configuration. Services are auto-configured through services.yaml.

Quick Start

1. Register the Bundle

// config/bundles.php
return [
    // ...
    UserTagBundle\UserTagBundle::class => ['all' => true],
];

2. Configure Database

Run migrations to create the required tables:

bin/console doctrine:migrations:migrate

3. Basic Usage

use UserTagBundle\Entity\Tag;
use UserTagBundle\Entity\Category;
use UserTagBundle\Enum\TagType;

// Create a category
$category = new Category();
$category->setName('Customer Status');
$entityManager->persist($category);

// Create a static tag
$tag = new Tag();
$tag->setName('VIP Customer')
    ->setType(TagType::StaticTag)
    ->setCategory($category)
    ->setDescription('High-value customers');
$entityManager->persist($tag);

// Create a smart tag with JSON rules
$smartTag = new Tag();
$smartTag->setName('Active User')
         ->setType(TagType::SmartTag)
         ->setCategory($category);
         
$smartRule = new SmartRule();
$smartRule->setTag($smartTag)
          ->setCronStatement('0 0 * * *') // Daily at midnight
          ->setJsonStatement([
              'conditions' => [
                  ['field' => 'last_login', 'operator' => '>=', 'value' => '7 days ago']
              ]
          ]);
          
$entityManager->persist($smartTag);
$entityManager->persist($smartRule);
$entityManager->flush();

// Create a SQL-based tag
$sqlTag = new Tag();
$sqlTag->setName('Recent Buyers')
       ->setType(TagType::SqlTag)
       ->setCategory($category);
       
$sqlRule = new SqlRule();
$sqlRule->setTag($sqlTag)
        ->setSqlStatement("
            SELECT user_id 
            FROM orders 
            WHERE created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
            GROUP BY user_id 
            HAVING COUNT(*) >= 3
        ");
        
$entityManager->persist($sqlTag);
$entityManager->persist($sqlRule);
$entityManager->flush();

4. Using JSON-RPC API

// Get user tags
$procedure = new GetUserTagList();
$result = $procedure->execute();

// Assign tag to user
$assignProcedure = new AssignTagToBizUser();
$assignProcedure->setParameters([
    'tagId' => $tag->getId(),
    'bizUserId' => $userId
]);
$assignProcedure->execute();

Advanced Usage

Custom Tag Types

You can extend the system with custom tag types by implementing the TagInterface:

use UserTagBundle\Enum\TagType;

// Create a custom tag type
class CustomTagType extends TagType
{
    public const CustomType = 'custom';
}

Event Listeners

The bundle dispatches events that you can listen to:

use UserTagBundle\Event\BeforeAddTagEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class TagEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            BeforeAddTagEvent::class => 'onBeforeAddTag',
        ];
    }

    public function onBeforeAddTag(BeforeAddTagEvent $event): void
    {
        // Custom logic before tag assignment
        $user = $event->getUser();
        $tag = $event->getTag();
        
        // Example: Validate business rules
        if (!$this->validateTagAssignment($user, $tag)) {
            throw new \InvalidArgumentException('Tag assignment not allowed');
        }
    }
}

Smart Tag Rules

Configure complex JSON rules for smart tags:

$smartRule->setJsonStatement([
    'conditions' => [
        [
            'field' => 'user.orders.count',
            'operator' => '>=',
            'value' => 10
        ],
        [
            'field' => 'user.totalSpent', 
            'operator' => '>',
            'value' => 1000
        ]
    ],
    'logic' => 'AND' // or 'OR'
]);

SQL Tag Examples

Dynamic tags using SQL queries:

$sqlRule->setSqlStatement("
    SELECT user_id 
    FROM orders 
    WHERE created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
    GROUP BY user_id 
    HAVING COUNT(*) >= 3
");

API Reference

JSON-RPC Procedures

Tag Management

CreateSingleUserTag - Create a new tag
UpdateSingleUserTag - Update existing tag
DeleteSingleUserTag - Delete a tag
GetUserTagList - List all tags

Category Management

CreateSingleUserTagCategory - Create a new category
UpdateSingleUserTagCategory - Update existing category
DeleteSingleUserTagCategory - Delete a category
GetUserTagCategories - List all categories

Tag Assignment

AssignTagToBizUser - Assign tag to user
UnassignTagToBizUser - Remove tag from user
GetAssignTagsByBizUserId - Get user's assigned tags
AdminGetAssignLogsByTag - Get assignment history

Entities

Tag - Main tag entity with support for different types
Category - Hierarchical category system
SmartRule - JSON-based rules for smart tags
SqlRule - SQL-based rules for dynamic tags
AssignLog - Assignment tracking and audit trail

Requirements

PHP 8.1+
Symfony 6.4+
Doctrine ORM 3.0+
Doctrine DBAL 3.0+

Required Packages

symfony/framework-bundle
doctrine/orm
doctrine/doctrine-bundle
tourze/doctrine-timestamp-bundle
tourze/doctrine-snowflake-bundle
tourze/arrayable

License

This bundle is released under the MIT License. See the LICENSE file for details.

tourze / user-tag-bundle

Maintainers

Details