CoolCMS API

PplCarrier extends AbstractCarrier
in package

Application

FinalYes

PPL Access Point Widget 2.0: the Web Component `<ppl-access-point-widget>`.

The loader is https://www.ppl.cz/accesspointwidget/loader.js; the selection returns through the CustomEvent ppl-accesspointwidget-select with the payload in event.detail.

IMPORTANT: the older "PPL Parcelshop" widget (main.js, div#ppl-parcelshop-map, a DOM event on document, no API key) is intentionally not implemented because PPL retires it.

Constants

ELEMENT_TAG : mixed = 'ppl-access-point-widget'
EVENT_NAME : mixed = 'ppl-accesspointwidget-select': Event name for `document.getElementById(...).addEventListener(...)`.
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
SCRIPT_URL : mixed = 'https://www.ppl.cz/accesspointwidget/loader.js'

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.detail` (`DetailResponseModel`). Its `code` (format `KM...`) is the only field documented as the point identifier used by the PPL API to create a shipment, so it goes directly to `code`.
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()}).

ELEMENT_TAG


    private
        mixed
    ELEMENT_TAG
    = 'ppl-access-point-widget'

EVENT_NAME

Event name for `document.getElementById(...).addEventListener(...)`.


    private
        mixed
    EVENT_NAME
    = 'ppl-accesspointwidget-select'

MAX_LENGTH_CITY


    private
        mixed
    MAX_LENGTH_CITY
    = 100

MAX_LENGTH_CODE

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


    private
        mixed
    MAX_LENGTH_CODE
    = 64

MAX_LENGTH_COUNTRY


    private
        mixed
    MAX_LENGTH_COUNTRY
    = 60

MAX_LENGTH_NAME


    private
        mixed
    MAX_LENGTH_NAME
    = 255

MAX_LENGTH_RAW

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


    private
        mixed
    MAX_LENGTH_RAW
    = 8000

MAX_LENGTH_STREET


    private
        mixed
    MAX_LENGTH_STREET
    = 100

MAX_LENGTH_ZIP


    private
        mixed
    MAX_LENGTH_ZIP
    = 10

SCRIPT_URL


    private
        mixed
    SCRIPT_URL
    = 'https://www.ppl.cz/accesspointwidget/loader.js'

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.detail` (`DetailResponseModel`). Its `code` (format `KM...`) is the only field documented as the point identifier used by the PPL API to create a shipment, so it goes directly to `code`.


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

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

PplCarrier extends AbstractCarrier in package Application

Table of Contents

Constants

Methods

Constants

ELEMENT_TAG

EVENT_NAME

MAX_LENGTH_CITY

MAX_LENGTH_CODE

MAX_LENGTH_COUNTRY

MAX_LENGTH_NAME

MAX_LENGTH_RAW

MAX_LENGTH_STREET

MAX_LENGTH_ZIP

SCRIPT_URL

Methods

getLabel()

Return values

getScriptName()

Return values

getWidgetConfig()

Parameters

Return values

manualPickupPoint()

Parameters

Return values

normalizePickupPoint()

Parameters

Return values

supportsPickup()

Return values

buildManualPickupPoint()

Parameters

Return values

buildPickupPoint()

Parameters

Return values

getSetting()

Parameters

sanitizeRaw()

Parameters

Return values

sanitizeText()

Parameters

Return values

settingString()

Parameters

Return values

PplCarrier extends AbstractCarrier
in package

Application