survos/shape-contracts

Shared value objects for physical shape, dimensions, and measurement units.

2.6.0 2026-05-28 12:58 UTC

Requires

• php: ^8.4

Requires (Dev)

• phpunit/phpunit: ^13.0
• symplify/easy-coding-standard: ^13.0

MIT

README

Shared PHP value objects for physical shape and dimensions.

This package is deliberately framework-free. It defines the stable payload that importers, DTO contracts, folio browsing, Symfony bundles, Doctrine storage, parsers, and UI renderers can agree on.

Scope

shape-contracts owns:

• unit identifiers and conversion to millimeters
• immutable single-axis lengths
• immutable physical shape values with nullable axes
• normalized array round-tripping for JSON/DTO payloads

It does not own Symfony services, Doctrine mapping, Twig filters, form types, icons, or free-text parsing. Those belong in survos/shape-bundle or survos/dimensions-bundle.

Example

use Survos\ShapeContracts\Length;
use Survos\ShapeContracts\Shape;
use Survos\ShapeContracts\Unit;

$shape = new Shape(
    width: Length::from(18, Unit::CM),
    height: Length::from(22, Unit::CM),
    source: '18 x 22 cm',
);

$shape->toNormalizedArray();
// [
//   'widthMm' => 180,
//   'heightMm' => 220,
//   'depthMm' => null,
//   'lengthMm' => null,
//   'thicknessMm' => null,
//   'diameterMm' => null,
//   'label' => null,
//   'source' => '18 x 22 cm',
// ]

Normalized JSON shape

Use camel-case millimeter keys so JSON can be copied directly into DTO data:

{
  "widthMm": 180,
  "heightMm": 220,
  "depthMm": null,
  "lengthMm": null,
  "thicknessMm": null,
  "diameterMm": null,
  "label": null,
  "source": "18 x 22 cm"
}

The original source/display string should remain in the museum dimensions field when available. The structured shape is a companion field for consistent storage, querying, and rendering.