Magendoo CustomerSegment for Magento 2

A comprehensive Customer Segmentation module for Magento 2 Community Edition that enables merchants to create dynamic customer segments based on various criteria including customer attributes, order history, shopping cart data, and behavior patterns.

Screenshots

Segment Grid — manage all your customer segments at a glance

[image: Customer Segments Grid]

Segment Editor — visual rule builder with conditions and customer matching

[image: Customer Segment Edit]

Documentation

Features

Customer Segmentation

• Dynamic Segments: Automatically assign customers based on rules
• Manual Segments: Static customer assignments
• Real-time Updates: Refresh segments on customer events
• Scheduled Updates: Cron-based segment refresh

Condition Types

Customer Attributes

• Email, First Name, Last Name
• Date of Birth, Gender
• Tax/VAT Number
• Website, Store View, Customer Group
• Account Creation Date

Order History

• Total Orders Count
• Total Revenue / Average Order Value
• First/Last Order Date
• Total Items Purchased
• Used Coupon Codes
• Payment/Shipping Methods
• Shipping Countries
• Order Status

Shopping Cart

• Cart Subtotal
• Cart Items Count
• Contains Products (by SKU)
• Has Active Cart
• Days Since Cart Activity

Product Interactions

• Viewed Categories
• Purchased Products (SKU)
• Purchased from Categories
• Wishlist Items Count

Admin Features

• Grid view of all segments with customer counts
• Create/Edit segments with visual rule builder
• Preview matching customers before saving
• "Matched Customers" tab on edit page shows assigned customers
• Refresh button on edit page
• Mass actions (Delete, Refresh)
• Export segment customers (CSV/XML)

API & Integrations

• REST API for segment management
• CLI commands for segment operations
• Integration with Cart Price Rules
• Customer grid segment filtering
• Segment indexer with mview support

Installation

Via Composer (Recommended)

composer require magendoo/module-customer-segment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Manual Installation

1. Extract files to app/code/Magendoo/CustomerSegment/
2. Run the following commands:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Configuration

Access the configuration at:

Admin → Customers → Customer Segments

Usage

Creating a Segment

1. Navigate to Customers → Customer Segments
2. Click "Add New Segment"
3. Fill in the general information:
   • Name (required)
   • Description (optional)
   • Status (Active/Inactive)
   • Refresh Mode (Manual/Cron/Real-time)
4. Configure conditions in the Conditions tab
5. Save the segment
6. Click "Refresh Segment Data" to populate customers

Segment Refresh Modes

CLI Commands

# Refresh specific segment(s)
bin/magento magendoo:customer-segment:refresh 1
bin/magento magendoo:customer-segment:refresh 1 2 3

# Refresh all active segments
bin/magento magendoo:customer-segment:refresh --all

# Export segment customers
bin/magento magendoo:customer-segment:refresh 1 --export --format=csv

Using Segments in Cart Price Rules

1. Go to Marketing → Cart Price Rules
2. Create or edit a rule
3. In the Conditions section, add condition:
   • Customer Segment → is → [Select your segment]
4. Save the rule

API Reference

REST API Endpoints

Example: Create Segment via API

curl -X POST "https://your-store.com/rest/V1/customer-segments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "segment": {
      "name": "VIP Customers",
      "description": "Customers with 10+ orders",
      "is_active": true,
      "refresh_mode": "cron",
      "conditions_serialized": "{...}"
    }
  }'

Database Structure

Tables

Events

The module dispatches the following events:

Extension Points

Adding Custom Conditions

Create a plugin to add custom conditions:

class AddCustomConditionPlugin
{
    public function afterGetNewChildSelectOptions($subject, $result)
    {
        $result[] = [
            'label' => __('My Custom Condition'),
            'value' => 'Vendor\Module\Model\Condition\MyCondition'
        ];
        return $result;
    }
}

Troubleshooting

Segments not refreshing

1. Check if the segment is Active
2. Verify cron is running: bin/magento cron:run
3. Check logs at var/log/system.log

Customers not matching

1. Verify condition logic
2. Check that customer data exists
3. Test with CLI: bin/magento magendoo:customer-segment:refresh --all

Performance issues

1. Enable batch processing (already enabled by default)
2. Use Manual refresh mode for large segments
3. Schedule refresh during low-traffic hours

Testing

Running Tests

# Run all module tests
vendor/bin/phpunit --filter Magendoo app/code/Magendoo/CustomerSegment/Test/Unit

# Run specific test class
vendor/bin/phpunit --filter SegmentManagementTest app/code/Magendoo/CustomerSegment/Test/Unit/Model/SegmentManagementTest.php

# Run with coverage
vendor/bin/phpunit --filter Magendoo --coverage-html coverage app/code/Magendoo/CustomerSegment/Test/Unit

Test Coverage

Security Tested

• ✅ CSV Injection Prevention (fputcsv)
• ✅ Formula Injection Protection
• ✅ Condition Type Allowlist
• ✅ Arbitrary Class Instantiation Prevention

See TESTING.md and TESTING_LESSONS.md for detailed testing documentation.

Support

For support and questions:

• Email: [email protected]

License

This module is licensed under the Open Software License v. 3.0 (OSL-3.0).
See LICENSE.txt for details.

Credits

Developed by Magendoo (https://magendoo.com)

Version: 1.0.1
Compatibility: Magento 2.4.x
PHP Version: 8.1+

Changelog

All notable changes to the Magendoo CustomerSegment module will be documented in this file.

The format is based on Keep a Changelog.

[1.1.0] - 2026-04-03

Added

• Product Interactions condition type (viewed categories, purchased products, purchased categories, wishlist items count) with between operator
• SqlBuilder for batch customer validation (N+1 performance fix)
• Segment indexer with mview support (etc/indexer.xml, etc/mview.xml)
• System configuration admin panel (etc/adminhtml/system.xml, etc/config.xml) for enable/disable, default refresh mode, cron schedule
• RefreshButton on segment edit page
• Matched Customers tab on segment edit page with pagination
• MatchedCustomersDataProvider for matched customers grid
• CustomerSegmentRelation model and ResourceModel for segment-customer relationships
• Product::class added to condition type allowlists (SegmentManagement + NewConditionHtml)
• Cart Price Rule integration now loads segment options from repository (was stub)
• Functional test suite (Playwright) — API, CLI, Admin UI, Integration tests
• Unit tests for Product condition and SqlBuilder

Fixed

• CRITICAL: Segment model extended AbstractModel instead of AbstractExtensibleModel — getExtensionAttributes() crashed all REST API serialization
• CRITICAL: SegmentSearchResultsInterface used short class name in @return docblock — Magento Web API reflection failed with "Class SegmentInterface does not exist" on getList endpoint
• CRITICAL: Edit controller stored full Segment model object in DataPersistor (session) — non-serializable dependencies (FormFactory/ObjectManager/Closures) caused "Serialization of 'Closure' is not allowed" fatal error on every admin page load
• Conditions blocks now load segment from DB via request param instead of DataPersistor
• Removed DataPersistorInterface dependency from Conditions blocks

Changed

• Segment model constructor now accepts ExtensionAttributesFactory and AttributeValueFactory (required by AbstractExtensibleModel)
• Version bumped to 1.1.0

[1.0.1] - 2026-04-01

Added

• Comprehensive Unit Test Suite - 106 tests with 198 assertions
  • SegmentManagement tests (31 tests) - CRUD, refresh, export, validation
  • Condition tests (75 tests) - Customer, Order, Cart, Combine conditions
  • Security-critical tests for CSV injection prevention
  • Condition type allowlist verification
  • Error handling and edge case coverage
• Testing documentation:
  • TESTING.md - Testing patterns and best practices
  • TESTING_LESSONS.md - Implementation lessons learned

Fixed

• Security: CSV export now uses fputcsv() to prevent formula injection
• Security: Condition instantiation uses allowlist to prevent arbitrary class loading
• Table prefix support in database queries
• Type mismatches in API methods
• Deprecated class replacements (Zend_Db_Expr, Registry)

Technical

• Reduced test code duplication by 30% through refactoring
• Established testing patterns for future development
• All production code issues resolved (see TESTING_LESSONS.md)

[1.0.0] - 2026-04-01

Added

• Initial release of Magendoo CustomerSegment module
• Customer segmentation with dynamic rules engine
• Three condition types: Customer Attributes, Order History, Shopping Cart
• Admin grid for segment management with filtering and mass actions
• Create, edit, delete, and refresh segments
• Three refresh modes: Manual, Cron, Real-time
• REST API for all segment operations
• CLI command for segment refresh
• Integration with Cart Price Rules
• Event system for extensibility
• Database schema with foreign key constraints
• Multi-condition support with AND/OR logic
• Customer count caching
• Export segment customers (CSV/XML)
• Full ACL support for permissions
• Observer-based real-time updates
• Comprehensive documentation

Features

• Dynamic Segments: Automatically assign customers based on rules
• Visual Rule Builder: Admin UI for building complex conditions
• Batch Processing: Efficient customer matching in batches of 1000
• Scheduled Updates: Cron-based segment refresh (default: daily at 2 AM)
• Event-Driven: Real-time updates on customer events
• API Access: Full REST API coverage
• Extensible: Plugin and event support for custom conditions

Technical

• Magento 2.4.x compatibility
• PHP 8.1+ support
• Service Contracts pattern
• Dependency Injection throughout
• Unit and integration test support
• Playwright functional tests

Future Releases (Planned)

[1.2.0] - TBD

• GraphQL API support
• Segment-based email templates
• Customer grid segment column
• Advanced reporting for segments

[1.3.0] - TBD

• Segment-based CMS content
• Segment comparison tool
• Import/Export segment definitions
• Customer segment history

[2.0.0] - TBD

• Machine learning-based segment suggestions
• Segment-based pricing
• Segment-based shipping methods
• Real-time segment webhooks