Midari Create > webアプリケーション製品 > Wakarana > 関数マニュアル >

class wakarana

Wakaranaの主要機能を提供し、wakarana_data_itemの子孫クラスのインスタンスは全てこのクラスのインスタンスにより生成される。

定数

wakarana::STATUS_DISABLE

「0」。wakarana_users.statusにおける停止中アカウント識別用。

wakarana::STATUS_NORMAL

「1」。wakarana_users.statusにおける有効なアカウント識別用。

wakarana::STATUS_UNAPPROVED

「-1」。wakarana_users.statusにおける未承認アカウント識別用。

wakarana::ORDER_USER_ID

「user_id」。ユーザー一覧の並び替え基準「ユーザーID」。

wakarana::ORDER_USER_NAME

「user_name」。ユーザー一覧の並び替え基準「ユーザー名」。

wakarana::ORDER_USER_CREATED

「user_created」。ユーザー一覧の並び替え基準「ユーザー作成日」。

wakarana::BASE_ROLE

「__base__」。ベースロールの識別名。ベースロールは全てのユーザーが最初から保有しているものとみなされる。

wakarana::ADMIN_ROLE

「__admin__」。特権管理者ロールの識別名。特権管理者ロールには全ての権限が自動的に設定される。

◆ wakarana::BASE32_TABLE

Base32エンコード用の変換対応表。
◆クラス内呼び出し専用。

関数

wakarana::__construct($base_dir=NULL)

wakaranaインスタンスを生成し、データベースに接続する。
設定ファイルの読み込みやデータベースへの接続に失敗した場合は例外が発生する。

$base_dir : wakarana_config.iniのあるフォルダのパス。省略時はwakarana.phpのあるフォルダを使用する。

wakarana::__debugInfo()

wakaranaインスタンスがダンプされたときに実行される。

返り値 : ベースフォルダのパスのみを返す。

wakarana::get_rejection_reason()

wakaranaインスタンスで直前に行われた各種認証・登録処理の結果が拒絶だった場合、その理由を取得する。

返り値 : 認証・登録が拒絶されていた場合はその理由を表す文字列を返し、まだ認証・登録処理が行われていない場合や認証・登録が承認されていた場合、内部エラーにより認証・登録処理が中断されていた場合はNULLを返す。拒絶理由を表す文字列の候補は直前に行われた認証・登録処理により異なる。

◆☆ wakarana::bin_to_int($bin, $start, $length)

バイナリデータをビット単位で切り出し、整数に変換する。
◆クラス内呼び出し専用。
☆staticメソッド。

$bin : バイナリデータを格納した文字列
$start : 切り出し開始ビット
$length : 切り出すビット数

返り値 : 切り出したビット列を2進数として解釈した整数値を返す。

◆☆ wakarana::int_to_bin($int, $digits_start)

整数値型のデータから2進数で8桁分のビットを切り出して1バイトのバイナリに変換する。
◆クラス内呼び出し専用。
☆staticメソッド。

$int : 整数値型データ
$digits_start : データを2進数に変換したときの下から何番目の位から切り出すか。

返り値 : 1バイトの文字列に格納されたバイナリを返す。

◆☆ wakarana::base32_decode($base32_str)

Base32方式でエンコードされた文字列をバイナリにデコードする。
◆クラス内呼び出し専用。
☆staticメソッド。

$base32_str : Base32エンコードされた文字列

返り値 : バイナリデータを格納した文字列を返す。

☆ wakarana::generate_unique_id()

各種IDとして使用できる16文字の一意な文字列を生成する。
☆staticメソッド。

返り値 : 現在時刻と乱数から生成された16文字の文字列を返す。

☆ wakarana::verify_password($hash, $password, $salt=NULL)

パスワードがハッシュ値に対応するものであるか検証する。
☆staticメソッド。

$hash : 比較対象のハッシュ文字列
$password : パスワード
$salt : ソルトとして使用された文字列。ハッシュアルゴリズムとしてArgon2を使用する設定では無視される。

返り値 : パスワードがハッシュ値に対応するものだった場合はTRUE、それ以外の場合はFALSEを返す。

wakarana::get_user($user_id)

ユーザーIDで指定したユーザーのwakarana_userインスタンスを生成する。

$user_id : ユーザーID

返り値 : ユーザーが存在する場合はwakarana_userクラスのインスタンス、存在しない場合はFALSEを返す。

wakarana::count_users()

ユーザーの総数を数える。

返り値 : 登録されているユーザーの総数を返す。

wakarana::get_all_users($start=0, $limit=-1, $order_by=wakarana::ORDER_USER_CREATED, $asc=TRUE)

全ユーザーの一覧を順に返す。

$start : 何番目のユーザーから取得するか(1番目なら「0」)
$limit : 何件まで取得するか。-1が指定された場合は上限を設けない。
$order_by : 並び替え基準。wakarana::ORDER_USER_CREATEDまたはwakarana::ORDER_USER_IDまたはwakarana::ORDER_USER_NAMEのいずれか。
$asc : 昇順で取得する場合はTRUE、降順ならFALSE。

返り値 : 成功した場合は、wakarana_userインスタンスを配列で返す。失敗した場合はFALSEを返す。

wakarana::create_user($user_id, $password, $user_name="", $status=wakarana::STATUS_NORMAL, $used_invite_code=NULL)

新しいユーザーを追加する。
既に存在するユーザーIDを指定した場合はエラーとなる。
招待コードを使用してのユーザー追加にはこの関数でなく wakarana::create_user_with_invite_code を使用すべきである。

$user_id : 追加するユーザーのID。半角英数字及びアンダーバーが使用可能。
$password : 追加するユーザーのパスワード
$user_name : 追加するユーザーのハンドルネーム
$status : wakarana::STATUS_UNAPPROVEDを指定すると未承認ユーザー(ログイン不可)として作成することができる。
$used_invite_code : ユーザー追加時に使用した招待コード。この関数を直接呼び出す際は常にNULLとする。

返り値 : 成功した場合は追加したユーザーのwakarana_userインスタンスを返す。失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_user_id"(ユーザーIDに使用できない文字が含まれる)、"user_already_exists"(ユーザーアカウントが既に存在している)、"weak_password"(弱いパスワードである)

wakarana::create_user_with_invite_code($invite_code, $user_id, $password, $user_name="", $status=wakarana::STATUS_NORMAL)

招待コードを検証し、有効であれば新しいユーザーを追加する。
既に存在するユーザーIDを指定した場合はエラーとなる。

$invite_code : 招待コード文字列。大文字小文字を区別しない。
$user_id : 追加するユーザーのID。半角英数字及びアンダーバーが使用可能。
$password : 追加するユーザーのパスワード
$user_name : 追加するユーザーのハンドルネーム
$status : wakarana::STATUS_UNAPPROVEDを指定すると未承認ユーザー(ログイン不可)として作成することができる。

返り値 : 成功した場合は追加したユーザーのwakarana_userインスタンスを返す。失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_invite_code"(有効な招待コードではない)、"invalid_user_id"(ユーザーIDに使用できない文字が含まれる)、"user_already_exists"(ユーザーアカウントが既に存在している)、"weak_password"(弱いパスワードである)、"currently_locked_out"(ロックアウト中のため招待コードを検証できない)

wakarana::get_role($role_id)

ロールのwakarana_roleインスタンスを生成する。

$role_id : ロールID

返り値 : ロールが存在する場合はロールのwakarana_roleクラスのインスタンス、ロールが存在しない場合はFALSEを返す。

wakarana::get_all_roles()

存在するロールの一覧(ベースロールと特権管理者ロールを含む)を取得する。

返り値 : ロールのwakarana_roleインスタンスをロールIDのアルファベット順に格納した配列を返す。失敗した場合はFALSEを返す。

wakarana::create_role($role_id, $role_name, $role_description="")

ロールを新規作成する。

$role_id : ロールID。半角英数字及びアンダーバーが使用可能。アルファベット大文字は小文字に変換される。
$role_name : ロールの表示名
$role_description : ロールについての説明文

返り値 : 成功した場合は作成したロールのwakarana_roleインスタンスを、失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_role_id"(ロールIDに使用できない文字が含まれる)、"role_already_exists"(ロールが既に存在している)

☆ wakarana::check_resource_id_string($resource_id)

文字列にリソースIDとして使用できない文字が含まれないか否かを検査する。
☆staticメソッド。

$resource_id : 検査する文字列

返り値 : リソースIDとして使用可能な文字列ならTRUEを、それ以外の場合はFALSEを返す。

☆ wakarana::get_parent_resource_id($resource_id)

権限のリソースIDから親権限のリソースIDを切り出す。このとき、実際にその権限が存在するか否かはチェックしない。
☆staticメソッド。

$resource_id : リソースID

返り値 : 親権限のリソースIDが切り出せた場合はその文字列を返し、それ以外の場合はNULLを返す。

wakarana::get_permission($resource_id)

権限のwakarana_permissionインスタンスを生成する。

$resource_id : 権限対象リソースID

返り値 : 権限が存在する場合は権限のwakarana_permissionクラスのインスタンス、権限が存在しない場合はFALSEを返す。

wakarana::get_all_permissions()

存在する権限の一覧を取得する。

返り値 : 権限のwakarana_permissionインスタンスを権限対象リソースIDのアルファベット順に格納した配列を返す。権限が存在しない場合は空配列を返す。失敗した場合はFALSEを返す。

wakarana::create_permission($resource_id, $permission_name, $permission_description="")

権限を新規作成する。権限は権限の表示名ではなく権限対象リソースのIDで識別される。
権限対象リソースIDに「/」が含まれる場合、作成される権限は「/」以下を取り除いたリソースIDの権限(親権限)の子権限となり、親権限に存在する動作を全て持った状態で作成される。
存在しない親権限に子権限を作成することはできない。
権限の作成時、初期動作「any」が自動作成される。

$resource_id : 権限対象リソースID。半角英数字及びアンダーバー、「/」が使用可能(ただし、「/」はリソースIDの先頭や末尾に使用したり、複数文字連続させることはできない)。アルファベット大文字は小文字に変換される。
$permission_name : 権限の表示名
$permission_description : 権限についての説明文

返り値 : 成功した場合は作成した権限のwakarana_permissionインスタンスを、失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_resource_id"(リソースIDに使用できない文字が含まれる)、"resource_already_exists"(権限対象リソースが既に存在している)、"parent_resource_not_exists"(親となる権限対象リソースが存在しない)

wakarana::get_permitted_value($permitted_value_id)

権限値のwakarana_permitted_valueインスタンスを生成する。

$permitted_value_id : 権限値ID

返り値 : 権限値が存在する場合は権限値のwakarana_permitted_valueクラスのインスタンスを、権限値が存在しない場合は空配列を返す。

wakarana::get_all_permitted_values()

存在する権限値の一覧を取得する。

返り値 : 権限値のwakarana_permitted_valueインスタンスを権限値IDのアルファベット順に格納した配列を返す。権限が存在しない場合は空配列を返す。

wakarana::create_permitted_value($permitted_value_id, $permitted_value_name, $permitted_value_description="")

権限値を新規作成する。

$permitted_value_id : 権限値ID。半角英数字及びアンダーバーが使用可能。アルファベット大文字は小文字に変換される。
$ppermitted_value_name : 権限値の表示名
$permitted_value_description : 権限値についての説明文

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_permitted_value_id"(権限値IDに使用できない文字が含まれる)、"permitted_value_already_exists"(権限値が既に存在している)

☆ wakarana::create_token()

トークンとして使用可能な文字列をランダムに生成する。
☆staticメソッド。

返り値 : 英数字と記号(-と_)からなるランダムな文字列を返す。

wakarana::delete_all_tokens()

データベースに存在する各種トークン(セッショントークン、ワンタイムトークン、メールアドレス確認トークン、パスワードリセット用トークン、2段階認証用仮トークン)を全て削除する。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::get_client_ip_address()

プロキシを除外してアクセス中のクライアント端末のIPアドレス文字列を取得し、それがIPアドレスとして正常な文字列であればそれを返す。

返り値 : クライアント端末のIPアドレスをサニタイズして返す。IPアドレスの取得に失敗した場合は「0.0.0.0」を返す。

☆ wakarana::get_client_environment($ua=NULL)

アクセス中のクライアント端末の情報を連想配列で返す。
☆staticメソッド。

$ua : ユーザーエージェント文字列。NULLの場合はクライアント端末のユーザーエージェントを参照する。

返り値 : キー"operating_system"(OS名)と"browser_name"(ブラウザ名)が含まれる連想配列。

wakarana::check_auth_allowed($ip_address, $user_id_or_email_address=NULL)

指定されたIPアドレスとユーザーIDがともにロックアウト中でないことを確認する。

$ip_address : IPアドレス。
$user_id_email_address : ユーザーIDまたはメールアドレス。ユーザーアカウントに依存しない試行の場合はNULL。

返り値 : ロックアウト中でなければTRUE、IPアドレスとユーザーIDまたはメールアドレスのいずれか一方でもロックアウト中の場合はFALSEを返す。

wakarana::add_auth_log($ip_address, $user_id, $authentication_type, $succeeded, $failure_reason=NULL)

認証試行ログを登録する。
各種認証処理を行う関数は内部的にこの関数を実行する。

$ip_address : IPアドレス
$user_id : ユーザーID。ユーザーアカウントに依存しない試行の場合はNULL。
$authentication_type : 試行の種類を表す文字列
$succeeded : 成功したか否か
$failure_reason : 失敗理由文。成功した場合はNULL。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::delete_auth_logs($retention_seconds_or_datetime=-1)

指定した期間より前の認証試行ログを全て削除する。

$retention_seconds_or_datetime : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定した履歴の保持秒数(この値がnullの場合は削除処理を実行しない)が代わりに使用される。YYYY-MM-DD hh:mm:ss形式の日時文字列が指定された場合、当該日時以前の試行ログを削除する。

返り値 : 成功した場合はTRUE、削除処理を実行しなかった場合はNULL、失敗した場合はFALSEを返す。

wakarana::export_auth_logs($file_path, $date_str, $compress=TRUE, $delete_exported_logs=FALSE)

指定した日付の認証試行ログをJSONL形式でファイルに出力する。

$file_path : 出力するファイルのパス。既に存在するファイルを指定した場合は上書きする。
$date_str : YYYY-MM-DD形式の日付文字列
$compress : TRUEが指定された場合、出力ファイルはgzip圧縮される。
$delete_exported_logs : TRUEが指定された場合、ファイルに出力されたログはデータベースから削除される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::delete_expired_ip_address_auth_info()

IPアドレスごとの認証失敗情報のうち、保持期間を過ぎたものを削除する。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::authenticate($user_id, $password, $ip_address=NULL)

ユーザーIDとパスワードを照合するが、トークンの生成と送信は行わない。
内部的に認証試行ログの参照と登録は実施する。

$user_id : ユーザーID
$password : パスワード
$ip_address : IPアドレス。NULLの場合はクライアント端末のIPアドレスを参照する。

返り値 : 認証された場合はユーザーのwakarana_userインスタンス、ユーザーアカウントが停止中の場合はその状態値(wakarana::STATUS_DISABLEまたはwakarana::STATUS_UNAPPROVED)、ユーザーIDが2段階認証の対象ユーザーのものだった場合は仮トークン、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "parameters_not_matched"(ユーザーIDまたはパスワードが誤っている)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::login($user_id, $password)

ユーザーIDとパスワードを照合し、正しければセッショントークンを生成してクライアント端末に送信する。

この関数はHTTPヘッダーの出力を伴うため、この関数より前にHTTPヘッダー以外の何らかの文字が出力されていた場合はエラーとなる。

$user_id : ユーザーID
$password : パスワード

返り値 : ログインが完了した場合はwakarana_userインスタンス、ユーザーアカウントが停止中の場合はその状態値(wakarana::STATUS_DISABLEまたはwakarana::STATUS_UNAPPROVED)、ユーザーIDが2要素認証の対象ユーザーのものだった場合は仮トークン、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "parameters_not_matched"(ユーザーIDまたはパスワード、TOTPコードのいずれかが誤っている)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::authenticate_with_email_address($email_address, $password, $ip_address=NULL)

ユーザーIDの代わりにメールアドレスを使用し、パスワードを照合する。トークンの生成と送信は行わない。
内部的に認証試行ログの参照と登録は実施する。

wakarana_config.iniで同じメールアドレスを複数アカウントに使用できるよう設定している場合、この関数は使用できない。

$email_address : メールアドレス
$password : パスワード
$ip_address : IPアドレス。NULLの場合はクライアント端末のIPアドレスを参照する。

返り値 : 認証された場合はユーザーのwakarana_userインスタンス、ユーザーアカウントが停止中の場合はその状態値(wakarana::STATUS_DISABLEまたはwakarana::STATUS_UNAPPROVED)、メールアドレスが2要素認証の対象ユーザーのものだった場合は仮トークン、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "parameters_not_matched"(メールアドレスまたはパスワードが誤っている)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::login_with_email_address($email_address, $password)

ユーザーIDの代わりにメールアドレスを使用し、パスワードとTOTPコード(2要素認証を使用する場合)を照合、正しければセッショントークンを生成してクライアント端末に送信する。

この関数はHTTPヘッダーの出力を伴うため、この関数より前にHTTPヘッダー以外の何らかの文字が出力されていた場合はエラーとなる。
また、wakarana_config.iniで同じメールアドレスを複数アカウントに使用できるよう設定している場合、この関数は使用できない。

$email_address : メールアドレス
$password : パスワード

返り値 : ログインが完了した場合はwakarana_userインスタンス、ユーザーアカウントが停止中の場合はその状態値(wakarana::STATUS_DISABLEまたはwakarana::STATUS_UNAPPROVED)、メールアドレスが2要素認証の対象ユーザーのものだった場合は仮トークン、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "parameters_not_matched"(メールアドレスまたはパスワードが誤っている)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::delete_session_tokens($expire=-1)

指定した経過時間より前に生成されたセッショントークンを無効化する。

$expire : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定したセッショントークンの有効秒数が代わりに使用される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::search_users_with_email_address($email_address)

メールアドレスからユーザーを逆引きする。

$email_address : 調べるメールアドレス

返り値 : 指定したメールアドレスを登録しているユーザーがいれば、該当ユーザーらのwakarana_userインスタンスの配列、そうでない場合は空配列、エラーの場合は-1を返す。

wakarana::check_email_address($email_address, $check_blacklist=TRUE)

指定した文字列がメールアドレスの規格に沿ったものであり、かつ、そのドメインがメールドメインブラックリストに含まれないドメインであることを確認する。

$email_address : メールアドレス
$check_blacklist : FALSEの場合、メールドメインブラックリストを確認しない。

返り値 : メールアドレスの規格に沿った文字列であり、かつ、メールドメインブラックリストに含まれないドメインの場合はTRUE、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "invalid_email_address"(メールアドレスとして正しくない文字列である)、"blacklisted_email_domain"(メールドメインがブラックリストに登録されている)

wakarana::check_email_sending_interval($email_address)

アクセス者のIPアドレスと指定されたメールアドレスの両方が発行可能間隔以降にメールアドレス確認トークン発行を受けていないことを確認する。

$email_address : メールアドレス

返り値 : アクセス者のIPアドレスと指定されたメールアドレスの両方が発行可能間隔以降にメールアドレス確認トークン発行を受けていなければTRUE、それ以外の場合はFALSEを返す。

wakarana::create_email_address_verification_code($email_address)

アカウント登録前の新規ユーザーに対してメールアドレス確認コードを生成し、データベースに登録する。
この関数によりメールが送信されるわけではない。

$email_address : コードの送信先メールアドレス

返り値 : 成功した場合は8桁のメールアドレス確認コード文字列を、失敗した場合はFALSEを返す。

拒絶理由文字列 : "invalid_email_address"(メールアドレスとして正しくない文字列である)、"blacklisted_email_domain"(メールドメインがブラックリストに登録されている)、"email_address_already_exists"(既に登録されているメールアドレスである)、"currently_locked_out"(前回のメールアドレス確認コード発行時から規定の時間が経過していない)

wakarana::email_address_verify($email_address, $verification_code)

メールアドレスと、新規ユーザー登録用に生成された確認コードとを照合する。使用済みのメールアドレス確認コードは削除される。

$email_address : コードが紐付けられたメールアドレス
$verification_code : メールアドレス確認コード。大文字小文字を区別しない。

返り値 : 認証された場合はTRUEを返し、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "invalid_email_address"(メールアドレスとして正しくない文字列である)、"blacklisted_email_domain"(メールドメインがブラックリストに登録されている)、"email_address_already_exists"(既に登録されているメールアドレスである)、"parameters_not_matched"(メールアドレスまたは確認コードが誤っている)、"currently_locked_out"(ロックアウト中のため確認コードを照合できない)

wakarana::get_email_address_verification_code_expire($email_address, $verification_code)

新規ユーザー登録用に生成されたメールアドレス確認コードの有効期限を取得する。

$email_address : コードが紐付けられたメールアドレス
$verification_code : メールアドレス確認コード。大文字小文字を区別しない。

返り値 : 新規ユーザー登録用の有効な確認コードだった場合はYYYY-MM-DD hh:mm:ss形式の有効期限、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "parameters_not_matched"(有効な確認コードではない)、"currently_locked_out"(ロックアウト中のため確認コードを照合できない)

wakarana::delete_email_address_verification_codes($expire=-1)

指定した経過時間より前に生成されたメールアドレス確認コードを無効化する。

$expire : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定したメールアドレス確認コードの有効秒数が代わりに使用される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::get_invite_code_expire($invite_code)

ユーザー招待コードを検証して残り有効時間を取得する。

$invite_code : 招待コード文字列。大文字小文字を区別しない。

返り値 : 有効な招待コードだった場合はその有効期限までの残り秒数またはNULL(無期限で有効な場合)、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "invalid_invite_code"(有効な招待コードではない)、"currently_locked_out"(ロックアウト中のため確認コードを照合できない)

wakarana::get_invite_code_info($invite_code)

ユーザー招待コードの情報(発行したユーザー、有効か否か、発行日時、有効期限、残り回数、使用回数)を取得する。
エンドユーザーが入力した招待コードの有効性確認にはこの関数でなく wakarana::get_invite_code_expire を使用すべきである。

$invite_code : 招待コード文字列。大文字小文字を区別しない。

返り値 : 有効な招待コードだった場合は、ユーザー招待コードの情報を連想配列("user_id"(発行者のユーザーID)、"is_active"(有効か否か)、"code_created"(YYYY-MM-DD hh:mm:ss形式の発行日時)、"code_expire"(YYYY-MM-DD hh:mm:ss形式の有効期限)、"remaining_number"(残り回数、無限の場合はNULL)、"usage_count"(使用された回数))で返す。それ以外の場合はFALSEを返す。

wakarana::count_invite_codes($is_active=NULL)

招待コードの総数を数える。

$is_active : 招待コードの状態による絞り込み(TRUEなら有効な招待コード、FALSEなら無効となった招待コードのみを数える)

返り値 : 登録されているユーザーの総数を返す。

wakarana::get_invite_codes($is_active=NULL, $start=0, $limit=100, $asc=TRUE)

招待コードの一覧を取得する。

$is_active : 招待コードの状態による絞り込み(TRUEなら有効な招待コード、FALSEなら無効となった招待コードのみを取得する)
$start : 何番目の招待コードから取得するか(1番目なら「0」)
$limit : 何件まで取得するか
$asc : 発行日時の古い順で取得する場合はTRUE、新しい順ならFALSE。

返り値 : 成功した場合は、各招待コードの情報が格納された連想配列("invite_code"(招待コード本体)以外の項目はwakarana::get_invite_code_infoの返り値と同様)を格納した配列(招待コードがない場合は空配列)を返す。失敗した場合はFALSEを返す。

wakarana::create_invite_code($code_expire=NULL, $remaining_number=NULL, $user_id=NULL)

発行ユーザーを指定せずにユーザー招待コードを生成する。
エンドユーザーの操作によるユーザー招待コードの発行時はこの関数でなく wakarana_user::create_invite_code を使用すべきである。

$code_expire : 有効期限。YYYY-MM-DD hh:mm:ss形式の文字列。NULLを指定した場合は無限とみなす。
$remaining_number : コードの使用可能回数。NULLを指定した場合は無限とみなす。
$user_id : コード発行者のユーザーID。この関数を直接呼び出す際は常にNULLとする。

返り値 : 成功した場合は16桁の招待コード文字列、失敗した場合はFALSEを返す。

wakarana::disable_invite_code($invite_code=NULL)

ユーザー招待コードを無効化する。
エンドユーザーの操作により当該ユーザー自身が発行した招待コードを無効化する場合は、この関数でなく wakarana_user::disable_invite_code を使用すべきである。

$invite_code : 招待コード文字列。NULLを指定した場合は全ての招待コードを無効化する。

返り値 : 成功した場合はTRUEを返し、指定された招待コードが有効なものでなかった場合や失敗した場合はFALSEを返す。

wakarana::disable_expired_invite_codes()

有効期限切れのユーザー招待コードを全て無効化する。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::delete_disabled_invite_codes($keep_used_invite_codes=TRUE)

有効でないユーザー招待コードを全て削除する。

$keep_used_invite_codes : TRUEを指定した場合、使用回数が0でない招待コードは削除対象外となる。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::get_invited_users($invite_code)

招待コードを使用して登録されたユーザーの一覧を取得する。

$invite_code : 招待コード文字列。大文字小文字を区別しない。

返り値 : 成功した場合はwakarana_userインスタンスを登録日時(招待コード使用日時と同義)の古い順に配列で返す。失敗した場合はFALSEを返す。

wakarana::reset_password($token, $new_password)

パスワードリセット用トークンに紐付けられたアカウントのパスワードを再設定する。使用済みトークンは自動的に削除される。

$token : パスワードリセット用トークン
$new_password : 新しいパスワード

返り値 : 成功した場合はトークンに紐付けられたユーザーのwakarana_userクラスのインスタンスを返し、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効なトークンではない)、"weak_password"(弱いパスワードである)

wakarana::get_password_reset_token_expire($token)

パスワードリセット用トークンの有効期限を取得する。

$token : パスワードリセット用トークン

返り値 : 有効な確認コードだった場合はYYYY-MM-DD hh:mm:ss形式の有効期限、それ以外の場合はFALSEを返す。

wakarana::delete_password_reset_tokens($expire=-1)

指定した経過時間より前に生成されたパスワードリセット用トークンを無効化する。

$expire : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定したパスワードリセット用トークンの有効秒数が代わりに使用される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::search_users_with_custom_field($custom_field_name, $custom_field_value)

カスタムフィールドの値からユーザーを逆引きする。

$custom_field_name : カスタムフィールド名
$custom_field_value : カスタムフィールド値

返り値 : 指定した値と一致するカスタムフィールドの値を持つユーザーがいれば、該当ユーザーらのwakarana_userインスタンスの配列、そうでない場合は空配列、エラーの場合は-1を返す。

wakarana::delete_all_users_values($custom_field_name)

全ユーザーを対象に、指定したカスタムフィールドの全データを削除する。

$custom_field_name : カスタムフィールド名

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::get_2sv_token_holder($tmp_token)

2段階認証用仮トークンの割り当て対象ユーザーを照会する。

tmp_token : wakarana::authenticate等により発行される仮トークン

返り値 : 有効なユーザーに割り当てられた正しい仮トークンだった場合は当該ユーザーのwakarana_userインスタンスを、それ以外の場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効な仮トークンではない)、"unavailable_user"(ユーザーアカウントが停止中である)

wakarana::delete_2sv_tokens($expire=-1)

指定した経過時間より前に生成された2段階認証用仮トークンを無効化する。

$expire : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定した2段階認証用仮トークンの有効秒数が代わりに使用される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::totp_authenticate($tmp_token, $totp_pin, $ip_address=NULL)

ユーザーIDとパスワードが照合済みのユーザーに対してTOTPによる第2段階の認証を行う。

tmp_token : wakarana::authenticate等により発行される仮トークン
$totp_pin : 6桁のTOTPコード
$ip_address : IPアドレス。NULLの場合はクライアント端末のIPアドレスを参照する。

返り値 : 認証された場合はユーザーのwakarana_userインスタンス、そうでない場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効な仮トークンではない)、"pin_not_matched"(TOTPコードが一致しない)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::totp_login($tmp_token, $totp_pin)

ユーザーIDとパスワードが照合済みのユーザーに対してTOTPによる第2段階の認証を行い、正しければセッショントークンを生成してクライアント端末に送信する。

この関数はHTTPヘッダーの出力を伴うため、この関数より前にHTTPヘッダー以外の何らかの文字が出力されていた場合はエラーとなる。

tmp_token : wakarana::login等により発行される仮トークン
$totp_pin : 6桁のTOTPコード

返り値 : ログインが完了した場合はユーザーのwakarana_userインスタンス、そうでない場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効な仮トークンではない)、"pin_not_matched"(TOTPコードが一致しない)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::authenticate_with_recovery_code($tmp_token, $recovery_code, $ip_address=NULL)

ユーザーIDとパスワードが照合済みのユーザーに対してTOTPの代わりにリカバリコードを使用して第2段階の認証を行う。

tmp_token : wakarana::authenticate等により発行される仮トークン
$recovery_code : リカバリコード
$ip_address : IPアドレス。NULLの場合はクライアント端末のIPアドレスを参照する。

返り値 : 認証された場合はユーザーのwakarana_userインスタンス、そうでない場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効な仮トークンではない)、"code_not_matched"(リカバリコードが一致しない)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::login_with_recovery_code($tmp_token, $recovery_code)

ユーザーIDとパスワードが照合済みのユーザーに対してTOTPの代わりにリカバリコードを使用して第2段階の認証を行い、正しければセッショントークンを生成してクライアント端末に送信する。

この関数はHTTPヘッダーの出力を伴うため、この関数より前にHTTPヘッダー以外の何らかの文字が出力されていた場合はエラーとなる。

tmp_token : wakarana::login等により発行される仮トークン
$recovery_code : リカバリコード

返り値 : ログインが完了した場合はユーザーのwakarana_userインスタンス、そうでない場合はFALSEを返す。

拒絶理由文字列 : "invalid_token"(有効な仮トークンではない)、"code_not_matched"(リカバリコードが一致しない)、"unavailable_user"(ユーザーアカウントが停止中である)、"currently_locked_out"(ロックアウト中のためログインを試行できない)

wakarana::check($token=NULL, $update_last_access=TRUE, $ip_address=NULL)

クライアント端末のcookieを参照し、正しくログインしているか否かを照合する。

$token : 文字列を指定した場合、クライアント端末のcookie情報に関係なくその文字列をセッショントークンとみなして照合処理を行う。
$update_last_access : FALSEの場合、最終アクセス日時の更新を行わない。
$ip_address : IPアドレス。NULLの場合はクライアント端末のIPアドレスを参照する。

返り値 : 有効なセッショントークンでログインしている場合はそのトークンに対応するユーザーのwakarana_userインスタンス、それ以外の場合はFALSEを返す。

wakarana::get_session_info($session_id_or_token=NULL)

指定したセッションIDまたはセッショントークンに対応するセッションの情報を取得する。

$session_id_or_token : 16文字のセッションIDまたは43文字のセッショントークン。NULLを指定した場合はクライアント端末のcookieにセットされているセッショントークンを参照する。

返り値 : セッションIDまたはセッショントークンが存在する場合は、セッション情報が格納された連想配列("session_id"(セッションID)、"user_id"(ユーザーID)、"token_created"(セッショントークンの生成日時)、"ip_address"(最終アクセス時のクライアント端末のIPアドレス)、"operating_system"(ログイン時のクライアント端末のOS名)、"browser_name"(ログイン時のクライアント端末のブラウザ名)、"last_access"(当該セッショントークンでの最終アクセス日時))を返す。それ以外の場合はFALSEを返す。

wakarana::delete_session_token($session_id_or_token)

指定したセッショントークンを削除し、セッションを終了する。

$session_id_or_token : 16文字のセッションIDまたは43文字のセッショントークン

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::logout()

接続中のクライアント端末が持つセッショントークンをクライアント端末とデータベースの双方から削除し、ログアウト状態にする。

この関数はHTTPヘッダーの出力を伴うため、この関数より前にのHTMLやHTTPヘッダー以外の何らかの文字が出力されていた場合はエラーとなる。

返り値 : 成功した場合はTRUE、既にログアウトしている場合はNULL、失敗した場合はFALSEを返す。

wakarana::delete_one_time_tokens($expire=-1)

指定した経過時間より前に生成されたワンタイムトークンを無効化する。

$expire : 経過時間の秒数。-1を指定した場合はwakarana_config.iniで指定したトークンの有効秒数が代わりに使用される。

返り値 : 成功した場合はTRUE、失敗した場合はFALSEを返す。

wakarana::totp_compare($totp_key, $totp_pin)

TOTPの規格に基づいて現在時刻のタイムスタンプで生成鍵とワンタイムコードを照合する。

$totp_key : TOTP生成鍵
$totp_pin : 6桁のTOTPコード

返り値 : 生成鍵に対して正しいTOTPコードだった場合はTRUEを、それ以外の場合はFALSEを返す。

☆ wakarana::create_random_code($code_length=16)

TOTP生成鍵として使用できるランダムなBASE32文字列を作成する。
☆staticメソッド。

$code_length : 作成する文字列の桁数。8の倍数でなければならない。

返り値 : 指定された桁数のランダムなBASE32文字列を返す。

◆☆ wakarana::get_totp_pin($key_base32, $past_30s=0)

TOTP生成鍵と現在時刻からワンタイムコードを生成する。
◆クラス内呼び出し専用。
☆staticメソッド。

$key_base32 : TOTP生成鍵
$past_30s : 負でない整数値。この値に30をかけた秒数過去のタイムスタンプを現在時刻とみなす。

返り値 : ワンタイムコードを返す。