PHPackages                             salesrender/plugin-core-macros - 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. salesrender/plugin-core-macros

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

salesrender/plugin-core-macros
==============================

SalesRender plugin macros core

0.19.1(2y ago)01881proprietaryPHPPHP >=7.4.0

Since Jun 24Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/SalesRender/plugin-core-macros)[ Packagist](https://packagist.org/packages/salesrender/plugin-core-macros)[ RSS](/packages/salesrender-plugin-core-macros/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (63)Used By (1)

Plugin Core Macros
==================

[](#plugin-core-macros)

> Type-specific core framework for SalesRender macros plugins

Overview
--------

[](#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
------------

[](#installation)

```
composer require salesrender/plugin-core-macros
```

**Requirements:**

- PHP >= 7.4
- Extensions: `ext-json`

**Dependencies:**

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

Architecture
------------

[](#architecture)

### How This Core Extends plugin-core

[](#how-this-core-extends-plugin-core)

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

#### WebAppFactory

[](#webappfactory)

```
namespace SalesRender\Plugin\Core\Macros\Factories;

class WebAppFactory extends \SalesRender\Plugin\Core\Factories\WebAppFactory
{
    public function build(): App
    {
        $this
            ->addCors()
            ->addBatchActions();

        return parent::build();
    }
}
```

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:

MethodPathActionDescription`POST``/protected/batch/prepare``BatchPrepareAction`Creates a new batch with filters, sort, and arguments`GET``/protected/forms/batch/{number}``GetBatchFormAction`Returns batch step form (1-10)`PUT``/protected/data/batch/{number}``PutBatchOptionsAction`Saves batch step options`POST``/protected/batch/run``BatchRunAction`Starts batch execution`GET``/process``ProcessAction`Returns batch process status`GET``/protected/autocomplete/{name}``AutocompleteAction`Autocomplete suggestions`GET``/protected/preview/table/{name}``TablePreviewAction`Table preview data`GET``/protected/preview/markdown/{name}``MarkdownPreviewAction`Markdown preview#### ConsoleAppFactory

[](#consoleappfactory)

```
namespace SalesRender\Plugin\Core\Macros\Factories;

class ConsoleAppFactory extends \SalesRender\Plugin\Core\Factories\ConsoleAppFactory
{
    public function build(): Application
    {
        $this->addBatchCommands();
        return parent::build();
    }
}
```

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

CommandClassDescription`batch:queue``BatchQueueCommand`Picks up queued batches and spawns handler processes`batch:handle``BatchHandleCommand`Executes the batch handler for a specific batchThese commands are also automatically registered as cron tasks (every minute) by the base `ConsoleAppFactory` when a `BatchContainer` handler is configured.

### Batch Processing Flow

[](#batch-processing-flow)

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

```
1. PREPARE    POST /protected/batch/prepare     -- Create batch with FSP (Filters, Sort, Pagination)
2. CONFIGURE  GET  /protected/forms/batch/{n}   -- Get configuration form for step N
              PUT  /protected/data/batch/{n}    -- Submit configuration for step N
              (repeat for steps 1-10 as needed)
3. RUN        POST /protected/batch/run         -- Start processing
4. PROCESS    (async via CLI)                   -- BatchHandler iterates orders
5. STATUS     GET  /process?id={id}             -- Check progress

```

### What the Developer Must Implement

[](#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
-----------------------------------------

[](#getting-started-creating-a-macros-plugin)

### Step 1: Project Setup

[](#step-1-project-setup)

```
mkdir my-macros-plugin && cd my-macros-plugin
composer init --name="myvendor/my-macros-plugin" --type="project"
composer require salesrender/plugin-core-macros
composer require salesrender/plugin-component-purpose
```

Set up PSR-4 autoloading in `composer.json`:

```
{
  "autoload": {
    "psr-4": {
      "MyVendor\\Plugin\\Instance\\Macros\\": "src/"
    }
  }
}
```

Create the project directory structure:

```
mkdir -p src/Components src/Forms db public runtime
```

### Step 2: Bootstrap Configuration

[](#step-2-bootstrap-configuration)

Create `bootstrap.php` in the project root:

```