Full data collector (plugin) example

As explained in the other articles, it is possible to configure a custom system for collecting the guests information, either during the pre-check-in, or for the manual guests registration made through the back-end (check-in).

If you wish to collect specific information from each room guest, then coding your own driver is the best solution, and this is done through a custom WordPress plugin that extends the native functionalities of VikBooking.

The name of the plugin we will be coding in this example is vbocustomcheckindriver ("VikBooking Custom Check-in Driver"), and you are free to adjust the various PHP files according to your own needs.

This example plugin is composed of 3 PHP files, but actually 2 PHP files only are mandatory:

1. The first PHP file is the WordPress main plugin file declaration with the required hooks for installing the custom driver, it is called vbocustomcheckindriver.php and the name of this file must match your "text domain" in order to support custom translations for the various field labels, optionally into multiple languages, thanks to the WordPress native functions.
2. The second PHP file is for declaring a new guest data collection driver for VikBooking. This is the main PHP file to control the whole custom integration, and it's called custom.php.
3. The third PHP file is optional, but since this is a full explanatory plugin example, the article shows also how to code a custom type of field in HTML format. The PHP file is called myfieldtype.php, and it will declare a new guest field of a custom type that is displayed only for the main guest of every room booked.

The screenshot below shows the directory tree for our custom WordPress plugin, where the above mentioned 3 PHP files are visible in their respective directories:

Main WordPress plugin file

The code snippet below shows the full source code of the file vbocustomcheckindriver.php, which should be placed in the root of the plugin's directory /vbocustomcheckindriver.

<?php
/*
Plugin Name:  VikBooking Custom Check-in Driver
Plugin URI:   https://vikwp.com/plugin/vikbooking
Description:  Custom check-in driver for guests data collection in VikBooking.
Version:      1.0
Author:       E4J s.r.l.
Author URI:   https://vikwp.com
License:      GPL2
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  vbocustomcheckindriver
*/

// no direct access
defined('ABSPATH') or die('No script kiddies please!');

// register callback for filter "vikbooking_load_paxdatafields_drivers"
add_filter('vikbooking_load_paxdatafields_drivers', function($return)
{
    if (!$return)
    {
        $return = [];
    }

    /**
     * Since multiple plugins could add their own custom drivers, it is
     * necessary to always merge the paths to the driver files of this
     * plugin to any previous widget that may have already been injected.
     * Simply define an array of absolute paths to the PHP files that declare
     * the needed class by VikBooking to load a custom check-in driver.
     * 
     * In this example, we are telling VikBooking to load one custom check-in driver.
     */
    return array_merge($return, [
        // WP_PLUGIN_DIR          = absolute server path to plugin's directory
        // vbocustomcheckindriver = the name of this custom plugin
        // drivers                = a private/internal folder of this custom plugin
        // custom.php             = the class file that declares the driver
        WP_PLUGIN_DIR . '/vbocustomcheckindriver/drivers/custom.php',
    ]);
});

// make sure to load (require) the needed PHP Class(es) for this driver
add_action('plugins_loaded', function()
{
    // load main driver (mandatory operation)
    require_once dirname(__FILE__) . DIRECTORY_SEPARATOR . 'drivers' . DIRECTORY_SEPARATOR . 'custom.php';

    // require the class file for declaring a custom type of field called "myfieldtype" (this is of course optional)
    if (is_file(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'drivers' . DIRECTORY_SEPARATOR . 'myfieldtype.php')) {
        require_once dirname(__FILE__) . DIRECTORY_SEPARATOR . 'drivers' . DIRECTORY_SEPARATOR . 'myfieldtype.php';
    }
});

VikBooking main driver file

The code snippet below shows the full source code of the file custom.php, which should be placed inside the drivers directory of the plugin: /vbocustomcheckindriver/drivers.

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

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

/**
 * Helper class to support custom pax fields data collection. The driver's file name (custom.php)
 * must match the class name "VBOCheckinPaxfields" + Filename ("VBOCheckinPaxfieldsCustom").
 */
final class VBOCheckinPaxfieldsCustom extends VBOCheckinAdapter
{
    /**
     * The ID of this pax data collector class.
     * 
     * @var     string
     */
    protected $collector_id = 'custom';

    /**
     * Returns the name of the current pax data driver.
     * 
     * @return  string  The name of this driver.
     */
    public function getName()
    {
        // this is how the wp-admin section will list this driver
        return '"Custom data collector"';
    }

    /**
     * Tells whether children should be registered.
     * 
     * @param   bool    $precheckin     True if requested for front-end pre check-in.
     * 
     * @return  bool    True to also register the children.
     */
    public function registerChildren($precheckin = false)
    {
        /**
         * Return true if your driver requires children to be registered.
         * The return value can also change depending on the registration type:
         * during back-end check-in registration or during front-end pre check-in.
         * In this example we only want to register the adults, not the children.
         */
        return false;
    }

    /**
     * Returns the list of field labels. The count and keys
     * of the labels should match with the attributes.
     * 
     * @return  array   Associative list of field labels.
     */
    public function getLabels()
    {
        // these are the fields (names) processed for each room-guest registration
        return [
            'first_name'     => __('First Name', 'vbocustomcheckindriver'),
            'last_name'      => __('Last Name', 'vbocustomcheckindriver'),
            'date_birth'     => __('Date of birth', 'vbocustomcheckindriver'),
            'nationality'    => __('Nationality', 'vbocustomcheckindriver'),
            'id_type'        => __('Type of document', 'vbocustomcheckindriver'),
            'id_number'      => __('Document number', 'vbocustomcheckindriver'),
            'address'        => __('Address', 'vbocustomcheckindriver'),
            'city'           => __('City', 'vbocustomcheckindriver'),
            'zip'            => __('Postal code', 'vbocustomcheckindriver'),
            'country'        => __('Country', 'vbocustomcheckindriver'),
            'est_arrival'    => __('Estimated arrival time', 'vbocustomcheckindriver'),
            'est_departure'  => __('Estimated departure time', 'vbocustomcheckindriver'),
            'notes'          => __('Notes', 'vbocustomcheckindriver'),
        ];
    }

    /**
     * Returns the list of field attributes. The count and keys
     * of the attributes should match with the labels.
     * 
     * @return  array   Associative list of field attributes.
     * 
     * @see     the attribute of type "custom_myfieldtype" is a custom field
     *          that must be defined through a specific class file.
     */
    public function getAttributes()
    {
        // these are the fields (types) processed for each room-guest registration
        return [
            'first_name'     => 'text',
            'last_name'      => 'text',
            'date_birth'     => 'calendar',
            'nationality'    => 'country',
            'id_type'        => [
                'id_card' => __('ID card', 'vbocustomcheckindriver'),
                'visa'    => __('Visa', 'vbocustomcheckindriver'),
            ],
            'id_number'      => 'text',
            'address'        => 'text',
            'city'           => 'text',
            'zip'            => 'text',
            'country'        => 'country',
            'est_arrival'    => 'custom_myfieldtype',
            'est_departure'  => 'custom_myfieldtype',
            'notes'          => 'textarea',
        ];
    }

    /**
     * Builds the list of front-end (pre-checkin) pax fields for the extended collection type.
     * Check-in pax fields data collector implementations may override this method, if needed.
     * 
     * @param   array   $def_fields     List of default pre-checkin field labels and attributes.
     * 
     * @return  array   The list of pax fields to collect in the front-end during pre-checkin.
     */
    public function listPrecheckinFields(array $def_fields)
    {
        // use the same fields for the back-end guests registration
        $labels = $this->getLabels();
        $attributes = $this->getAttributes();

        // for pre-checkin we keep any default field of type "file" for uploading IDs
        foreach (($def_fields[1] ?? []) as $field_key => $field_type) {
            if (!is_string($field_type)) {
                // not looking for a list of options
                continue;
            }
            if (!strcasecmp($field_type, 'file') && ($def_fields[0][$field_key] ?? null)) {
                // append this pax field of type "file" for uploading IDs
                $labels[$field_key] = $def_fields[0][$field_key];
                $attributes[$field_key] = $field_type;
            }
        }

        // return the list of pre-checkin pax fields
        return [$labels, $attributes];
    }

    /**
     * Performs a validation over the guest registration fields data for a given reservation.
     * Custom drivers can override this method to implement their own validation method.
     * 
     * @param   array   $booking        The booking record involved with the guests registration.
     * @param   array   $booking_rooms  The booking room records involved with the guests registration.
     * @param   array   $data           The guests registration data to validate.
     * @param   bool    $precheckin     True if validating pre-checkin fields.
     * 
     * @return  void
     * 
     * @throws  Exception
     */
    public function validateRegistrationFields(array $booking, array $booking_rooms, array $data, bool $precheckin = true)
    {
        if (!$precheckin) {
            // no validation needed during back-end registration
            return;
        }

        // get all field labels
        $labels = $this->getLabels();

        // list of mandatory fields
        $mandatory_gfields = [
            'first_name',
            'last_name',
            'date_birth',
            'nationality',
            'id_type',
            'id_number',
            'address',
            'city',
            'zip',
            'country',
        ];

        // list of mandatory fields for the main guest
        $mandatory_main_gfields = [
            'est_arrival',
        ];

        // iterate over all rooms booked
        foreach ($booking_rooms as $index => $booking_room) {
            if (!is_array(($data[$index] ?? null)) || !$data[$index]) {
                throw new Exception(sprintf('Missing guests registration data for room #%d.', ($index + 1)), 500);
            }

            // count expected room registration guests data
            $room_adults = $booking_room['adults'] ?? 1;
            $room_children = $booking_room['children'] ?? 0;
            $room_guests = $this->registerChildren($precheckin) ? ($room_adults + $room_children) : $room_adults;

            if ($room_guests > count($data[$index])) {
                throw new Exception(sprintf('Please fill the information for all guests (%d) for room #%d.', $room_guests, ($index + 1)), 500);
            }

            // scan room guests for the expected room guest registration data
            for ($g = 1; $g <= $room_guests; $g++) {
                if (!is_array(($data[$index][$g] ?? null))) {
                    throw new Exception(sprintf('Please fill the information for the guests #%d for room #%d.', $g, ($index + 1)), 500);
                }

                // build guest mandatory fields
                $mand_fields = $mandatory_gfields;

                if ($g === 1) {
                    // merge main guest-level mandatory fields for validation
                    $mand_fields = array_merge($mand_fields, $mandatory_main_gfields);
                }

                // ensure no mandatory field is empty
                foreach ($mand_fields as $mand_gfield) {
                    if (!is_string($data[$index][$g][$mand_gfield] ?? null) || !strlen($data[$index][$g][$mand_gfield])) {
                        throw new Exception(sprintf('Please provide the information for the guest registration field "%s".', ($labels[$mand_gfield] ?? $mand_gfield)), 500);
                    }
                }
            }
        }
    }

    /**
     * Invokes a callback for the extended collection type after the pre-checkin
     * details have been stored or updated to perform certain actions.
     * 
     * @param   array   $data       The guest registration data stored.
     * @param   array   $booking    The booking record involved with the guests registration.
     * @param   array   $customer   Tptional customer record associated with the booking.
     * 
     * @return  void
     */
    public function onPrecheckinDataStored(array $data, array $booking, array $customer)
    {
        // no actions to be performed by default
        return;
    }
}

Custom field-type declaration file

The code snippet below shows the full source code of the file myfieldtype.php, which should be placed inside the drivers directory of the plugin: /vbocustomcheckindriver/drivers.

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

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

/**
 * Defines the handler for a pax field of type "custom_myfieldtype". The field's filename (myfieldtype.php)
 * must match the class name "VBOCheckinPaxfieldType" + Driver + Filename ("VBOCheckinPaxfieldTypeCustomMyfieldtype").
 */
final class VBOCheckinPaxfieldTypeCustomMyfieldtype extends VBOCheckinPaxfieldType
{
    /**
     * Renders the current pax field HTML.
     * 
     * @return  string  the HTML string to render the field.
     */
    public function render()
    {
        // get the field unique ID
        $field_id = $this->getFieldIdAttr();

        // get the guest number (fields could be displayed only to a specific guest number)
        $guest_number = $this->field->getGuestNumber();

        if ($guest_number > 1) {
            // we are parsing the Nth guest of a room, and we only want this field for the room main guest
            // return an empty string to let the system understand that this field should not be displayed
            return '';
        }

        // get the field class attribute
        $pax_field_class = $this->getFieldClassAttr();

        // get field name attribute
        $name = $this->getFieldNameAttr();

        // get the field value attribute (sanitized for an HTML attribute)
        $value = htmlspecialchars((string) $this->getFieldValueAttr(), ENT_QUOTES, 'UTF-8');

        // compose HTML content for the field
        $field_html = <<<HTML
<input type="text" id="$field_id" data-gind="$guest_number" class="$pax_field_class" name="$name" value="$value" />
HTML;

        // return the necessary HTML string to display the field
        return $field_html;
    }
}

Conclusion

Create the 3 above explained PHP files and place them in the proper directories to create your own and custom WordPress plugin that extends the default check-in and pre-check-in functionalities of VikBooking.

The plugin's main folder "vbocustomcheckindriver" can be either compressed into a ZIP archive for then being installed through the WordPress native functions (Plugins - Add New Plugin - Upload Plugin, then Activate Plugin), or it can just be uploaded via FTP onto your server, onto the directory: /wp-content/plugins.

Make sure your custom plugin is active, and then from the page "Global - Configuration" in VikBooking you can select your "Custom data collector" driver from the apposite setting. Click the save button and start testing the plugin for collecting the information from your guests.