Этот документ поясняет как использовать phpBB auth/acl API.

Auth API


1. Введение

Что это?

Класс auth содержит методы связанные с проверкой на право получения пользователем доступа к различным функциям конференции, таким как отправка сообщений, просмотр, ответ, вход (выход) и т.д. Если вам необходимо проверить, может ли пользователь выполнить действие или совершить вход/выход, то вы обязаны использовать этот класс.

Инициализация

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

$auth = new auth();
	

Сразу после создания класса вы можете использовать любые методы, которые он в себе содержит. Имейте ввиду, что если вы желаете использовать auth_admin, то вы должны произвести определение метода отдельно, но все в той же манере.


2. Методы

Ниже перечисленны методы, которые вы можете использовать.

2.i. acl

Метод acl - это рутинная инициализация для всех функций acl. Если вы хотите вызвать любой acl-метод, то должны сначала вызвать его. Этот метод имеет только один, но обязательный параметр - ассоциированный массив информации о пользователе, содержащейся в БД. Этот массив должен содержать по крайней мере следующую информацию: user_id, user_permissions и user_type. Метод нужно использовать следующим образом:

$auth->acl(userdata);
	

Где userdata - массив, содержащий вышеупомянутые данные.

2.ii. acl_get

Это первичный метод для определения может или не может пользователь произвести данное действие глобально или для отдельного форума. Этот метод используется следующим образом:

$result = $auth->acl_get(option[, forum]);
	

Где option - строка представляющая список необходимых действий, например 'f_list', 'm_edit', 'a_adduser' и т.д. Добавляя ! перед действием (например, '!f_list') возвращенный результат будет инвертирован для этого действия. Дополнительный параметр этого метода forum - это целое число выражающее forum_id.

Метод возвращает положительное целое число, когда пользователю разрешено действие, и ноль, когда запрещено. Или наоборот, если перед действием был добавлен восклицательный знак.

Если вы определите возможность действия для форума, но будет так же существовать и глобальное определение возможности действия, то этот метод вернет положительное целое число в случае, когда возможность действия существует, не важно для форума или глобально. Например, возможность действия m_approve может быть установлена как для отдельного форума, так и глобально. Если пользователь будет иметь глобальную возможность действия m_approve, то он автоматически получит возможность этого действия в каждом форуме.

Существуют специальные параметры или флаги, которые используются как префиксы для других параметров, например 'f_' или 'm_'. Эти флаги позволяют объединять несколько параметров с общим префиксом и в результате возвращать положительное целое число, если хотя бы один (или несколько) из этих параметров возвращает положительное целое число. Локальные установки will result in the flag будут установлены только локально (таким образом это требует возврата id форума). Если пользователь имеет одну (или несколько) глобальных возможностей действия, а все возможности действия объединены префиксом, то метод acl_get вернет положительное целое число вне зависимости от заданного форума.

2.iii. acl_gets

Этот метод функционально очень похож на acl_get тем, что возвращает информацию о возмоджности выполнения действия пользователем. Различие состоит в возможности проверить несколько различных параметров за один шаг. Это может быть полезно, что бы проверить является ли пользователь модератором или администратором за один вызов. Вместо того, что бы дважды определять и проверять, используя acl_get.

Метод нужно использовать следующим способом:

$result = $auth->acl_gets(option1[, option2, ..., optionN, forum]);
	

Как и в acl_get в качестве option используется строка, представляющая список необходимых для проверки прав доступа. forum - опять же, целое число выражающее forum_id.

Метод возвращает положительное целое число, если acl_get for one of the options evaluates to a positive integer (combines permissions with OR).

2.iv. acl_getf

Этот метод используется, что бы определить в каких форумах пользователю разрешено или запрещено выполнять какое-либо действие. Этот метод используется следующим образом:

$result = $auth->acl_getf(option[, clean]);
	

Точно так же как в методе acl_get в качестве option используется строка, представляющая список необходимых для проверки прав доступа (возможно использование ! для отрицания). Второй параметр логический. If it is set to false this method returns all forums with either zero or a positive integer. If it is set to true only those forums with a positive integer as the result will be returned.

Метод возвращает ассоциативный масив следующего вида:

array(forum_id1 => array(option => integer), forum_id2 => ...)
	

Where option is the option passed to the method and integer is either zero or a positive integer and the same acl_get(option, forum_id) would return.

2.v. acl_getf_global

Этот метод используется, чтобы определить имеет ли пользователь возможность действия хотя бы в одном форуме или глобально. Этот метод похож на проверку acl_getf(option, true) возвращающую один или несколько значений форумов, но действует более быстро. Его следует использовать так:

$result = acl_getf_global(option)
	

Как и в предыдущем методе option - это строка определяющая права, которые необходимо проверить.

Метод возвращает ноль или положительное целое число.

2.vi. acl_cache

Можно сказать, что этот метод является приватным. Он не должен вызываться. It handles the generation of the user_permissions data, используя основную информацию об авторизации пользователя и группы. В случае необходимости этот метод вызывается автоматически через acl.


3. Функции, используемые для администраторов

A number of additional methods are available related to auth. These handle more basic functions such as adding user and group permissions, new options and clearing the user cache. These methods are contained within a separate class, auth_admin. Они могут быть найдены в файле includes/acp/auth.php.

To use any methods this class contains it first needs to be instantiated separately from auth. This is achieved in the same way as auth:

$auth_admin = new auth_admin();
	

Этот метод дает вам доступ и к этому специальному методу, и к перечисленным выше методам auth.


4. Авторские права и отказ от обязательств

Это приложение с открытым исходным кодом выпущено под лицензией GPL. Смотрите исходный код и каталог «docs» для получения дополнительной информации. Этот пакет и его содержимое является собственностью (c) 2000, 2002, 2005, 2007 phpBB Group. Все права защищены.
Перевод этого документа на русский язык выполнил VVVas.