Product documentation

Documentation intended for product developers

Basic properties

• Each product is represented by one exact class
• Each extends product type class (e.g. PzpProduct), which extends class GeneralProduct
• Each implement interface GeneralProductInterface
• Each use namespace BP\Products\(Product type, e.g. Pzp)\(InsuranceCompanyName)
  
  

Product class template

/**
 * Class for ProductName
 *
 * @version 0.9.6
 */
class ProductName extends PzpProduct implements GeneralProductInterface
{
    /**
     * Reference date for age detection (REF_DATE_START / REF_DATE_CLOSURE)
     * Used in $this->clientAge
     *
     * @var string
     */
    protected $ageReferenceDate = REF_DATE_CLOSURE;

    /**
     * Required fields from first step (create)
     *
     * @var array (multidimensional)
     */
    protected $requiredInCreate = [];
    // Example
    protected $requiredInCreate = [
        Field::BLOCK_HOLDER => [
            Field::BIRTH, FIELD_LEGAL_FORM
        ]
    ];

    /**
     * Required fields from third step (complete)
     *
     * @var array (multidimensional)
     */
    protected $requiredInComplete = [];

    /**
     * Fields which are used in any step but are not required
     *
     * @var array (multidimensional)
     */
    protected $otherUsedFields = [];

    /**
     * Name to show in comparison (optional)
     *
     * @var string
     */
    protected $name = '';

    /**
     * Number of days client has to pay
     *
     * @var integer
     */
    protected $daysToPay = 30;

    /**
     * Number of days client has to pay (used in dateToPay)
     *
     * @var integer
     */
    protected $daysToPayForCalculation = null;

    /**
     * Reference date (REF_DATE_START / REF_DATE_CLOSURE)
     *
     * @var string
     */
    protected $referenceDate = REF_DATE_CLOSURE;

    /**
     * Variable to store available reinsurances
     *
     * @var array
     */
    protected $reinsurances = [];

    /**
     * Initialize variables/setting (if needed)
     *
     * @return void
     */
    public function initialize()
    {
        // Do anything you need to (similar to __construct method)
    }

    /**
     * Check if product is valid with datas from first step
     * This is called before method prices()
     * If addError is called, prices is automatically not called
     *
     * @return void
     */
    public function isValid()
    {
        if ($someProblem == true) {
            $this->addError(ERROR_CONSTANT);   // See methods documentation
        }
    }

    /**
     * Get prices of insurance
     *
     * @return array|bool
     */
    public function prices()
    {
        return [
            FREQUENCY_YEAR => 100,      // Yearly payment price
            FREQUENCY_HALF => 50,       // Half year
            FREQUENCY_QUARTER => 25     // Quarter
        ];

        // return false;   // Return false if something is wrong
    }

    /**
     * Complete contract after 4th step
     *
     * @return bool
     */
    public function contract(): bool
    {

    }

    /**
     * Called after contract is created to attach documents
     *
     * @return bool
     */
    public function documents(): bool
    {
      // Process documents  (see methods docs)
        // $this->addDocumentFromUrl($url, $type);
        // $this->addDocumentFromContents($contents, $type);

        // return $everythingWasOk ? true : false; // (if false, whole process will be rolled back)
    }

}

Inherited from GeneralProduct class

Methods and properties you can use from main class

Properties

protected string $apiUrl - Used on REST WS calls as prefix

protected string $apiCert - REST certificate file name (create folder "cert" within your product file and add that file there)

protected array $apiAuth - REST/API authentication credentials in [$login, $password] format

protected array $soapAuth - SOAP authentication credentials in [$login, $password] format

protected string $soapCert - SOAP certificate file name (create folder "cert" within your product file and add that file there)

protected bool $test - Detect if in production or not (don't set, only use to detect)

public bool $isConfirming - Detect if contract is confirming (4th step)

protected int $variant - Get actual variant from $this->variants , always INTEGER

protected string $wsdl - WSDL url used on SOAP WS calls

protected int $mapProductId - When you mapping values from another product, set id of that product

Methods

accepts(string $key): bool

/**
 * Detect if client accepted
 *
 * Add into $otherUsedFields Field::BLOCK_ACCEPTS => [ACCEPT_CONSTANT]
 *
 * @param string $key
 * @return bool
 */

addDocumentFromUrl(string $url, $type) $type Codelist

/**
 * Add document for contract from $url, called in method documents
 *
 * @param string $url
 * @param int|array $type (value/s from codelist #22)
 * @return void
 */

addDocumentFromContents(string $contents, $type) $type Codelist

/**
 * Add document for contract from $contents, called in method documents
 *
 * @param string $contents
 * @param int|array $type (value/s from codelist #22)
 * @return void
 */

addError($error, bool $showError = false)

/**
 * Used in method **isValid**, is something is wrong, call $this->addError(ERROR_CONSTANT);
 *
 * @param string|number $error (Use error constants)
 * @param bool $showError (If custom error detect if should be shown to user)
 * @return void
 */

addGridToPdf(int $page = 1, float $moveX = 0, float $moveY = 0)

/**
 * Helper to add grid to pdf to get positions
 *
 * @param integer $page
 * @param float $moveX
 * @param float $moveY
 * @return void
 */

addIncluded(string $key, ?int $value, array $data = [])

/**
 * Add things which are included in product
 *
 * @param string $key (use REINSURANCE CONSTANTS)
 * @param int $value YES/NO or null = remove
 * @param array $data (optional, reinsurance data)
 * @return void
 */

addMessage(string $message, string $type = MESSAGE_INFO, string $icon = '')

/**
 * Add message into comparison view
 *
 * @param string $message
 * @param string $type (Constants -> Product messages types)
 * @param string $icon (code from font-awesome icons, see http://fontawesome.io/icons/)
 */

addPictogram(int $key, string $desc, array $data = [])

Call in initialize()

/**
 * Add pictogram
 *
 * @param int $key (PIC_CONSTANTS)
 * @param string $desc
 * @param array $data (optional)
 * @return void
 */

addReplacement(string $key, $replacement)

/**
 * Replace value in HTML template for PDF, replaces [key] with replacement
 *
 * @param string $key
 * @param string $replacement
 */

addReplacements(array $replacements)

/**
 * Replace value in HTML template for PDF, replaces [key] with replacement
 *
 * @param array $replacements
 * [
 *      'key' => 'replacement'
 *      ...
 * ]
 */

addSeparatedTextToPdf(int $page, string $text, float $x, float $y, float $width = 5)

/**
 * Add text as letters separated with more space into pdf
 *
 * @param int $page
 * @param string $text
 * @param float $x
 * @param float $y
 * @param float $width
 * @return void
 */

addTextToPdf(int $page, $text, float $x, float $y, float $w = PDF_TEXT_DEF_WIDTH, float $h = PDF_TEXT_DEF_HEIGHT, string $align = PDF_TEXT_DEF_ALIGN, float $size = 0)

/**
 * Insert text into pdf on exact position
 *
 * @param integer $page
 * @param string $text
 * @param float $x
 * @param float $y
 * @param float $w
 * @param float $h
 * @param string $align
 * @param float $size
 * @return void
 */

broker()

/**
 * Return broker owner of this contract
 *
 * @return User
 */

canAttach(string $needs): bool

/**
  * Detect if can attach
  *
  * @param string $needs
  * @return boolean
  */

// Use example
protected function checkReinsurances(bool $allValid = false)
{
    // All reinsurances
    if ($allValid || $this->canReinsurances()) {
        // Add reinsurances for car check attach if can
        if ($allValid || $this->canAttach(NEEDS_CAR_CHECK)) {
            $this->reinsurances[] = [

callApi(string $url, $data = false, string $method = 'post', array $headers = [], bool $ignoreLog = false)

/**
 * Method calls REST WS
 *
 * @param string $url (prefixed with $this->apiUrl)
 * @param mixed $data (array with values or empty)
 * @param string $method (post, get...)
 * @param array $headers (additionals headers if needed)
 * @param bool $ignoreLog (if response shouldnt be logged)
 */

callApiJson(string $url, $json, string $method = 'post', array $headers = [], bool $ignoreLog = false)

/**
 * The same as callApi but it dedicated for calling with json
 *
 * @param string $url
 * @param string|array $json
 * @param string $method
 * @param array $headers
 * @param bool $ignoreLog
 */

callApiXml(string $url, $xml)

/**
 * The same as callApi but it dedicated for calling with xml files
 *
 * @param string $url
 * @param string $xml
 */

callSoap(string $method, array $data, array $options = [])

/**
 * Call Soap WS
 *
 * @param string $method
 * @param array $data
 * @param array $options (optional) Custom soap options
 * @return mixed
 */

checkDefaultIncluded()

/**
 * Check what is included in price from default documents
 *
 * @return void
 */

cleanValue(string|array $key)

/**
 * Use $this->get()
 */

clientAge($date = null, string $ageReferenceDate = null): int

/**
 * Return client age, depending on birth field, or $date variable
 *
 * see $ageReferenceDate property
 *
 * @param mixed $date
 * @param string|null $ageReferenceDate (if needs to override $this->ageReferenceDate)
 * @return int
 */

closure(): Carbon

/**
 * Get date of closure
 *
 * @return Carbon
 */

codelistValue(int $codelist, $value, string $field = 'name', bool $sub = false) Codelists

/**
 * Returns text (human readable) value from codelist
 *
 * @param int $codelist (see codelists)
 * @param mixed $value
 * @param string $field
 * @param bool $sub
 */

contractNumber(): string

/**
 * Returns contract number if set and needed
 *
 * @return string
 */

correspondenceAddressData() Address

/**
 * Get correspondence address data if different or false
 *
 * @return Address|bool
 */

dateToPay(): string

/**
 * Return date until client have to pay for insurance
 * Format: YYYY-MM-DD
 *
 * @return string
 */

dateToYear(string $date): int

/**
 * Convert date to year
 *
 * @return int
 */

daysToPayText(): string

/**
 * Generate readable format for days to pay
 *
 * @return string
 */

decideByDate(array $values, $date = '')

/**
 * Get value depending on refernce date
 * Returns first $value where reference date for actual product
 * falls into datefrom-dateto range
 *
 * @param array $values
 *      $values format
 *      [
 *          ',dateto' => $value1,
 *          'datefrom,dateto' => $value2,
 *          'datefrom' => $value3,
 *          'datefrom,' => $value4
 *      ]
 *      dateto/datefrom format YYYY-MM-DD
 * @param string|Carbon $date (optional)
 *      custom reference date, for example $this->closure(), $this->fullStart() if different from default reference date
 * @return mixed
 */

discount(string $key)

/**
 * Detect if discount was selected in first step
 * $key is without "discounts.", only part after
 *
 * @param string $key
 * @return mixed
 */

fromYearPrice(float $price): array

/**
 * Generate prices from year price, use in prices() method
 * When half and quarter prices are just year / (2 or 4)
 *
 * @param float $price
 * @return array
 */

fullStart()

/**
 * Return start with time
 *
 * @return Carbon
 */

fullZip(int $zip): string

/**
 * Add zeros prefix for zip if needed
 *
 * @param int $zip
 * @return string
 */

get(string|array $key) Fields

/**
 * Returns value from form from field with name = $key
 * Multidimensional are dot separated, e.g. owner[surname] => owner.surname
 * Or use $key = ['owner', 'surname']
 *
 * @param string|array $key
 * @return mixed
 */

getCarbon(string|array $key, bool $resetTime = false): Carbon Fields

/**
 * Get field value helper to convert into carbon
 *
 * @param string|array $key
 * @param bool $resetTime (set time to 00:00)
 * @return Carbon
 */

getCustom(string $key)

/**
 * Get custom data set by setCustom method
 *
 * @param string $key
 * @return mixed
 */

getSoap()

/**
 * Debug method to return soap client object
 *
 * @return Client (Extended SoapClient)
 */

holderData(): Person

/**
 * Get data for holder
 *
 * @return Person
 */

insuranceCompanyCenter(): int

/**
 * Helper to determine insurance company center
 * Only for Komunalna, Kooperativa
 *
 * @return int
 */

loadHtmlForPdf(string $html)

/**
 * Use HTML as template (background) for new PDF
 *
 * @param string $html
 */

loadPdf(string $source)

/**
 * Use PDF as template (background) for new PDF
 * Create for example /template/ folder within product folder
 * Add contract.pdf for example in that folder
 * Convert PDF file to version 1.4 (see this http://blogs.adobe.com/acrolaw/2007/10/change_pdf_versions_using_acroba/)
 *
 * @param string $source (for example $source = __DIR__ . '/template/contract.pdf' )
 */

logErrors(array $errors)

/**
 * Log errors in returned by soap/api call for example for later analysis
 *
 * @param array $errors
 */

mapValue(int $codelist, $key, int $level = 0)

/**
 * Return codelist map value for actual value
 *
 * @param int $codelist
 * @param string|int $key
 * @param int $level (equals to sub in map migrations)
 * @return mixed
 */

needs(string $key, ?bool $need = null)

/**
 * Set what will be needed after finishing contract (if not null second attribute)
 * Get if is needed (if null/empty second attribute)
 *
 * @param string $key (see contants)
 * @param bool $need (optional)
 * @return bool(if second attribute is null)|void(if setter)
 */

parseXml(string $xml, array $parse): array $parse examples/manual

/**
 * Parse XML into array
 *
 * @param string $xml
 * @param array $parse
 * @return array
 */

placeOfClosure(): string

/**
 * Get place of closure
 *
 * @return string
 */

policyholderData(): Person

/**
 * Get data for policyholder depending on form data
 *
 * @return Person
 */

priceIsSame($price): bool

/**
  * Check if price stays the same
  *
  * @param number $price
  * @return boolean
  */

// Use example
public function contract()
{
    // Check price
    $price = $this->getContractPrice();
    if (!$this->priceIsSame($price)) {
        return false;
    }
    ...

profitNumber(bool $original = false): string

/**
 * Get Actual needed profit number (ziskateľské číslo)
 *
 * @param bool $original (true = real profit number, false = WS version)
 * @return string
 */

reinsurance(string $key) (removed)

/**
 * Detect reinsurance value
 *
 * @param string $key
 * @return mixed
 */

reinsuranceData(string $key)

/**
 * Get data about reinsurance
 *
 * @param string $key
 * @return DataObject
 */

reinsuranceWants(string $key)

/**
 * Detect if reinsurance is wanted
 *
 * @param string $key
 * @return boolean
 */

removeNamespaces(string $xml): string

/**
 * Remove namespaces from xml
 *
 * @param string $xml
 * @return string
 */

savePdfAs($type)

/**
 * Save pdf as type of document
 *
 * @param int|array $type (see Constants -> Document types)
 * @return bool
 */

serieNumber()

/**
 * Get contract number from product series
 *
 * @return int
 */

setApiCustomHeader(string $key, $value)

/**
 * Set custom header for api
 *
 * @param string $key
 * @param mixed $value (if null key is unset)
 */

setContractNumber(string $number)

/**
 * Called in method contract after you determine contract number (e.g. WS returns contract number)
 *
 * @param string $key
 */

setCustom(string $key, $value)

/**
 * Set custom data for later use
 * Suitable only for small data, like prices etc, no files
 * e.g. callSoap for price return data needed in contract() method
 *
 * @param string $key
 * @param mixed $value
 * @return void
 */

setDebugValue(string $name, $value)

/**
 * Helper to add debug deta into debugger
 *
 * @param string $name
 * @param mixed $value
 * @return $value
 */

// Use example
$price = $this->setDebugValue('Base price', $base) * $this->setDebugValue('Age coefficient', $this->getAgeCoefficient());

setPaymentLink(string $link)

/**
 * Set payment link
 *
 * @param string $link
 * @return void
 */

// Use example
$result = $this->callApi(...);
$this->setPaymentLink($result->paymentLink);
$this->setContractNumber($result->number);

setPaymentNote(string $note)

/**
 * Set payment note
 *
 * @param string $note
 * @return void
 */

// Use example
$result = $this->callApi(...);
$this->setPaymentNote('Číslo PZP je 521411');
$this->setContractNumber($result->number);

setParser(array|string $key, string $method)

Tutorial here

/**
 * Helper method to set parser method for form value
 *
 * @param array|string $key (same as $key in $this->value($key))
 * @param string $method
 * @return void
 */

setStylePdf(array $style)

/**
 * Set style for pdf
 *
 * @param array $style
 *      Array of styles to set
 *          PDF_TEXT_SIZE => 12,
 *          PDF_TEXT_BOLD => true/false
 * @return void
 */

setTextationCode(string $code)

/**
 * Set special code for textations
 *
 * @param string $code
 * @return void
 */

// Use example
public function prices()
{
    $this->setTextationCode('advanced');

setTextSizePdf(float $size = PDF_TEXT_DEF_SIZE)

/**
 * Set text size for pdf
 *
 * @param float $size (optional)
 * @return void
 */

sfa(): DataObject

/**
 * Get sfa informations
 *
 * @return DataObject
 */

soapAttachements(): array

/**
 * Get attachements from soap call (MTOM helper)
 *
 * @return array
 */

value(string|array $key) Fields

/**
 * Same as method CleanValue but if exist method parse(Key) (e.g. $key = 'name' than parseName($value))
 * than value from form will be parsed through this method
 *
 * @param string $key
 */

validateCustom(array $rules, array $messages = []) Example in how to

/**
 * Helper method used to validate before confirm, using basic laravel request validation
 *
 * @param array $rules
 * @param array $messages (optional)
 */

zipData($zip, string $city): array

/**
 * Get more data about ZIP
 *
 * @param string $zip
 * @param string $city
 * @return array
 *  Format:
 *    [
 *      "zip" => "95142",
 *      "name" => "Andač",
 *      "district" => "Nitra",
 *      "code" => "NR,NI,NT",
 *      "codes" => [    // The same as explode(',', $code)
 *          "NR",
 *          "NI",
 *          "NT",
 *      ],
 *    ]
 */

Codelist map migrations

If you need insurance company codelist to be migrated into our database

1. Make /maps/ folder in your product folder

2. Create [ProductFileName]-[anyname].json file with format like this.
   For example Allianz-brands.json

   {
       "codelist": "",     // ID depending on codelist - see Codelists
       "sub": "0",         // 1 / 0 when sub codelist values or not (For now 1 only for Model codelist)
       "map": {            // Values representing foreign codelist
           "key": "value",     // key = foreign codelist value
           "key2": "value2",   // value = foreign codelist text value (if sub = 1, value = 'Text value parent; text value', e.g. 'Škoda; Fábia')
           ...
       }
   }
   

   3. Check json format, it will try to migrate only once 4. Each migration will be run only once, so always make another if needed 5. Key has to be unique or will be overridden 6. Migrations are run every 5 minutes so it needs time to be processed, please wait

Variants

If product has multiple variants you can define them in attribute $variants

Defining variants

At least one is needed to show in comparison

    public $variants = [
        [
            VARIANT_ID => self::VARIANT_CUSTOM,     // Needs to be INTEGER , constants needs to be created
            VATIANT_NAME => 'Variant name'          // Same value as in $this->name
        ],
        ...
    ];

Reinsurances

If product contains any reinsurances you have to define them in attribute $reinsurances

Defining reinsurances

• Key will be later used for defining translations, you can't define translations by yourselves
• Use keys for reinsurance from constants if possible
• Key has to be in snake_case format, should be fully lower case
• If you use custom, define class constants and use self::REINSURANCE_CONST

Checkbox type (yes / no)

$reinsurances = [
    ...
    'key_for_reinsurance',
    ...
];

Other type

$reinsurances = [
    ...
    [
        'key' => REINSURANCE_CONSTANT,
        // Optional
        'fields' => [
            ...
        ],
        'prefix' => 'Custom text before name if "custom" is not used',
        'custom' => 'Custom reinsurance name',
        'suffix' => 'Custom text after name if "custom" is not used',
        'default' => 'Default value',
        'readonly' => true,
        'info' => 'tooltip text for info icon next to reinsurance',
        'short' => 'abbreviation of reinsurance',
    ],
    ...
];

Field types

You can add more fields into reinsurance if you need them

Select type

[
    'type' => REINSURANCE_TYPE_SELECT,
    'key' => 'custom_optional_key',
    'label' => 'Custom label',
    'data' => [
        'options' => [
            REINSURANCE_EMPTY_VALUE => REINSURANCE_EMPTY_TEXT, // Empty value if needed
            'ws value' => 'Option text value', // For example 'D' => 'Balík D', '350' => '350e' ..
            ...
        ]
    ]
]

Input type

[
    'type' => REINSURANCE_TYPE_INPUT,
    'key' => 'custom_optional_key',
    'label' => 'Custom label',
    'data' => [
        'type' => '', // number|text|password|.... (optional)
        'min' => 4000, // if type number, optional
        'max' => 20000, // if type number, optional
    ]
]

Detection value

• Always when somebody change reinsurance within your product prices method will be called again.
• If you need to detect value of reinsurance chosen by user use method reinsuranceWants

  $reinsWanted = $this->reinsuranceWants(REINSURANCE_CONSTANT)
  

• If you need reinsurance fields values reinsuranceData

  $reinsData = $this->reinsuranceData(REINSURANCE_CONSTANT);
  $val = $reinsData->custom_optional_key;