Download the PHP package tmonier/sylius-container-fill-plugin without Composer

Pallet & Truckload Builder for Sylius

Français : README.fr.md

B2B container filling for Sylius 2: "full pallets only", "fill the truck to 95 %", "sold by case of 6", with a fill gauge in the cart and the rules enforced at checkout.

Wholesalers of drinks, building materials, packaging or food often sell by the pallet or the truckload: a mixed pallet must be complete, a truck must be worth the trip, a product ships by whole cases. Sylius 2 has no minimum, step or multiple of quantity, and no notion of container. Checkout blocking on a total weight exists on other platforms, but nobody combines B2B container types, a binding constraint over places and payload, the split into several containers and an accessible gauge.

This plugin adds container types (pallets, trucks, sea containers, cartons), logistics data per variant, a load planner, fill rules per channel, scope and customer group, a gauge in the cart that tells the buyer what to add, and the same blocking in the shop, the shop API and the admin.

Features

Also included: translations in English, French, German, Spanish, Italian, Dutch and Polish; Twig Hooks everywhere; demo fixtures; MySQL, MariaDB and PostgreSQL support. No core entity is changed: the plugin has its own tables.

Requirements

Sylius 2.2.9 is the floor because the plugin takes part in the checkout: earlier 2.2 releases are affected by GHSA-2rv4-pjmm-7fxf and GHSA-vv4h-q2x8-74g4.

Installation

1. Require the package:

2. Register the bundle in config/bundles.php (Symfony Flex does it automatically once a recipe exists):

3. Import the configuration in config/packages/tmonier_sylius_container_fill.yaml:

4. Import the admin routes in config/routes/tmonier_sylius_container_fill.yaml:

   The shop API operation is registered with the Sylius API (/api/v2) automatically.

5. Run the migrations (plugin tables only):

6. Load the container type presets (optional, idempotent), then review them in the admin:

   tmonier_container_fill_demo adds demo products, a rule and the verified buyer [email protected] / sylius: for demo shops only.

Configuration

Sylius stores bare numbers for the variant weight and dimensions: set the units your catalog uses. The plugin stores its own data in millimetres and grams; the admin forms take kilograms.

Overrides. Nobody has the override role by default. Grant it to the administrators who may complete an order that does not meet the rules (admin order creation, admin API):

Every override is logged on the tmonier_container_fill Monolog channel and shown on the load plan of the order.

Container types

The presets are indicative figures from public sources (see SPEC.md): check them with your carriers and pallet networks (load heights from 1.8 to 2.2 m, payloads from 1000 to 1500 kg per EUR pallet).

Layer mode (1.1)

Tick Plan by layers on a single-place container type (a pallet, a carton) that has a load height (or inner height) and/or a maximum number of layers. Give each product a layer height (Logistics tab) and its units per layer for that type (capacity row). Then:

• a pallet is a stack of layers, one product per layer, heavy layers at the bottom; a partial layer takes the height of a full one but counts for its share in the fill, and a pallet with a partial layer that can be completed is not "full" (full pallets are made of full layers);
• a pallet is limited by its load height, its maximum number of layers and its payload (whichever binds is shown: "limited by stack height");
• a non-stackable product bears nothing: at most one of its layers per pallet, on top;
• the gauge draws a side view of each pallet with its layers, says how many layers still fit, and "round up to the layer" completes partial layers;
• the product page speaks in layers: "90 = 1.5 layers ≈ 18 % of a EUR pallet".

Without layer data for every product of a plan, or on a type without layer mode, the plan uses the capacities, as in 1.0. Upgrading from 1.0 needs the migration (nullable columns, layer mode off): nothing changes until you opt in.

Logistics data (Logistics tab of the variant form, or of the product form for simple products)

A product in the scope of a rule with a weight but without capacity for the container type makes the plan incomplete: the rule is not met and the gauge names the product. A product without a usable weight (empty, zero or negative; a corrupted non-numeric weight or dimension is also logged as a warning naming the variant) is ignored by the rules: it neither fills a container nor blocks the cart, so an "all products" rule does not block mixed carts. Give the product a weight to make it count.

Rules

Overloaded containers and incomplete plans fail every mode. An enabled rule whose container types are all disabled blocks the checkout of its products (flagged in the rule grid): disable the rule rather than its types. Rules apply to the lines in their scope; carts without lines in the scope of a rule show no gauge. When several rules match a line, all of them must be met (a global "at most 1 truck" rule also counts the products of a taxon rule). The load plan shown in the gauge, on the order and in the API, and counted by the per container shipping, plans each line once, with its most specific rule: product, then taxon (deepest first), then all products; at equal scope the customer group rule, then the oldest. Lines of different rules are planned in separate containers.

Shipping

• Per container of the load plan calculator: amount per channel x number of containers of the applicable rules (one when no rule applies).
• Container type rule: the shipping method is available when the load plan uses one of the selected types.

One Sylius shipment per order. The amounts are labelled indicative and the plan reads "Freight is confirmed after the order": when your per-container price commits you, confirm freight after the order or quote it (e.g. with tmonier/sylius-quote-request-plugin).

CSV import and export

Columns: variant_code;container_type;capacity;units_per_layer;units_per_case;case_weight_kg;layer_height_mm (layer_height_mm since 1.1, optional: 1.0 files import unchanged) (; or ,, UTF-8 with or without BOM). The first three are required; an empty capacity removes the capacity; empty optional columns keep the stored values. Every line is checked first: one rejected line and nothing is written (errors by line number).

Shop API

GET /api/v2/shop/orders/{tokenValue}/load-plan returns the plan of a cart (computed now, source: cart) or the plan recorded when the order was placed (source: snapshot): satisfied flag, plan (the load plan: per planning rule the container type and containers, each line counted once) and containerCount, rules (every applicable rule checked on its whole scope: container type, containers with fill %, places, weight and volume ratios, binding constraint, units per product, violations and suggestion), line violations ("sold by whole cases"). A registered customer's order is only visible to that customer. PATCH /api/v2/shop/orders/{tokenValue}/complete answers 422 while the rules are not met.

Twig hooks

The gauge is the Live component tmonier_container_fill:gauge: it listens to sylius:shop:cart_changed; its actions emit it (on the cart page they reload the page).

Screenshots

Limitations

• A commercial filling rule, not a physical loading plan: no 3D bin packing, rotation, stacking order, axle loads, securing or ADR (the carrier's responsibility).
• One container type per order (per rule), one Sylius shipment; no double deck in mega trailers; no loading metres (LDM).
• Layer mode: one product per layer (no mixed layers), single-place container types (pallets, cartons); trucks count pallet places by capacity. stackable is only used in layer mode.
• The product page preview is indicative: the cart is the reference for mixed carts.
• Rules per customer group, not per organisation.

Development

See CLAUDE.md for the local environment and commands, SPEC.md for the design and decisions.

B2B demo

This plugin is used in the Sylius B2B demo: a Sylius 2.3 shop with fictitious sample data where the B2B plugins work together. The source code, setup and fixtures of the demo are in that repository.

The demo is an example, not a production setup.

License

MIT, see LICENSE.