Define @package and @subpackage of Framework classes

Aleksander Machniak

2012-11-17 9ab34604d94270f6c1795c7dd7b615273d05db0c

 program/include/rcube_addressbook.php

@@ -5,8 +5,11 @@
 | program/include/rcube_addressbook.php                                 |
 |                                                                       |
 | This file is part of the Roundcube Webmail client                     |
 | Copyright (C) 2006-2011, The Roundcube Dev Team                       |
 | Licensed under the GNU GPL                                            |
 | Copyright (C) 2006-2012, 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                        |
@@ -14,16 +17,14 @@
 +-----------------------------------------------------------------------+
 | Author: Thomas Bruederli <roundcube@gmail.com>                        |
 +-----------------------------------------------------------------------+

 $Id$

*/


/**
 * Abstract skeleton of an address book/repository
 *
 * @package Addressbook
 * @package    Framework
 * @subpackage Addressbook
 */
abstract class rcube_addressbook
{
@@ -44,6 +45,8 @@
    public $group_id = null;
    public $list_page = 1;
    public $page_size = 10;
    public $sort_col = 'name';
    public $sort_order = 'ASC';
    public $coltypes = array('name' => array('limit'=>1), 'firstname' => array('limit'=>1), 'surname' => array('limit'=>1), 'email' => array('limit'=>1));

    protected $error;
@@ -96,12 +99,16 @@
     *
     * @param array   List of fields to search in
     * @param string  Search value
     * @param int     Matching mode:
     *                0 - partial (*abc*),
     *                1 - strict (=),
     *                2 - prefix (abc*)
     * @param boolean True if results are requested, False if count only
     * @param boolean True to skip the count query (select only)
     * @param array   List of fields that cannot be empty
     * @return object rcube_result_set List of contact records and 'count' value
     */
    abstract function search($fields, $value, $strict=false, $select=true, $nocount=false, $required=array());
    abstract function search($fields, $value, $mode=0, $select=true, $nocount=false, $required=array());

    /**
     * Count number of available contacts in database
@@ -176,6 +183,21 @@
        $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 != null && ($this->coltypes[$sort_col] || in_array($sort_col, $this->coltypes))) {
            $this->sort_col = $sort_col;
        }
        if ($sort_order != null) {
            $this->sort_order = strtoupper($sort_order) == 'DESC' ? 'DESC' : 'ASC';
        }
    }

    /**
     * Check the given data before saving.
@@ -187,11 +209,14 @@
     */
    public function validate(&$save_data, $autofix = false)
    {
        $rcmail = rcmail::get_instance();

        // check validity of email addresses
        foreach ($this->get_col_values('email', $save_data, true) as $email) {
            if (strlen($email)) {
                if (!check_email(rcube_idn_to_ascii($email))) {
                    $this->set_error(self::ERROR_VALIDATE, rcube_label(array('name' => 'emailformaterror', 'vars' => array('email' => $email))));
                if (!rcube_utils::check_email(rcube_utils::idn_to_ascii($email))) {
                    $error = $rcmail->gettext(array('name' => 'emailformaterror', 'vars' => array('email' => $email)));
                    $this->set_error(self::ERROR_VALIDATE, $error);
                    return false;
                }
            }
@@ -296,6 +321,18 @@
    }

    /**
     * Get group properties such as name and email address(es)
     *
     * @param string Group identifier
     * @return array Group properties as hash array
     */
    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 The group name
@@ -386,8 +423,8 @@
    function get_col_values($col, $data, $flat = false)
    {
        $out = array();
        foreach ($data as $c => $values) {
            if (strpos($c, $col) === 0) {
        foreach ((array)$data as $c => $values) {
            if ($c === $col || strpos($c, $col.':') === 0) {
                if ($flat) {
                    $out = array_merge($out, (array)$values);
                }
@@ -396,6 +433,11 @@
                    $out[$type] = array_merge((array)$out[$type], (array)$values);
                }
            }
        }

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

        return $out;
@@ -408,52 +450,35 @@
     *
     * @param string Input string (UTF-8)
     * @return string Normalized string
     * @deprecated since 0.9-beta
     */
    protected static function normalize_string($str)
    {
        // split by words
        $arr = explode(" ", preg_replace(
            array('/[\s;\+\-\/]+/i', '/(\d)[-.\s]+(\d)/', '/\s\w{1,3}\s/'),
            array(' ', '\\1\\2', ' '),
            $str));

        foreach ($arr as $i => $part) {
            if (utf8_encode(utf8_decode($part)) == $part) {  // is latin-1 ?
                $arr[$i] = utf8_encode(strtr(strtolower(strtr(utf8_decode($part),
                    'ÇçäâàåéêëèïîìÅÉöôòüûùÿøØáíóúñÑÁÂÀãÃÊËÈÍÎÏÓÔõÕÚÛÙýÝ',
                    'ccaaaaeeeeiiiaeooouuuyooaiounnaaaaaeeeiiioooouuuyy')),
                    array('ß' => 'ss', 'ae' => 'a', 'oe' => 'o', 'ue' => 'u')));
            }
            else
                $arr[$i] = mb_strtolower($part);
        }

        return join(" ", $arr);
        return rcube_utils::normalize_string($str);
    }


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

        if (!$fn)
            $fn = join(' ', array_filter(array($contact['prefix'], $contact['firstname'], $contact['middlename'], $contact['surname'], $contact['suffix'])));
        if (!$fn)  // default display name composition according to vcard standard
            $fn = trim(join(' ', array_filter(array($contact['prefix'], $contact['firstname'], $contact['middlename'], $contact['surname'], $contact['suffix']))));

        // use email address part for name
        $email = is_array($contact['email']) ? $contact['email'][0] : $contact['email'];

        if ($email && (empty($fn) || $fn == $email)) {
            // Use full email address on contacts list
            if ($list_mode)
            // return full email
            if ($full_email)
                return $email;

            list($emailname) = explode('@', $email);
@@ -466,5 +491,43 @@
        return $fn;
    }


    /**
     * Compose the name to display in the contacts list for the given contact record.
     * This respects the settings parameter how to list conacts.
     *
     * @param array  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))  // cache this
            $compose_mode = rcmail::get_instance()->config->get('addressbook_name_listing', 0);

        if ($compose_mode == 3)
            $fn = join(' ', array($contact['surname'] . ',', $contact['firstname'], $contact['middlename']));
        else if ($compose_mode == 2)
            $fn = join(' ', array($contact['surname'], $contact['firstname'], $contact['middlename']));
        else if ($compose_mode == 1)
            $fn = join(' ', array($contact['firstname'], $contact['middlename'], $contact['surname']));
        else
            $fn = !empty($contact['name']) ? $contact['name'] : join(' ', array($contact['prefix'], $contact['firstname'], $contact['middlename'], $contact['surname'], $contact['suffix']));

        $fn = trim($fn, ', ');

        // fallback to display name
        if (empty($fn) && $contact['name'])
            $fn = $contact['name'];

        // fallback to email address
        $email = is_array($contact['email']) ? $contact['email'][0] : $contact['email'];
        if (empty($fn) && $email)
            return $email;

        return $fn;
    }

}