CoolCMS API

BalikovnaCarrier extends AbstractCarrier
in package

FinalYes

Balikovna (Czech Post) widget: a search dialog embedded as an `<iframe>`.

No JS is loaded, so scriptUrl carries the iframe src (the front end recognizes from mechanism that it renders an <iframe>, not a <script>).

IMPORTANT: there is no API key; the widget is publicly embeddable. The contract of CarrierInterface::getWidgetConfig() says "null = missing API key", but this driver returns null only when the carrier is explicitly disabled in settings (disabled[1]).

Table of Contents

Constants

EVENT_NAME  : mixed = 'pickerResult'
Value of `event.data.message` in the returning `postMessage`.
IFRAME_BASE_URL  : mixed = 'https://b2c.cpost.cz/locations/'
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

getLabel()  : string
Returns the readable name for the admin select ({@see \App\UI\Api\Eshop\Carriers\CarrierRegistry::getOptions()}).
getScriptName()  : string
Returns the driver identity, the value of `Shipper::$scriptName` (packeta, balikovna, ppl).
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 `event.data` (`{message, id, point, phone}`), where `point` is the point itself.
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

EVENT_NAME

Value of `event.data.message` in the returning `postMessage`.

private mixed EVENT_NAME = 'pickerResult'

IFRAME_BASE_URL

private mixed IFRAME_BASE_URL = 'https://b2c.cpost.cz/locations/'

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

getLabel()

Returns the readable name for the admin select ({@see \App\UI\Api\Eshop\Carriers\CarrierRegistry::getOptions()}).

public getLabel() : string
Return values
string

getScriptName()

Returns the driver identity, the value of `Shipper::$scriptName` (packeta, balikovna, ppl).

public getScriptName() : string
Return values
string

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 `event.data` (`{message, id, point, phone}`), where `point` is the point itself.

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

IMPORTANT: only zip and name may go on the address label (the word "Balikovna", postcode, branch name). point.address may carry a different postcode than the branch point.zip, so it must not be used on the label; street and city stay empty on purpose and point.address is informative only (shown in the widget), not invoice data.

code is point.id, the only field that identifies the point; shipment submission uses it together with zip and name (those go to name/zip, not code).

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