Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/DISCUSSION_TEMPLATE/q-a.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ body:
id: package-version
attributes:
label: Package and version
placeholder: "packvium/packvium 1.9.0 (PHP)"
placeholder: "packvium/packvium 1.10.0 (PHP)"
validations:
required: true
- type: textarea
Expand Down
2 changes: 1 addition & 1 deletion .github/DISCUSSION_TEMPLATE/show-and-tell.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ body:
id: package-version
attributes:
label: Package and version
placeholder: "packvium/packvium 1.9.0 (PHP)"
placeholder: "packvium/packvium 1.10.0 (PHP)"
validations:
required: false
- type: textarea
Expand Down
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ body:
id: version
attributes:
label: Package version
description: The exact version installed, for example 1.9.0.
placeholder: "1.9.0"
description: The exact version installed, for example 1.10.0.
placeholder: "1.10.0"
validations:
required: true
- type: input
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ body:
id: version
attributes:
label: Package version
placeholder: "1.9.0"
placeholder: "1.10.0"
validations:
required: true
- type: textarea
Expand Down
61 changes: 61 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,67 @@ What changed in `packvium/packvium` on Packagist, release by release. The format
[Keep a Changelog](https://keepachangelog.com/1.1.0/) and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.10.0]

Overhanging pallets, gusseted bags, 24 rotations for a hull, a declared currency, an id on every
placement, a nested packer that compares carton sets, and bounds under three more objectives.
One stricter refusal: a `units` key other than `length` (see *Changed*).

### Added

- **`container.pallet_overhang_limit`** (`Packvium\Domain\OverhangLimit`): a load may pass the
deck by the stated length at each end and width at each side. Positions are measured from the
corner of the overhang zone, only the deck bears weight, and the packed pallet reports
`achieved_dimensions`, at which it is billed and handed up. Refused beside `access_directions`,
`axles`, `made_to_measure`, `obstacles`, a non-zero `void_fill_reserve_ratio` or a
`stop_index`.
- **Gusseted bags:** `deformable_boundary.kind: "gusseted_bag"` with `side_gusset_depth`;
`Container::create()` and the constructor take a trailing `?Length $sideGussetDepth`.
- **18 signed rotations for a `convex_hull` item** (`Rotation::NL_NW_PH` is `-L-W+H`), 24 in all,
in `allowedRotations`, a placement's orientation, `fixed_placements` and revision events;
`Rotation::every()`, `isSigned()`, `isUpright()`. `Rotation::all()` is unchanged, and a signed
code on any other item is `invalid_request` / `invalid_value`.
- **`placement_id` on every placement**, the canonical JSON of `[container id, x, y, z,
item_type, orientation]` in ticks. A fixed placement or a locked revision event may quote it,
the execution plan copies it, and `validate` reports `placement_id_mismatch` and
`duplicate_placement_id`.
- **`currency`** on the request and each `rate_table`, echoed as the result's `currency`; it
never changes the packing. `PackingRequest`, `Packer::pack()` and `RateTable` take a trailing
`?string $currency`, and `validate` reports `currency_mismatch`.
- **`optimality.lower_bound` and the gap under `maximum_value`, `open_dimension_height` and
`maximum_volume`**, besides `default` and `lowest_cost`; `validate` checks them.
- **`new NestedPacker(int $levelBeamWidth = 1)`** carries the K best carton sets up a level and
lets the outermost level's score choose; 1 is the greedy chain, answer for answer.
- **A made-to-measure box may keep a `void_fill_reserve_ratio`**: when the box cut tight to the
load would break the reserve, a larger one is cut.
- **`PlanRevision::stockCutBoxes()`**, and the revision issue `artifact_required`.
- **`examples/packaging.php`**: an overhanging pallet, a gusseted mailer, a cut box with a
reserve and a nested beam.

### Changed

- **`units` refuses every key but `length`**: `invalid_request` / `not_allowed` at
`/units/<key>`. 1.9 read a bare weight as grams whatever `units.weight` said; write the unit
on each weight instead.
- **`PlanRevision::derive()` stocks a box already cut to measure** that holds a locked or
verified placement, as `<type>@<revision>#<instance>` at its cut size, price and tare, where
1.9 derived a request every engine refused. `verifyChain()` checks that revision only when
given its approved artifact.
- **`keep_upright` narrows an explicit `allowed_rotations` list** in `validate`, not only the
default list.

### Fixed

- **An explicit rotation list emptied by `keep_upright` is refused at `allowed_rotations`**,
with the same named request error the independent validator checks.
- **Stocking cut boxes indexes artifact lookups once** and reports malformed consumed
machine fields as structured `invalid_revision` errors.
- **An artifact export refuses an integer past `2^53 - 1`** with `number_out_of_range`, where it
printed one up to `PHP_INT_MAX` that other engines read differently.
- **A compressible item no longer joins a rigid item's grid lattice.**
- **A mixed fraction whose whole part is `PHP_INT_MIN`** is refused as a negative measure,
where it failed later as a type error.

## [1.9.0]

No API change, but admission is stricter: some requests 1.8 accepted are now refused (see the
Expand Down
2 changes: 1 addition & 1 deletion CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: software
authors:
- name: "Packvium contributors"
website: "https://packvium.com"
version: "1.9.0"
version: "1.10.0"
license: MIT
url: "https://packvium.com"
repository-code: "https://github.com/toxakara/packvium-php"
Expand Down
34 changes: 21 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ coordinates and rotations for each item, with a reason for anything that did not
Full documentation, the constraint reference and benchmarks live at
[packvium.com](https://packvium.com).

> **Version 1.9.0 — the public API is frozen.** Field names, status codes and the
> **Version 1.10.0 — the public API is frozen.** Field names, status codes and the
> objective vector do not change without a major version, so any `1.x` is a safe upgrade
> from any earlier `1.x`.
> Read [docs/GUARANTEES.md](https://github.com/toxakara/packvium-php/blob/main/docs/GUARANTEES.md)
Expand Down Expand Up @@ -97,7 +97,7 @@ Pass numbers as strings or integers — the API has no float parameters for a me
item exteriors outward and container interiors inward before building the request.
Volumes that exceed `PHP_INT_MAX` are handled in exact decimal-string arithmetic rather
than losing precision. A JSON request's `units` sets only the length unit; a weight takes its
unit from the measure or is grams, and `units.weight` is ignored today. See
unit from the measure or is grams; any other `units` key, `weight` included, is refused. See
[docs/UNITS-AND-NUMERICS.md](https://github.com/toxakara/packvium-php/blob/main/docs/UNITS-AND-NUMERICS.md)
and [`units.php`](https://github.com/toxakara/packvium-php/blob/main/examples/units.php).

Expand Down Expand Up @@ -172,6 +172,8 @@ try {
- Since 1.8.0, `keep_upright`, `stackable`, `must_be_on_floor` and
`require_placement_coordinates` must be JSON booleans: `"no"`, `0` or `1` raises
`InvalidRequestException` with reason `wrong_type`.
- Since 1.10.0, a `units` key other than `length` is `not_allowed` at `/units/<key>`, and so
is a `rate_table.currency` that differs from the request's `currency`.

A request that is valid but does not fit completely is not an error: the result lists what
was left out, and why, in `unpacked_items`.
Expand Down Expand Up @@ -216,22 +218,23 @@ surprise people.
| File | What it shows |
| --- | --- |
| [`basic.php`](https://github.com/toxakara/packvium-php/blob/main/examples/basic.php) | The smallest useful call: items in, placements out — and the three details in it that are easy to miss. |
| [`objectives.php`](https://github.com/toxakara/packvium-php/blob/main/examples/objectives.php) | Six of the seven objectives (all but `maximum_volume`) on scenes where they genuinely disagree, including the rate card that makes the heavier shipment the cheaper one. |
| [`objectives.php`](https://github.com/toxakara/packvium-php/blob/main/examples/objectives.php) | Six of the seven objectives (all but `maximum_volume`) on scenes where they genuinely disagree, including the rate card that makes the heavier shipment the cheaper one — and the lower bound a result states, loose or attained. |
| [`constraints.php`](https://github.com/toxakara/packvium-php/blob/main/examples/constraints.php) | Upright-only, floor-only, non-stackable, top-load limits, and tags that keep two items out of the same box — plus how to read the reason an item was refused. |
| [`limits.php`](https://github.com/toxakara/packvium-php/blob/main/examples/limits.php) | A courier's refrigerated van and cargo bikes: obstacles built from `additional_boxes`, `max_items`, `tag_limits`, `eligible_container_tags` and `max_containers`, and what each one costs. |
| [`units.php`](https://github.com/toxakara/packvium-php/blob/main/examples/units.php) | Why there are no floats anywhere: fractional inches, exact ticks, and the one-tick difference between a fit and a refusal. |
| [`serialization.php`](https://github.com/toxakara/packvium-php/blob/main/examples/serialization.php) | The same request as JSON, the result in full, runners-up via `alternatives`, and exactly which mistakes are refused and which are silently ignored. |
| [`serialization.php`](https://github.com/toxakara/packvium-php/blob/main/examples/serialization.php) | The same request as JSON, the result in full with its `currency` and each `placement_id`, runners-up via `alternatives`, the signed rotations only a hull may use, and exactly which mistakes are refused and which are silently ignored. |
| [`errors.php`](https://github.com/toxakara/packvium-php/blob/main/examples/errors.php) | A web handler that turns every refusal into a 422 naming the item and the value: each `InvalidRequestException` reason, the fixed-placement refusals, and the oversize order that is not an error at all. |
| [`reproducibility.php`](https://github.com/toxakara/packvium-php/blob/main/examples/reproducibility.php) | `effortBudget` against `timeLimitMs` on four simulated hosts: a clock-stopped search that answers differently on each, a budget that answers the same on all of them, and how to read `termination`. |
| [`trucking.php`](https://github.com/toxakara/packvium-php/blob/main/examples/trucking.php) | A van with two axle ratings, a rear door and three stops: the route-legal plan, axle loads, the unloading and loading order, what the driver can reach at the first stop, and what goes wrong without `stopIndex`. |
| [`fixed_placements.php`](https://github.com/toxakara/packvium-php/blob/main/examples/fixed_placements.php) | Pack a trailer that already has four pallets on board: packing around them, the cost of one left in the wrong place, and the refusals when the record is impossible. |
| [`shapes.php`](https://github.com/toxakara/packvium-php/blob/main/examples/shapes.php) | Items that are not their box: complementary wedges sharing one crate as `convex_hull`, and a cushion that compresses under load until the crush limit refuses it. |
| [`nested.php`](https://github.com/toxakara/packvium-php/blob/main/examples/nested.php) | Units into cartons, cartons onto a pallet, in one call. |
| [`packaging.php`](https://github.com/toxakara/packvium-php/blob/main/examples/packaging.php) | Packaging that is not a rigid box: a crate overhanging its pallet deck, a gusseted mailer that holds a layer a flat one cannot, a box cut to measure that keeps room for void fill, and `new NestedPacker(2)` letting the outer level choose the cartons. |
| [`extensions.php`](https://github.com/toxakara/packvium-php/blob/main/examples/extensions.php) | Rules the request has no field for: a custom placement constraint and container selector through `ExtensionRegistry`, a custom solution scorer — and why a rule everyone must obey belongs in the request instead. |
| [`commerce.php`](https://github.com/toxakara/packvium-php/blob/main/examples/commerce.php) | Rate a shipment, apply an eligibility rule, and pin a catalog version. |
| [`execution.php`](https://github.com/toxakara/packvium-php/blob/main/examples/execution.php) | Turn a result into dock instructions: solver facts kept apart from screen text, and a step order that is injected or honestly absent — byte-identical to the other three engines. |
| [`artifacts.php`](https://github.com/toxakara/packvium-php/blob/main/examples/artifacts.php) | Hand a result to a system with no engine: one document with the plan, geometry and the request that produced it, exported as CSV and a printable HTML work order — byte-identical to the other three engines. |
| [`revisions.php`](https://github.com/toxakara/packvium-php/blob/main/examples/revisions.php) | Replan a half-loaded job: a missing item and a locked placement recorded against the approved plan, a replan that keeps the locked item in place, and a hash-chained record that notices an edit — the same digests as the other three engines. |
| [`revisions.php`](https://github.com/toxakara/packvium-php/blob/main/examples/revisions.php) | Replan a half-loaded job: a missing item and a placement locked by its `placement_id`, a replan that keeps the locked item in place, a hash-chained record that notices an edit — the same digests as the other three engines — and a box already cut to measure offered back as stock. |

```bash
php examples/objectives.php
Expand All @@ -254,18 +257,22 @@ where their answers agree.
floor-only, non-stackable, top-load limits, minimum support ratio, tag incompatibility
and per-container tag limits, item-count limits, clearance, obstacles built from unions
of boxes, two-axle load limits, delivery stops and door access.
- **Packaging that is not a rigid box.** Flat and gusseted bags, boxes cut to measure (with a
void-fill reserve if you ask for one), pallets a load may overhang by a stated margin, and
convex-hull items in all 24 orientations.
- **A solver portfolio, not one algorithm.** Regular-grid, layer, extreme-point,
maximal-space and bounded exact search, selected by problem shape and profile.
- **Answers you can check.** Every solution is re-validated by logic independent of the
search. Unplaced items come back with a reason code, not silently missing.
- **A proof, or the distance to one.** Under the `default` and `lowest_cost` objectives every
result states `optimality.lower_bound`. A complete result that attains it reports `optimal`,
which proves no packing obeying the request's rules scores better; any other carries the gap
to the bound (`gap_key`, `absolute_gap`, `relative_gap`).
- **A proof, or the distance to one.** Under every objective but `shipping_cost` and
`lowest_landed_cost`, every result states `optimality.lower_bound`. A complete result that
attains it reports `optimal`, which proves no packing obeying the request's rules scores
better; any other carries the gap to the bound (`gap_key`, `absolute_gap`, `relative_gap`).
- **Deterministic.** The same input, seed and effort budget produce the same result, and
the result says when a clock, not the budget, stopped the search.
- **Multi-container and nested.** Split across containers, or pack containers into
containers.
containers; `new NestedPacker(K)` carries the K best carton sets up a
level, so the pallet decides between them.
- **Extensible.** Register your own constraints, item orderings, candidate scorers,
container selectors or complete solvers.
- **Loading and unloading order.** `Packvium\Sequence` answers which placements a door can
Expand All @@ -278,7 +285,8 @@ where their answers agree.
Rust and JavaScript packages write.
- **Items already in place, and replanning around them.** A request's `fixed_placements`
pins items to known positions before the solve: they keep their place, carry weight and
support, and come back marked `fixed: true`. `Packvium\Revisions\PlanRevision` records what
support, and come back marked `fixed: true`. Every placement carries a `placement_id` the
same in every engine, which a fixed placement or a lock may quote. `Packvium\Revisions\PlanRevision` records what
changed on the dock — a missing item, a substituted container, a lock, a verification — as
an append-only chain linked by SHA-256, and derives the request the next plan solves.

Expand Down Expand Up @@ -367,7 +375,7 @@ Documentation, the constraint reference and the benchmarks are at
| --- | --- | --- |
| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/toxakara/packvium-python) |
| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/toxakara/packvium-php) |
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.9"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.10"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
| Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/toxakara/packvium-node) |
| Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/toxakara/packvium-wasm) |
| PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/toxakara/packvium-php-bridge) |
Expand All @@ -391,7 +399,7 @@ CodeMeta form.
@software{packvium_php,
author = {{Packvium contributors}},
title = {Packvium for PHP},
version = {1.9.0},
version = {1.10.0},
license = {MIT},
url = {https://packvium.com}
}
Expand Down
5 changes: 3 additions & 2 deletions bin/packvium
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ use Packvium\Serialization\ArrayCodec;
use Packvium\Support\PrettyJsonStream;
$input = stream_get_contents(STDIN);
if ($input === false || trim($input) === '') { fwrite(STDERR, "Expected packing JSON on stdin\n"); exit(2); }
// Streamed, not `echo json_encode(...)`: the encoded result is never held next to its array.
try { $result=ArrayCodec::pack(json_decode($input,true,512,JSON_THROW_ON_ERROR)); PrettyJsonStream::write($result,STDOUT); fwrite(STDOUT,"\n"); }
// Streamed, not `echo json_encode(...)`: the encoded result is never held next to its array,
// and its placements are built as they are written, never all at once.
try { $result=ArrayCodec::packStreamed(json_decode($input,true,512,JSON_THROW_ON_ERROR)); PrettyJsonStream::write($result,STDOUT); fwrite(STDOUT,"\n"); }
catch(Throwable $e){ fwrite(STDERR,$e->getMessage()."\n"); exit(1); }
2 changes: 1 addition & 1 deletion codemeta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"@type": "SoftwareSourceCode",
"name": "Packvium for PHP",
"description": "Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.",
"version": "1.9.0",
"version": "1.10.0",
"license": "https://spdx.org/licenses/MIT",
"author": [
{
Expand Down
2 changes: 1 addition & 1 deletion docs/GUARANTEES.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ silently — if you need them, they belong in your own layer above this library.

## Status of this release

Version `1.9.0` freezes the public API. Field names, status codes, the objective
Version `1.10.0` freezes the public API. Field names, status codes, the objective
vector, the numeric policy and the validation rules do not change without a major
version, so any `1.x` is a safe upgrade from any earlier `1.x`. A caret or tilde
constraint on `1.0` is enough; an exact pin is no longer required.
Expand Down
Loading
Loading