core/src/Shipping/DTOs/ShipmentRequest.php

<?php

namespace Modules\Core\Shipping\DTOs;

/**
 * Carrier-agnostic input for CarrierFulfillmentInterface::createShipment().
 * Every field is optional — a carrier reads only what it needs and ignores
 * the rest (e.g. destinationLocationId/boxes only matter to locker-delivery
 * carriers like Box Now; ACS has no use for either — it ships by weight,
 * not by box/compartment size).
 */
class ShipmentRequest
{
    /**
     * @param  array<int, string>  $boxes  Box Now only — one entry per
     *   physical parcel, each a compartment size ('S'|'M'|'L'). A single
     *   shipment can be split across several lockers of the same
     *   destinationLocationId's collection point, e.g. two Large boxes for
     *   an order that doesn't fit one compartment. Empty for every other
     *   carrier, which ships as a single package described by $weight
     *   instead.
     */
    public function __construct(
        public readonly ?float $weight = null,
        public readonly int $packageCount = 1,
        public readonly ?string $destinationLocationId = null,
        public readonly ?string $paymentMode = null,
        public readonly ?float $amountToCollect = null,
        public readonly array $boxes = [],
    ) {}
}