понедельник, 6 декабря 2010 г.

DX Auth: Руководство пользователя. Справочник по функциям класса

Третья часть перевода документации библиотеки авторизации DX Auth для фреймворка CodeIgniter.


Далее приведён список функций которые вы можете использовать в работе с библиотекой DX Auth.

  • Основные функции
  • reCAPTCHA функции
  • Устаревшие функции

Основные функции

login($login, $password, $remember = TRUE)

Вход пользователя. Если вход завершился успешно, возвращается TRUE, иначе FALSE.

$login имя пользователя или e-mail адрес, или оба зависит от настроек в файле конфигурации.

$password пароль пользователя.

$remember помнить пользователя в следующий раз когда он зайдёт на сайт (опция 'запомнить меня')

Если функция вернула FALSE, вы можете использовать функцию get_auth_error() для получения строки ошибки.


logout()

Выход пользователя.


register($username, $password, $email)

Регистрация нового пользователя. Если регистрация прошла удачно, возвращается запись о новом пользователе, иначе FALSE.

Возвращаемое значение:
array(
     'username',
     'password',
     'email',
   'last_ip');

Если DX_email_activation = TRUE, то происходит активация пользовательского аккаунта через e-mail.

Если DX-email_activation = FALSE и DX_email_account_detail = TRUE, то пользователю высылается e-mail с данными о профиле.

Эта функция автоматически устанавливает у нового пользователя role_id = 1, та что вы должны убедится, что запись в таблице role имеющая id =1, это запись 'обычный пользователь' или что-то подобное.

forgot_password($login)

Отсылает на e-mail сообщение с ключём для сброса пароля. Если сообщение отсылается успешно возвращает TRUE, иначе FALSE.

$login имя пользователя или e-mail

В связи с тем, что пароль зашифрован односторонним шифрованием, то выслать пароль становится невозможно. Поэтому нужно его сбрасывать.
Если функция вернула FALSE, вы можете использовать функцию get_auth_error() для получения строки ошибки.

reset_password($username, $key = '')

Сбрасывает пароль по имени пользователя и ключу. Обычно используется в сочетании с forgot_password(). Если сброс прошёл удачно, возвращается TRUE, иначе FALSE.


activate($username, $key = '')

Активация пользователя по имени пользователя и ключу. Используется для активации аккаунта, если DX_email_verification = TRUE в файле конфигурации.


change_password($old_password, $new_password)

Изменяет пароль текущего пользователя. Убедитесь, что пользователь вошёл прежде чем вызывать эту функцию. Если смена пароля прошла удачно возвращает TRUE, иначе FALSE.

Если функция вернула FALSE, вы можете использовать функцию get_auth_error() для получения строки ошибки.

cancel_account($password)

Удаляет текущего пользователя из базы данных. Убедитесь, что пользователь вошёл прежде чем вызывать эту функцию. Если удаление прошло удачно возвращается TRUE, иначе FALSE.

Если функция вернула FALSE, вы можете использовать функцию get_auth_error() для получения строки ошибки.

get_user_id()

Возвращает id пользователя, если пользователь вошёл.


get_username()

Возвращает имя пользователя, если пользователь вошёл.


get_role_id()

Возвращает id роли пользователя, если пользователь вошёл.


get_role_name()

Возвращает имя роли, если пользователь вошёл.


is_admin()

Проверяет, является ли администратором вошедший пользователь.

Если имя роли пользователя == 'admin' (без учёта регистра), функция возвращает 'TRUE'.

is_role($roles = array(), $use_role_name = TRUE, $check_parent = TRUE)

Проверяет имеет ли пользователь привилегии ролей $roles.

Если $use_role_name = TRUE, то используются имена ролей ('Администратор','Редактор' и т.д.), иначе используются id ролей (0, 1, 2 и т.д.)

Если $check_parent = TRUE, значит если роль не найдена в роли пользователя, то будет проверятся роль предок роли пользователя.

Вы можете использовать массив или строку в качестве параметра $roles.

Например:

if ($this->dx_auth->is_role('admin'))  
{  
    // Выполнить действие
}  
 
if ($this->dx_auth->is_role(array('admin', 'moderator'))  
{  
    // Выполнить действие
}  
 
// Используем идентификатор роли как параметр $roles
if ($this->dx_auth->is_role('1', FALSE))  
{  
    // Выполнить действие
}  
 
if ($this->dx_auth->is_role(array('1', '2'), FALSE))  
{  
    // Выполнить действие
} 

is_logged_in()

Проверят, вошёл ли пользователь.


is_banned()

Проверяет, заблокирован ли пользователь.

Вы должны использовать эту функцию только после использования login(). Если login() возвращает FALSE, вы можете проверить заблокирован пользователь или не использовать её вообще.

is_username_available($username)

Проверят, доступно ли это имя пользователя для регистрации. Может использоваться в качестве коллбэк-функции


is_email_available($email)

Проверяет, доступен ли этот e-mail для регистрации. Может использоваться в качестве коллбэк-функции


get_auth_error()

Возвращает сообщения об ошибки когда функции login(), forgot_password(), change_password(), cancel_account() возвращают FALSE.


is_max_login_attempts_exceeded()

Проверят достигло ли количество попыток входа максимального количества, устанавливается в файле конфигурации.

Увеличение счётчика попыток входа основывается на попытках входа с одного IP-адреса


check_uri_permissions($allow = TRUE)

Проверяет, есть ли доступ к текущему URI у пользователя, на основе его роли или предка его роли.

Подробнее о действиях внутри функции:

Во первых, происходит проверка, вошёл ли пользователь. Если нет, то он будет перенаправлен на страницу входа.

Но, если пользователь вошёл, то будет проверятся, является ли он администратором.

Если пользователь администратор, то ему разрешён доступ к этому URI.

Но, если пользователь не администратор, то функция будет проверять есть у роли или родительской роли доступ к текущему URI, на основе permissions таблицы прав доступа к URI.

Если пользователь не имеет доступа, то он будет перенаправлен на страницу с сообщение об отсутствии прав доступа.

Вы можете использовать check_uri_permission() в конструкторе контроллера, для защиты доступа ко всему контроллеру.

class Home extends Controller   
{  
    function Home()  
    {  
        parent::Controller();  
 
        $this->dx_auth->check_uri_permissions();  
    }  
} 

Или использовать внутри функции

function hello_world()  
{  
    $this->dx_auth->check_uri_permissions();  
      
    // Выполнить действие 
}

Примеры:

Есть пользователь с role_id = 1 (обычный пользователь).

В таблице прав доступа к URI, указано, что роли role_id = 1 имеют доступ к URI '/test/'.

Пользователь хочет получить доступ к URI '/test/hi/'.

Код контроллера, вроде этого:

class Test extends Controller   
{  
    function Test()  
    {  
        parent::Controller();  
          
        // Secure controller  
        $this->dx_auth->check_uri_permissions();  
    }  
      
    function hi()  
    {  
        echo 'Hi';  
    }  
      
    function hello()  
    {  
        echo 'Hello';  
    }  
} 

Пользователь получит доступ к '/test/hi/' и увидит сообщение 'Hi'.

Потому что, если установлен доступ к '/test/', это означает, что есть доступ к классу Test и всем его функциям.

Если вы хотите дать доступ только к одной функции, вы должны указать '/класс/функция/', в таблице прав доступа к URI.

Например, в предыдущем примере если вы измените доступ роли role_id =1 к URI на '/test/hi/', то пользователь будет иметь доступ к URI '/test/hi/' и не будет иметь доступ к URI '/test/hello/'.

Вы, так же можете установить URI доступ на '/', что бы роль имела доступ ко всем URI.

Можно изменить принцип доступа на противоположный, установив $allow = TRUE при при вызове check_uri_permissions().

Тогда вместо разрешения доступа по указанным правилам, функция будет их запрещать.

Чтобы установить разрешение для URI вы можете использовать функцию установки разрешений из модели, ила написать свою. Смотрите пример, как установить разрешения.
Для пользователей CL Auth: обратите внимание, что разрешения URI нужно указывать '/class/function/', а не '/class/function'.

Наследование

Если есть доступ у родительской роли, значит роль пользователя имеет такой же доступ. Для описания этого давайте рассмотрим следующий пример:

User
{
     '/home/'
     '/help/'
}

Moderator: User
{
     '/moderator/'
}

Super_Moderator: Moderator
{
     '/super/'
}

Big_Moderator: Moderator
{
     '/big/'
}

Это означает, роль Super_Moderator имеет доступ ролей Moderator и User к URI, но у неё нет доступа роли Big_Moderator к URI.

Для использования этой функции вы должны указать у каждой роли предка в поле parent_id таблицы roles.

Таблица ролей для предыдущего примера

id parent_id name
----------------------
1     0      User
2     0      Admin
3     1      Moderator
4     3      Super_Moderator
5     3      Big_Moderator

Примечание. Эта функция является опциональной, её использование не обязательно. Вы можете её не использовать если вам удобно использовать для проверки доступа такие функции, как is_admin(), is_role(), is_logged_in() и т.д.


get_permission_value($key, $check_parent = TRUE)

Возвращает значение разрешения по указанному ключу. Вызывайте эту функцию, только когда пользователь вошёл.

$key массив ключей разрешений (Примечание: ключи доступа хранятся в таблице в виде массива)

Если $check_parent = TRUE и доступа нет у роли пользователя, то проверяются права родительских ролей.

Возвращает значение, если роль найдена, иначе возвращает NULL.

Для задания разрешения вы можете использовать функцию из модели или написать свою собственную. Смотрите в примерах, как устанавливать разрешения.
Примечание. Эта функция является опциональной, её использование не обязательно. Вы можете её не использовать если вам удобно использовать для проверки доступа такие функции, как is_admin(), is_role(), is_logged_in() и т.д.

get_permissions_value($key, $array_key = 'default')

Возвращает значение разрешений по указанному ключу. Вызывайте эту функцию, только когда пользователь вошёл.

$key массив ключей разрешений (Примечание: ключи доступа хранятся в таблице в виде массива)

$array_key = 'default'. Возвращает упорядоченный массив используя 0, 1, 2 как ключи массива.

$array_key = 'role_id'. Возвращает упорядоченный массив используя role_id как ключи массива.

$array_key = 'role_name'. Возвращает упорядоченный массив используя role_name как ключи массива.

Возвращает значение, если роль найдена, иначе возвращает NULL.

Для задания разрешения вы можете использовать функцию из модели или написать свою собственную. Смотрите в примерах, как устанавливать разрешения.
Примечание. Эта функция является опциональной, её использование не обязательно. Вы можете её не использовать если вам удобно использовать для проверки доступа такие функции, как is_admin(), is_role(), is_logged_in() и т.д.

deny_access($uri = 'deny')

Перенаправляет пользователя на страницу в зависимости от значение $uri. По умолчанию $uri = 'deny'

$uri = 'deny' перенаправляет пользователя на 'DX_deny_uri' указанный в файле конфигурации.

$uri = 'login' перенаправляет пользователя на 'DX_login_uri' указанный в файле конфигурации.

$uri = 'banned' перенаправляет пользователя на 'DX_banned_uri' указанный в файле конфигурации.


captcha()

Создаёт captchа, которая будет использоваться в форме проверки.


get_captcha_image()

Возвращает HTML для изображения. Используйте эту функцию в файле отображения.


is_captcha_expired()

Проверяет устарела используемая captcha или нет.


is_captcha_match($code)

Проверяет совпадает $code с созданной captcha или нет.


reCAPTCHA функции

Далее приведён список функций reCaPTCHA. Из-за ограничений наложенных reCAPTCHA API (все функции должны иметь фиксированные имена) функции reCAPTCHA вынесены в хелпер recaptcha_helper.php.

Для использования функций reCAPTCHA вы должны установить DX_recaptcha_public_key и DX_recaptch_private_key в dx_auth_config файле. Для получения ключей зарегистрируйтесь на веб-сайте reCAPTCHA.


get_recaptcha_reload_link($text = 'Get another CAPTCHA')

Получить ссылку для обновления reCAPTCHA, с $text в качестве текста ссылки. Использовать функцию в файле отображения.


get_recaptcha_switch_image_audio_link($switch_image_text = 'Get an image CAPTCHA', $switch_audio_text = 'Get an audio CAPTCHA')

Получить ссылку замены изображения или аудио reCAPTCHA. Используйте эту функцию в файле отображения.


get_recaptcha_label($image_text = 'Enter the words above', $audio_text = 'Enter the numbers you hear')

Получить текст метки над полем ввода слов captcha. Используйте эту функцию в фале отображения.


get_recaptcha_input()

Получить поле ввода captcha. Используйте эту функцию в файле отображения.

Вы должны обязательно использовать эту функцию, поскольку reCAPTCHA JavaScript будет пытаться найти это поле, иначе изображение reCAPTCHA не будет отображаться.

get_recaptcha_image()

Получить изображение reCAPTCHA. Используйте эту функцию в файле отображения.


get_recaptcha_html()

Получить reCAPTCHA JavaScript и html код для отключенного JavaScript. Используйте эту функцию в файле отображения.

Это основная часть reCAPTCHA функции.
Вызывайте эту функцию после того как вы вызвали некоторые или все функции get_recaptcha_xxx. Суть этой функции в том, что она должна вызываться последней.

is_recaptcha_match()

Проверяет совпадает ли текст введённый пользователем в поле, полученное get_recaptcha_input() и текст reCAPTCHA.


Устаревшие функции

check_role_uri()

Эта функция является устаревшая в версии 1.0.2 и выше используйте вместо неё check_uri_permissions(), для получения того же результата с новой таблицей разрешений.

Похожие по тематике посты:

2 комментария:

La2ha комментирует...

Благодарю за перевод)))

Анонимный комментирует...

Спасибо. Перевод пригодился.