lib/Roundcube/rcube_addressbook.php

<?php

/**
 +-----------------------------------------------------------------------+
 | This file is part of the Roundcube Webmail client                     |
 |                                                                       |
 | Copyright (C) The Roundcube Dev Team                                  |
 |                                                                       |
 | Licensed under the GNU General Public License version 3 or            |
 | any later version with exceptions for skins & plugins.                |
 | See the README file for a full license statement.                     |
 |                                                                       |
 | PURPOSE:                                                              |
 |   Interface to the local address book database                        |
 +-----------------------------------------------------------------------+
 | Author: Thomas Bruederli <roundcube@gmail.com>                        |
 +-----------------------------------------------------------------------+
*/

/**
 * Abstract skeleton of an address book/repository
 *
 * @package    Framework
 * @subpackage Addressbook
 */
abstract class rcube_addressbook
{
    // constants for error reporting
    const ERROR_READ_ONLY     = 1;
    const ERROR_NO_CONNECTION = 2;
    const ERROR_VALIDATE      = 3;
    const ERROR_SAVING        = 4;
    const ERROR_SEARCH        = 5;

    // search modes
    const SEARCH_ALL    = 0;
    const SEARCH_STRICT = 1;
    const SEARCH_PREFIX = 2;
    const SEARCH_GROUPS = 4;

    // contact types, note: some of these are used as addressbook source identifiers
    const TYPE_CONTACT        = 0;
    const TYPE_RECIPIENT      = 1;
    const TYPE_TRUSTED_SENDER = 2;
    const TYPE_DEFAULT        = 4;
    const TYPE_WRITEABLE      = 8;
    const TYPE_READONLY       = 16;

    // public properties (mandatory)

    /** @var string Name of the primary key field of this addressbook. Used to search for previously retrieved IDs. */
    public $primary_key;

    /** @var bool True if the addressbook supports contact groups. */
    public $groups = false;

    /**
     * @var bool True if the addressbook supports exporting contact groups. Requires the implementation of
     *              get_record_groups().
     */
    public $export_groups = true;

    /** @var bool True if the addressbook is read-only. */
    public $readonly = true;

    /**
     * @var bool True if the addressbook does not support listing all records but needs use of the search function.
     */
    public $searchonly = false;

    /** @var bool True if the addressbook supports restoring deleted contacts. */
    public $undelete = false;

    /** @var bool True if the addressbook is ready to be used. See rcmail_action_contacts_index::$CONTACT_COLTYPES */
    public $ready = false;

    /**
     * @var null|string|int If set, addressbook-specific identifier of the selected group. All contact listing and
     *                      contact searches will be limited to contacts that belong to this group.
     */
    public $group_id = null;

    /** @var int The current page of the listing. Numbering starts at 1. */
    public $list_page = 1;

    /** @var int The maximum number of records shown on a page. */
    public $page_size = 10;

    /** @var string Contact field by which to order listed records. */
    public $sort_col = 'name';

    /** @var string Whether sorting of records by $sort_col is done in ascending (ASC) or descending (DESC) order. */
    public $sort_order = 'ASC';

    /** @var string[] A list of record fields that contain dates. */
    public $date_cols = [];

    /** @var array Definition of the contact fields supported by the addressbook. */
    public $coltypes = [
        'name'      => ['limit' => 1],
        'firstname' => ['limit' => 1],
        'surname'   => ['limit' => 1],
        'email'     => ['limit' => 1]
    ];

    /**
     * @var string[] vCard additional fields mapping
     */
    public $vcard_map = [];

    /** @var ?array Error state - hash array with the following fields: type, message */
    protected $error;


    /**
     * Returns addressbook name (e.g. for addressbooks listing)
     * @return string
     */
    abstract function get_name();

    /**
     * Sets a search filter.
     *
     * This affects the contact set considered when using the count() and list_records() operations to those
     * contacts that match the filter conditions. If no search filter is set, all contacts in the addressbook are
     * considered.
     *
     * This filter mechanism is applied in addition to other filter mechanisms, see the description of the count()
     * operation.
     *
     * @param mixed $filter Search params to use in listing method, obtained by get_search_set()
     * @return void
     */
    abstract function set_search_set($filter);

    /**
     * Getter for saved search properties.
     *
     * The filter representation is opaque to roundcube, but can be set again using set_search_set().
     *
     * @return mixed Search properties used by this class
     */
    abstract function get_search_set();

    /**
     * Reset saved results and search parameters
     * @return void
     */
    abstract function reset();

    /**
     * Refresh saved search set after data has changed
     *
     * @return mixed New search set
     */
    function refresh_search()
    {
        return $this->get_search_set();
    }

    /**
     * Lists the current set of contact records.
     *
     * See the description of count() for the criteria determining which contacts are considered for the listing.
     *
     * The actual records returned may be fewer, as only the records for the current page are returned. The returned
     * records may be further limited by the $subset parameter, which means that only the first or last $subset records
     * of the page are returned, depending on whether $subset is positive or negative. If $subset is 0, all records of
     * the page are returned. The returned records are found in the $records property of the returned result set.
     *
     * Finally, the $first property of the returned result set contains the index into the total set of filtered records
     * (i.e. not considering the segmentation into pages) of the first returned record before applying the $subset
     * parameter (i.e., $first is always a multiple of the page size).
     *
     * The $nocount parameter is an optimization that allows to skip querying the total amount of records of the
     * filtered set if the caller is only interested in the records. In this case, the $count property of the returned
     * result set will simply contain the number of returned records, but the filtered set may contain more records than
     * this.
     *
     * The result of the operation is internally cached for later retrieval using get_result().
     *
     * @param ?array $cols    List of columns to include in the returned records (null means all)
     * @param int    $subset  Only return this number of records of the current page, use negative values for tail
     * @param bool   $nocount True to skip the count query (select only)
     *
     * @return rcube_result_set Indexed list of contact records, each a hash array
     */
    abstract function list_records($cols = null, $subset = 0, $nocount = false);

    /**
     * Search records
     *
     * Depending on the given parameters the search() function operates in different ways (in the order listed):
     *
     * "Direct ID search" - when $fields is either 'ID' or $this->primary_key
     *     - $values is either a string of contact IDs separated by self::SEPARATOR (,) or an array of contact IDs
     *     - Any contact with one of the given IDs is returned
     *
     * "Advanced search" - when $value is an array
     *     - Each value in $values is the search value for the field in $fields at the same index
     *     - All fields must match their value to be included in the result ("AND" semantics)
     *
     * "Search all fields" - when $fields is '*' (note: $value is a single string)
     *     - Any field must match the value to be included in the result ("OR" semantics)
     *
     * "Search given fields" - if none of the above matches
     *     - Any of the given fields must match the value to be included in the result ("OR" semantics)
     *
     * All matching is done case insensitive.
     *
     * The search settings are remembered (see set_search_set()) until reset using the reset() function. They can be
     * retrieved using get_search_set(). The remembered search settings must be considered by list_records() and
     * count().
     *
     * The search mode can be set by the admin via the config.inc.php setting addressbook_search_mode.
     * It is used as a bit mask, but the search modes are exclusive (SEARCH_GROUPS is combined with one of other modes):
     *   SEARCH_ALL: substring search (*abc*)
     *   SEARCH_STRICT: Exact match search (case insensitive =)
     *   SEARCH_PREFIX: Prefix search (abc*)
     *   SEARCH_GROUPS: include groups in search results (if supported)
     *
     * When records are requested in the returned rcube_result_set ($select is true), the results will only include the
     * contacts of the current page (see list_page, page_size). The behavior is as described with the list_records
     * function, and search() can be thought of as a sequence of set_search_set() and list_records() under that filter.
     *
     * If $nocount is true, the count property of the returned rcube_result_set will contain the amount of records
     * contained within that set. Calling search() with $select=false and $nocount=true is not a meaningful use case and
     * will result in an empty result set without records and a count property of 0, which gives no indication on the
     * actual record set matching the given filter.
     *
     * The result of the operation is internally cached for later retrieval using get_result().
     *
     * @param string|string[] $fields   Field names to search in
     * @param string|string[] $value    Search value, or array of values, one for each field in $fields
     * @param int             $mode     Search mode. Sum of rcube_addressbook::SEARCH_*.
     * @param bool            $select   True if records are requested in the result, false if count only
     * @param bool            $nocount  True to skip the count query (select only)
     * @param string|string[] $required Field or list of fields that cannot be empty
     *
     * @return rcube_result_set Contact records and 'count' value
     */
    abstract function search($fields, $value, $mode = 0, $select = true, $nocount = false, $required = []);

    /**
     * Count the number of contacts in the database matching the current filter criteria.
     *
     * The current filter criteria are defined by the search filter (see search()/set_search_set()) and the currently
     * active group (see set_group()), if applicable.
     *
     * @return rcube_result_set Result set with values for 'count' and 'first'
     */
    abstract function count();

    /**
     * Return the last result set
     *
     * @return ?rcube_result_set Current result set or NULL if nothing selected yet
     */
    abstract function get_result();

    /**
     * Get a specific contact record
     *
     * @param mixed $id    Record identifier(s)
     * @param bool  $assoc True to return record as associative array, otherwise a result set is returned
     *
     * @return rcube_result_set|array Result object with all record fields
     */
    abstract function get_record($id, $assoc = false);

    /**
     * Returns the last error occurred (e.g. when updating/inserting failed)
     *
     * @return ?array Hash array with the following fields: type, message. Null if no error set.
     */
    function get_error()
    {
        return $this->error;
    }

    /**
     * Setter for errors for internal use
     *
     * @param int    $type    Error type (one of this class' error constants)
     * @param string $message Error message (name of a text label)
     */
    protected function set_error($type, $message)
    {
        $this->error = ['type' => $type, 'message' => $message];
    }

    /**
     * Close connection to source
     * Called on script shutdown
     */
    function close() { }

    /**
     * Set internal list page
     *
     * @param int $page Page number to list
     */
    function set_page($page)
    {
        $this->list_page = (int) $page;
    }

    /**
     * Set internal page size
     *
     * @param int $size Number of messages to display on one page
     */
    function set_pagesize($size)
    {
        $this->page_size = (int) $size;
    }

    /**
     * Set internal sort settings
     *
     * @param ?string $sort_col   Sort column
     * @param ?string $sort_order Sort order
     */
    function set_sort_order($sort_col, $sort_order = null)
    {
        if ($sort_col && (array_key_exists($sort_col, $this->coltypes) || in_array($sort_col, $this->coltypes))) {
            $this->sort_col = $sort_col;
        }

        if ($sort_order) {
            $this->sort_order = strtoupper($sort_order) == 'DESC' ? 'DESC' : 'ASC';
        }
    }

    /**
     * Check the given data before saving.
     * If input isn't valid, the message to display can be fetched using get_error()
     *
     * @param array &$save_data Associative array with data to save
     * @param bool  $autofix    Attempt to fix/complete record automatically
     *
     * @return bool True if input is valid, False if not.
     */
    public function validate(&$save_data, $autofix = false)
    {
        $rcube = rcube::get_instance();
        $valid = true;

        // check validity of email addresses
        foreach ($this->get_col_values('email', $save_data, true) as $email) {
            if (strlen($email)) {
                if (!rcube_utils::check_email(rcube_utils::idn_to_ascii($email))) {
                    $error = $rcube->gettext(['name' => 'emailformaterror', 'vars' => ['email' => $email]]);
                    $this->set_error(self::ERROR_VALIDATE, $error);
                    $valid = false;
                    break;
                }
            }
        }

        // allow plugins to do contact validation and auto-fixing
        $plugin = $rcube->plugins->exec_hook('contact_validate', [
                'record'  => $save_data,
                'autofix' => $autofix,
                'valid'   => $valid,
        ]);

        if ($valid && !$plugin['valid']) {
            $this->set_error(self::ERROR_VALIDATE, $plugin['error']);
        }

        if (is_array($plugin['record'])) {
            $save_data = $plugin['record'];
        }

        return $plugin['valid'];
    }

    /**
     * Create a new contact record
     *
     * @param array $save_data Associative array with save data
     *                         Keys:   Field name with optional section in the form FIELD:SECTION
     *                         Values: Field value. Can be either a string or an array of strings for multiple values
     * @param bool  $check     True to check for duplicates first
     *
     * @return mixed The created record ID on success, False on error
     */
    function insert($save_data, $check = false)
    {
        // empty for read-only address books
    }

    /**
     * Create new contact records for every item in the record set
     *
     * @param rcube_result_set $recset Recordset to insert
     * @param bool             $check  True to check for duplicates first
     *
     * @return array List of created record IDs
     */
    function insertMultiple($recset, $check = false)
    {
        $ids = [];
        if ($recset instanceof rcube_result_set) {
            while ($row = $recset->next()) {
                if ($insert = $this->insert($row, $check)) {
                    $ids[] = $insert;
                }
            }
        }

        return $ids;
    }

    /**
     * Update a specific contact record
     *
     * @param mixed $id        Record identifier
     * @param array $save_cols Associative array with save data
     *                         Keys:   Field name with optional section in the form FIELD:SECTION
     *                         Values: Field value. Can be either a string or an array of strings for multiple values
     *
     * @return mixed On success if ID has been changed returns ID, otherwise True, False on error
     */
    function update($id, $save_cols)
    {
        // empty for read-only address books
    }

    /**
     * Mark one or more contact records as deleted
     *
     * @param array $ids   Record identifiers
     * @param bool  $force Remove records irreversible (see self::undelete)
     *
     * @return int|false Number of removed records, False on failure
     */
    function delete($ids, $force = true)
    {
        // empty for read-only address books
    }

    /**
     * Unmark delete flag on contact record(s)
     *
     * @param array $ids Record identifiers
     */
    function undelete($ids)
    {
        // empty for read-only address books
    }

    /**
     * Mark all records in database as deleted
     *
     * @param bool $with_groups Remove also groups
     */
    function delete_all($with_groups = false)
    {
        // empty for read-only address books
    }

    /**
     * Sets/clears the current group.
     *
     * This affects the contact set considered when using the count(), list_records() and search() operations to those
     * contacts that belong to the given group. If no current group is set, all contacts in the addressbook are
     * considered.
     *
     * This filter mechanism is applied in addition to other filter mechanisms, see the description of the count()
     * operation.
     *
     * @param null|0|string $gid Database identifier of the group. 0/"0"/null to reset the group filter.
     */
    function set_group($group_id)
    {
        // empty for address books don't supporting groups
    }

    /**
     * List all active contact groups of this source
     *
     * @param ?string $search Optional search string to match group name
     * @param int     $mode   Search mode. Sum of self::SEARCH_*
     *
     * @return array Indexed list of contact groups, each a hash array
     */
    function list_groups($search = null, $mode = 0)
    {
        // empty for address books don't supporting groups
        return [];
    }

    /**
     * Get group properties such as name and email address(es)
     *
     * @param string $group_id Group identifier
     *
     * @return ?array Group properties as hash array, null in case of error.
     */
    function get_group($group_id)
    {
        // empty for address books don't supporting groups
        return null;
    }

    /**
     * Create a contact group with the given name
     *
     * @param string $name The group name
     *
     * @return array|false False on error, array with record props in success
     */
    function create_group($name)
    {
        // empty for address books don't supporting groups
        return false;
    }

    /**
     * Delete the given group and all linked group members
     *
     * @param string $group_id Group identifier
     *
     * @return bool True on success, false if no data was changed
     */
    function delete_group($group_id)
    {
        // empty for address books don't supporting groups
        return false;
    }

    /**
     * Rename a specific contact group
     *
     * @param string $group_id Group identifier
     * @param string $newname  New name to set for this group
     * @param string &$newid   New group identifier (if changed, otherwise don't set)
     *
     * @return string|false New name on success, false if no data was changed
     */
    function rename_group($group_id, $newname, &$newid)
    {
        // empty for address books don't supporting groups
        return false;
    }

    /**
     * Add the given contact records the a certain group
     *
     * @param string       $group_id Group identifier
     * @param array|string $ids      List of contact identifiers to be added
     *
     * @return int Number of contacts added
     */
    function add_to_group($group_id, $ids)
    {
        // empty for address books don't supporting groups
        return 0;
    }

    /**
     * Remove the given contact records from a certain group
     *
     * @param string       $group_id Group identifier
     * @param array|string $ids      List of contact identifiers to be removed
     *
     * @return int Number of deleted group members
     */
    function remove_from_group($group_id, $ids)
    {
        // empty for address books don't supporting groups
        return 0;
    }

    /**
     * Get group assignments of a specific contact record
     *
     * @param mixed $id Record identifier
     *
     * @return array List of assigned groups indexed by a group ID.
     *               Every array element can be just a group name (string), or an array
     *               with 'ID' and 'name' elements.
     * @since 0.5-beta
     */
    function get_record_groups($id)
    {
        // empty for address books don't supporting groups
        return [];
    }

    /**
     * Utility function to return all values of a certain data column
     * either as flat list or grouped by subtype
     *
     * @param string $col  Col name
     * @param array  $data Record data array as used for saving
     * @param bool   $flat True to return one array with all values,
     *                     False for hash array with values grouped by type
     *
     * @return array List of column values
     */
    public static function get_col_values($col, $data, $flat = false)
    {
        $out = [];
        foreach ((array) $data as $c => $values) {
            if ($c === $col || strpos($c, $col.':') === 0) {
                if ($flat) {
                    $out = array_merge($out, (array) $values);
                }
                else {
                    list(, $type) = rcube_utils::explode(':', $c);
                    if ($type !== null && isset($out[$type])) {
                        $out[$type] = array_merge((array) $out[$type], (array) $values);
                    }
                    else {
                        $out[$type] = (array) $values;
                    }
                }
            }
        }

        // remove duplicates
        if ($flat && !empty($out)) {
            $out = array_unique($out);
        }

        return $out;
    }

    /**
     * Compose a valid display name from the given structured contact data
     *
     * @param array $contact    Hash array with contact data as key-value pairs
     * @param bool  $full_email Don't attempt to extract components from the email address
     *
     * @return string Display name
     */
    public static function compose_display_name($contact, $full_email = false)
    {
        $contact = rcube::get_instance()->plugins->exec_hook('contact_displayname', $contact);
        $fn      = isset($contact['name']) ? $contact['name'] : '';

        // default display name composition according to vcard standard
        if (!$fn) {
            $keys = ['prefix', 'firstname', 'middlename', 'surname', 'suffix'];
            $fn   = implode(' ', array_filter(array_intersect_key($contact, array_flip($keys))));
            $fn   = trim(preg_replace('/\s+/u', ' ', $fn));
        }

        // use email address part for name
        $email = self::get_col_values('email', $contact, true);
        $email = isset($email[0]) ? $email[0] : null;

        if ($email && (empty($fn) || $fn == $email)) {
            // return full email
            if ($full_email) {
                return $email;
            }

            list($emailname) = explode('@', $email);

            if (preg_match('/(.*)[\.\-\_](.*)/', $emailname, $match)) {
                $fn = trim(ucfirst($match[1]).' '.ucfirst($match[2]));
            }
            else {
                $fn = ucfirst($emailname);
            }
        }

        return $fn;
    }

    /**
     * Compose the name to display in the contacts list for the given contact record.
     * This respects the settings parameter how to list contacts.
     *
     * @param array $contact Hash array with contact data as key-value pairs
     *
     * @return string List name
     */
    public static function compose_list_name($contact)
    {
        static $compose_mode;

        if (!isset($compose_mode)) {
            $compose_mode = (int) rcube::get_instance()->config->get('addressbook_name_listing', 0);
        }

        $get_names = function ($contact, $fields) {
            $result = [];
            foreach ($fields as $field) {
                if (!empty($contact[$field])) {
                    $result[] = $contact[$field];
                }
            }
            return $result;
        };

        switch ($compose_mode) {
        case 3:
            $names = $get_names($contact, ['firstname', 'middlename']);
            if (!empty($contact['surname'])) {
                array_unshift($names, $contact['surname'] . ',');
            }
            $fn = implode(' ', $names);
            break;
        case 2:
            $keys = ['surname', 'firstname', 'middlename'];
            $fn   = implode(' ', $get_names($contact, $keys));
            break;
        case 1:
            $keys = ['firstname', 'middlename', 'surname'];
            $fn   = implode(' ', $get_names($contact, $keys));
            break;
        case 0:
            if (!empty($contact['name'])) {
                $fn = $contact['name'];
            }
            else {
                $keys = ['prefix', 'firstname', 'middlename', 'surname', 'suffix'];
                $fn   = implode(' ', $get_names($contact, $keys));
            }
            break;
        default:
            $plugin = rcube::get_instance()->plugins->exec_hook('contact_listname', ['contact' => $contact]);
            $fn     = $plugin['fn'];
        }

        $fn = trim($fn, ', ');
        $fn = preg_replace('/\s+/u', ' ', $fn);

        // fallbacks...
        if ($fn === '') {
            // ... display name
            if (isset($contact['name']) && ($name = trim($contact['name']))) {
                $fn = $name;
            }
            // ... organization
            else if (isset($contact['organization']) && ($org = trim($contact['organization']))) {
                $fn = $org;
            }
            // ... email address
            else if (($email = self::get_col_values('email', $contact, true)) && !empty($email)) {
                $fn = $email[0];
            }
        }

        return $fn;
    }

    /**
     * Build contact display name for autocomplete listing
     *
     * @param array  $contact Hash array with contact data as key-value pairs
     * @param string $email   Optional email address
     * @param string $name    Optional name (self::compose_list_name() result)
     * @param string $templ   Optional template to use (defaults to the 'contact_search_name' config option)
     *
     * @return string Display name
     */
    public static function compose_search_name($contact, $email = null, $name = null, $templ = null)
    {
        static $template;

        if (empty($templ) && !isset($template)) {  // cache this
            $template = rcube::get_instance()->config->get('contact_search_name');
            if (empty($template)) {
                $template = '{name} <{email}>';
            }
        }

        $result = $templ ?: $template;

        if (preg_match_all('/\{[a-z]+\}/', $result, $matches)) {
            foreach ($matches[0] as $key) {
                $key   = trim($key, '{}');
                $value = '';

                switch ($key) {
                case 'name':
                    $value = $name ?: self::compose_list_name($contact);

                    // If name(s) are undefined compose_list_name() may return an email address
                    // here we prevent from returning the same name and email
                    if ($name === $email && strpos($result, '{email}') !== false) {
                        $value = '';
                    }

                    break;

                case 'email':
                    $value = $email;
                    break;
                }

                if (empty($value)) {
                    $value = strpos($key, ':') ? $contact[$key] : self::get_col_values($key, $contact, true);
                    if (is_array($value) && isset($value[0])) {
                        $value = $value[0];
                    }
                }

                if (!is_string($value)) {
                    $value = '';
                }

                $result = str_replace('{' . $key . '}', $value, $result);
            }
        }

        $result = preg_replace('/\s+/u', ' ', $result);
        $result = preg_replace('/\s*(<>|\(\)|\[\])/u', '', $result);
        $result = trim($result, '/ ');

        return $result;
    }

    /**
     * Create a unique key for sorting contacts
     *
     * @param array  $contact  Contact record
     * @param string $sort_col Sorting column name
     *
     * @return string Unique key
     */
    public static function compose_contact_key($contact, $sort_col)
    {
        $key = $contact[$sort_col];

        // add email to a key to not skip contacts with the same name (#1488375)
        if (($email = self::get_col_values('email', $contact, true)) && !empty($email)) {
            $key .= ':' . implode(':', (array)$email);
        }

        // Make the key really unique (as we e.g. support contacts with no email)
        $key .= ':' . $contact['sourceid'] . ':' . $contact['ID'];

        return $key;
    }

    /**
     * Compare search value with contact data
     *
     * @param string       $colname Data name
     * @param string|array $value   Data value
     * @param string       $search  Search value
     * @param int          $mode    Search mode
     *
     * @return bool Comparison result
     */
    protected function compare_search_value($colname, $value, $search, $mode)
    {
        // The value is a date string, for date we'll
        // use only strict comparison (mode = 1)
        // @TODO: partial search, e.g. match only day and month
        if (in_array($colname, $this->date_cols)) {
            return (($value = rcube_utils::anytodatetime($value))
                && ($search = rcube_utils::anytodatetime($search))
                && $value->format('Ymd') == $search->format('Ymd'));
        }

        // Gender is a special value, must use strict comparison (#5757)
        if ($colname == 'gender') {
            $mode = self::SEARCH_STRICT;
        }

        // composite field, e.g. address
        foreach ((array) $value as $val) {
            $val = mb_strtolower($val);

            if ($mode & self::SEARCH_STRICT) {
                $got = ($val == $search);
            }
            else if ($mode & self::SEARCH_PREFIX) {
                $got = ($search == substr($val, 0, strlen($search)));
            }
            else {
                $got = (strpos($val, $search) !== false);
            }

            if ($got) {
                return true;
            }
        }

        return false;
    }
}