CoolCMS API

AbstractCarrier
in package
implements CarrierInterface uses PickupPointSanitizerTrait

AbstractYes

Table of Contents

Interfaces

CarrierInterface
Driver contract for carrier pickup points, mirroring {@see \App\UI\Api\System\PaymentGateways\Contracts\PaymentGatewayInterface}.

Constants

MAX_LENGTH_CITY  : mixed = 100
MAX_LENGTH_CODE  : mixed = 64
Length caps of the `cms_mod_eshop_order_shippers.pickup_*` columns.
MAX_LENGTH_COUNTRY  : mixed = 60
MAX_LENGTH_NAME  : mixed = 255
MAX_LENGTH_RAW  : mixed = 8000
Cap for `pickup_point_data` (text); a cheap safeguard, nothing reads the column yet.
MAX_LENGTH_STREET  : mixed = 100
MAX_LENGTH_ZIP  : mixed = 10

Methods

getWidgetConfig()  : CarrierWidgetConfig|null
Returns the config for rendering the widget on the front end. `null` means the carrier is not configured (missing API key in `Shipper::$settings`) and the front end then does not offer the pickup button.
manualPickupPoint()  : PickupPoint|null
Default manual pickup point entry: same sanitization and caps as {@see buildPickupPoint()}, and the carrier snapshot is this driver's `script_name`, so a manual entry for a carrier that has a driver stays that carrier's shipment. Drivers need not override it; the manual fields are the same for every carrier.
normalizePickupPoint()  : PickupPoint|null
Maps the raw widget payload (exactly what the widget emitted on the front end; three different return mechanisms) to the DTO. `null` means an unrecognized or unusable payload (the required point identifier is missing).
supportsPickup()  : bool
Returns whether this driver supports pickup point selection at all (as opposed to a carrier without pickup support that would be only a future placeholder in the registry).
buildManualPickupPoint()  : PickupPoint|null
Builds a point from a manual entry by an admin (order edit form).
buildPickupPoint()  : PickupPoint|null
Builds a sanitized {@see PickupPoint} from values a driver extracted from its widget payload. Returns `null` when the required `code` or `name` is empty after sanitization, since the point is unusable for an order without them.
getSetting()  : mixed
sanitizeRaw()  : string
Returns the raw payload as a capped JSON string (`pickup_point_data` is text; nothing reads it yet, it is a safeguard for later shipment creation).
sanitizeText()  : string
Strips tags (XSS from user text, widget data comes from foreign JS), collapses repeated whitespace and truncates to the length of the matching database column.
settingString()  : string
Typed variant of {@see getSetting()}. Settings are always plain strings, so this saves `(string)` casts over `mixed` at call sites (same as {@see \App\UI\Api\System\PaymentGateways\AbstractPaymentGateway::settingString()}).

Constants

MAX_LENGTH_CODE

Length caps of the `cms_mod_eshop_order_shippers.pickup_*` columns.

private mixed MAX_LENGTH_CODE = 64

MAX_LENGTH_RAW

Cap for `pickup_point_data` (text); a cheap safeguard, nothing reads the column yet.

private mixed MAX_LENGTH_RAW = 8000

Methods

getWidgetConfig()

Returns the config for rendering the widget on the front end. `null` means the carrier is not configured (missing API key in `Shipper::$settings`) and the front end then does not offer the pickup button.

public getWidgetConfig(Shipper $shipper, array{lang?: string, currency?: string, country?: string, weight?: float} $context) : CarrierWidgetConfig|null
Parameters
$shipper : Shipper
$context : array{lang?: string, currency?: string, country?: string, weight?: float}
Return values
CarrierWidgetConfig|null

manualPickupPoint()

Default manual pickup point entry: same sanitization and caps as {@see buildPickupPoint()}, and the carrier snapshot is this driver's `script_name`, so a manual entry for a carrier that has a driver stays that carrier's shipment. Drivers need not override it; the manual fields are the same for every carrier.

public manualPickupPoint(array{code?: mixed, name?: mixed, street?: mixed, city?: mixed, zip?: mixed, country?: mixed} $fields) : PickupPoint|null
Parameters
$fields : array{code?: mixed, name?: mixed, street?: mixed, city?: mixed, zip?: mixed, country?: mixed}
Return values
PickupPoint|null

normalizePickupPoint()

Maps the raw widget payload (exactly what the widget emitted on the front end; three different return mechanisms) to the DTO. `null` means an unrecognized or unusable payload (the required point identifier is missing).

public normalizePickupPoint(array<string|int, mixed> $raw) : PickupPoint|null

Sanitization is up to the implementation; no field may pass unsanitized. Nothing is verified against the carrier feed.

Parameters
$raw : array<string|int, mixed>
Return values
PickupPoint|null

supportsPickup()

Returns whether this driver supports pickup point selection at all (as opposed to a carrier without pickup support that would be only a future placeholder in the registry).

public supportsPickup() : bool
Return values
bool

buildManualPickupPoint()

Builds a point from a manual entry by an admin (order edit form).

protected buildManualPickupPoint(string $carrier, array{code?: mixed, name?: mixed, street?: mixed, city?: mixed, zip?: mixed, country?: mixed} $fields) : PickupPoint|null

Same sanitization and caps as buildPickupPoint() (single source of truth), but the input is six form text fields; raw is the JSON of the sanitized fields so that pickup_point_data keeps a readable origin. Returns null when code or name is missing (both required).

Parameters
$carrier : string
$fields : array{code?: mixed, name?: mixed, street?: mixed, city?: mixed, zip?: mixed, country?: mixed}
Return values
PickupPoint|null

buildPickupPoint()

Builds a sanitized {@see PickupPoint} from values a driver extracted from its widget payload. Returns `null` when the required `code` or `name` is empty after sanitization, since the point is unusable for an order without them.

protected buildPickupPoint(string $carrier, string|null $code, string|null $name, string|null $street, string|null $city, string|null $zip, string|null $country, array<string, mixed> $raw) : PickupPoint|null

Sanitization: strip_tags, whitespace normalization, truncation to the column length. Nothing is verified against the carrier feed.

Parameters
$carrier : string
$code : string|null
$name : string|null
$street : string|null
$city : string|null
$zip : string|null
$country : string|null
$raw : array<string, mixed>

raw widget payload, stored as truncated JSON

Return values
PickupPoint|null

getSetting()

protected getSetting(Shipper $shipper, string $key[, mixed $default = null ]) : mixed
Parameters
$shipper : Shipper
$key : string
$default : mixed = null

sanitizeRaw()

Returns the raw payload as a capped JSON string (`pickup_point_data` is text; nothing reads it yet, it is a safeguard for later shipment creation).

protected sanitizeRaw(array<string, mixed> $raw) : string
Parameters
$raw : array<string, mixed>
Return values
string

sanitizeText()

Strips tags (XSS from user text, widget data comes from foreign JS), collapses repeated whitespace and truncates to the length of the matching database column.

protected sanitizeText(mixed $value, int $maxLength) : string
Parameters
$value : mixed
$maxLength : int
Return values
string

settingString()

Typed variant of {@see getSetting()}. Settings are always plain strings, so this saves `(string)` casts over `mixed` at call sites (same as {@see \App\UI\Api\System\PaymentGateways\AbstractPaymentGateway::settingString()}).

protected settingString(Shipper $shipper, string $key[, string $default = '' ]) : string
Parameters
$shipper : Shipper
$key : string
$default : string = ''
Return values
string
On this page

Search results