Download the PHP package salesrender/plugin-core-macros without Composer

Plugin Core Macros

Type-specific core framework for SalesRender macros plugins

Overview

salesrender/plugin-core-macros is the core package for building MACROS type plugins on the SalesRender platform. Macros plugins perform bulk operations on orders -- they process orders in batches, enabling mass data export, import, field manipulation, status changes, and other automated workflows.

The key distinction of macros plugins from other types is batch processing: the ability to iterate over a set of orders (defined by filters, sort, and pagination) and apply operations to each one, tracking progress, errors, and results.

This package extends the base salesrender/plugin-core by:

• Adding batch HTTP routes (prepare, configure, run, status) via WebAppFactory
• Adding batch CLI commands (queue processing, batch handling) via ConsoleAppFactory
• Enabling CORS support by default in WebAppFactory
• Requiring the developer to implement BatchHandlerInterface for order processing logic

Installation

Requirements:

• PHP >= 7.4
• Extensions: ext-json

Dependencies:

• salesrender/plugin-core ^0.4.1
• salesrender/plugin-component-purpose ^2.0

Architecture

How This Core Extends plugin-core

plugin-core-macros provides two factory classes in the SalesRender\Plugin\Core\Macros\Factories namespace:

WebAppFactory

The macros WebAppFactory automatically adds two feature sets before building:

1. CORS support (addCors()) -- enables cross-origin requests for all routes
2. Batch actions (addBatchActions()) -- registers all batch-related HTTP routes

The addBatchActions() method (defined in the parent WebAppFactory) registers the following routes:

ConsoleAppFactory

The macros ConsoleAppFactory adds batch processing commands via addBatchCommands():

These commands are also automatically registered as cron tasks (every minute) by the base ConsoleAppFactory when a BatchContainer handler is configured.

Batch Processing Flow

The batch processing lifecycle in a macros plugin follows these steps:

What the Developer Must Implement

1. BatchHandlerInterface -- the core processing logic that iterates over orders and performs operations
2. Settings Form -- a class extending Form for plugin configuration
3. Batch Option Forms -- one or more Form classes for batch step configuration (up to 10 steps)
4. bootstrap.php -- configuration file wiring everything together

Getting Started: Creating a Macros Plugin

Step 1: Project Setup

Set up PSR-4 autoloading in composer.json:

Create the project directory structure:

Step 2: Bootstrap Configuration

Create bootstrap.php in the project root:

Key points:

• Plugin type must be PluginType::MACROS
• The fourth argument to Info::config() is a PluginPurpose object specifying the plugin class and entity
• BatchContainer::config() accepts a callable returning batch step forms and a BatchHandlerInterface implementation
• Available MacrosPluginClass values: CLASS_EXPORTER, CLASS_HANDLER, CLASS_IMPORTER
• Available PluginEntity values: ENTITY_ORDER, ENTITY_UNSPECIFIED

Step 3: Implement BatchHandlerInterface

Create src/Components/MyHandler.php:

The BatchHandlerInterface has a single method:

Process lifecycle methods:

Process states: STATE_SCHEDULED -> STATE_PROCESSING -> STATE_POST_PROCESSING -> STATE_ENDED

Batch provides:

Step 4: Create the Web Entry Point

Create public/index.php:

Note: Unlike integration plugins, macros plugins typically do not need to add custom routes. The WebAppFactory automatically registers all necessary batch routes.

Step 5: Create the Console Entry Point

Create console.php:

Step 6: Create the Settings Form

Create src/Forms/SettingsForm.php:

Step 7: Create Batch Options Form

Create src/Forms/BatchOptionsForm.php:

Batch option forms are displayed before running the batch (steps 1-10). Return null from the BatchContainer::config callable for steps that do not require configuration.

Step 8: Create the .env File

Create .env:

Step 9: Initialize and Deploy

The cron system is essential for macros plugins because batch processing runs asynchronously via the batch:queue and batch:handle commands, which are automatically scheduled every minute.

HTTP Routes

Routes Added by Macros WebAppFactory

These routes are added by the macros WebAppFactory in addition to the base plugin-core routes:

Routes Inherited from Base plugin-core

CORS headers are enabled on all routes by default.

CLI Commands

Commands Added by Macros ConsoleAppFactory

Commands Inherited from Base plugin-core

Auto-registered Cron Tasks

The macros ConsoleAppFactory automatically registers these cron tasks (every minute):

• batch:queue -- polls for queued batches and spawns handler processes
• specialRequest:queue -- polls for queued special requests

Key Interfaces

BatchHandlerInterface

This is the central interface every macros plugin must implement. The handler receives:

• Process $process -- tracks progress, errors, and result of the batch operation
• Batch $batch -- provides access to the API client, FSP (Filters/Sort/Pagination), and batch step options

The handler must:

1. Call $process->initialize($count) to set the total order count
2. Iterate over orders, calling $process->handle(), $process->skip(), or $process->addError() for each
3. Call $process->save() after processing each order to persist progress
4. Call $process->finish($result) when done

Process

Batch

BatchContainer

PluginPurpose

MacrosPluginClass values:

• MacrosPluginClass::CLASS_EXPORTER -- plugin exports order data
• MacrosPluginClass::CLASS_HANDLER -- plugin processes/modifies orders
• MacrosPluginClass::CLASS_IMPORTER -- plugin imports external data into orders

PluginEntity values:

• PluginEntity::ENTITY_ORDER -- plugin operates on orders
• PluginEntity::ENTITY_UNSPECIFIED -- entity type is unspecified

ActionInterface

Used for custom HTTP action handlers (not typically needed in macros plugins, but available).

Example Plugin

The plugin-macros-example is a comprehensive example demonstrating all features of a macros plugin.

Example Project Structure

How the Example Plugin's BatchHandler Works

From ExampleHandler.php:

Dependencies

All transitive dependencies (Slim, Symfony Console, Medoo, batch components, etc.) come from plugin-core.

See Also

• plugin-core -- Base framework for all SalesRender plugins
• plugin-core-integration -- Core for integration plugins
• plugin-core-logistic -- Core for logistic plugins
• plugin-core-chat -- Core for chat plugins
• plugin-core-pbx -- Core for PBX plugins
• plugin-macros-example -- Example macros plugin
• plugin-component-batch -- Batch processing components
• plugin-component-purpose -- Plugin purpose definitions
• plugin-component-form -- Form definitions and field types
• plugin-component-settings -- Settings storage
• plugin-component-db -- Database abstraction
• plugin-component-api-client -- SalesRender API client