Conditional Rule Driver File

A custom Conditional Rule driver is a PHP file that declares a class with a proper name according to the file name, that extends the parent abstract class of VikBooking. This means that specific methods must be implemented to define the filters (settings) of the rule, as well as to verify their compliance against the given reservation and room-reservation data.

It is strongly recommended to look at the source code of one of the existing Conditional Text Rules pre-installed in VikBooking in order to understand the logic of the framework, and how to implement your own rule. There are many simple rules available by default in VikBooking, such as the one to match a specific room or a minimum number of nights of stay. You should start from an existing PHP file to clone it, rename it, and give the PHP class a proper name according to the file name.

The below example shows how to declare the PHP class and how to implement the mandatory methods in a custom Conditional Rule file.

<?php
/**
 * @package     VikBooking
 * @subpackage  custom_one_conditional_rule
 */

defined('ABSPATH') or die('No script kiddies please!');

/**
 * Conditional Rule "Custom One" child Class of VikBookingConditionalRule
 */
class VikBookingConditionalRuleCustomOne extends VikBookingConditionalRule
{
    /**
     * Class constructor will define the rule name, description and identifier.
     */
    public function __construct()
    {
        // call parent constructor
        parent::__construct();

        $this->ruleName  = 'Custom One';
        $this->ruleDescr = 'A dummy example about number of nights';
        $this->ruleId    = basename(__FILE__);
    }

    /**
     * Displays the rule parameters (settings).
     * 
     * @return  void
     */
    public function renderParams()
    {
        ?>
        <div class="vbo-param-container">
            <div class="vbo-param-label">Number of nights</div>
            <div class="vbo-param-setting">
                <input type="number" name="<?php echo $this->inputName('nights'); ?>" value="<?php echo $this->getParam('nights', ''); ?>" min="1" />
            </div>
        </div>
        <?php
    }

    /**
     * Tells whether the rule is compliant.
     * 
     * @return  bool    True on success, false otherwise.
     */
    public function isCompliant()
    {
        $booking_nights = (int)$this->getPropVal('booking', 'days', 0);

        $setting_nights = (int)$this->getParam('nights', 1);

        // return true if number of nights for this booking is equal to the setting value
        return $booking_nights === $setting_nights;
    }
}

This sample code will add a new rule available for selection on any Conditional Text. The settings will let you enter an exact number of nights of stay, and the compliance validation method will return "true" if the booking is for that exact number of nights of stay. If all rules within your conditional text will result compliant, the text will be used in your email notification, cron job or anywhere you're using the conditional text instruction string.

Feel free to debug the objects in the various methods, or to check the original source code of the parent abstract class "VikBookingConditionalRule".

Manipulate rule message with dynamic values and remote HTTP connections

This section shows how to code a custom Conditional Text Rule that will fetch from a remote endpoint URL the door/lock code for the booked apartment(s).

We will show how to declare a new rule-driver called apartmentcode.php that your custom plugin could load, and you could extend this sample script to fetch door/lock codes from a third-party service provider.

<?php
/**
 * @package     VikBooking
 * @subpackage  apartmentcode_conditional_rule
 */

defined('ABSPATH') or die('No script kiddies please!');

/**
 * Conditional Rule "Apartment code" child Class of VikBookingConditionalRule
 */
class VikBookingConditionalRuleApartmentcode extends VikBookingConditionalRule
{
    /**
     * Class constructor will define the rule name, description and identifier.
     */
    public function __construct()
    {
        // call parent constructor
        parent::__construct();

        $this->ruleName  = 'Apartment Code';
        $this->ruleDescr = 'An example to obtain a remote lock code for an apartment ID.';
        $this->ruleId    = basename(__FILE__);
    }

    /**
     * Displays the rule parameters (settings).
     * 
     * @return  void
     */
    public function renderParams()
    {
        // build the list of rule params to collect during the configuration
        $params = [
            'apartment_ids' => [
                'type'     => 'listings',
                'label'    => 'Apartments',
                'multiple' => true,
                'asset_options' => [
                    'allowClear'  => true,
                ],
            ],
            'endpoint_url' => [
                'type'  => 'text',
                'label' => 'Endpoint URL',
                'help'  => 'Specify the remote URL to connect to for getting the apartment lock code.',
            ],
            'username' => [
                'type'  => 'text',
                'label' => 'Endpoint username',
            ],
            'password' => [
                'type'  => 'password',
                'label' => 'Endpoint password',
            ],
        ];

        // build the list of current rule settings that were saved
        $settings = (array) $this->getParams();

        // render all params/settings for this custom rule
        echo VBOParamsRendering::getInstance(
            $params,
            $settings
        )->setInputName(basename($this->ruleId, '.php'))->getHtml();
    }

    /**
     * Tells whether the rule is compliant.
     * 
     * @return  bool    True on success, false otherwise.
     */
    public function isCompliant()
    {
        // get the rooms booked within the current reservation
        $rooms_booked = array_column((array) $this->getProperty('rooms', []), 'idroom');

        // get the eventually filtered apartments through the rule settings
        $allowed_rooms = (array) $this->getParam('apartment_ids', []);

        if (!$allowed_rooms) {
            // rule is always compliant when no listing IDs have been filtered through the settings
            return true;
        }

        // return true if the rooms booked are all present in the filtered listing IDs
        return !array_diff(array_map('intval', $rooms_booked), array_map('intval', $allowed_rooms));
    }

    /**
     * Allows to manipulate the message of the conditional text with dynamic contents.
     * 
     * @override
     * 
     * @param   string  $msg    The configured conditional text message.
     * 
     * @return  string          The manipulated conditional text message.
     */
    public function manipulateMessage($msg)
    {
        // access the rule settings for the remote endpoint connection
        $endpoint_url = $this->getParam('endpoint_url', '');
        $username     = $this->getParam('username', '');
        $password     = $this->getParam('password', '');

        // access again the rooms booked within the current reservation
        $rooms_booked = array_column((array) $this->getProperty('rooms', []), 'idroom');

        /**
         * You can now perform a custom POST request to the remote endpoint URL
         * to obtain the lock codes for the booked rooms. This example is generating
         * a random code that will be used to manipulate the message of the conditional text.
         */
        $apartment_code = rand();

        if (strpos($msg, '{apartment_code}') !== false) {
            // the text of the conditional text rule contains a placeholder that we can replace
            $msg = str_replace('{apartment_code}', $apartment_code, $msg);
        } else {
            // we do not have a placeholder tag, so we append the code to the text message
            $msg .= '<p>Your apartment code is: ' . $apartment_code . '</p>';
        }

        // return the manipulated message
        return $msg;
    }
}