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

class wakarana_user

wakarana_data_itemの派生クラス。ユーザーの情報を読み書きするために使用する。1インスタンスごとに1ユーザーの情報が割り当てられる。

wakarana_user::__construct($wakarana, $user_info)

コンストラクタ。wakarana::get_user実行時に呼び出されるものであり、直接インスタンス化するべきではない。

$wakarana : 呼び出し元のwakaranaインスタンス
$user_info : ユーザー情報("user_id"(ユーザーID)、"user_name"(ユーザー名)、"password"(ハッシュ化されたパスワード)、"user_created"(アカウント作成日時)、"last_updated"(アカウント情報更新日時)、"last_access"(最終アクセス日時)、"status"(アカウントが使用可能か停止されているか)、"totp_key"(TOTPワンタイムパスワード生成キー))を格納した連想配列

☆ wakarana_user::free($wakarana_user)

wakarana_userインスタンスをメモリから解放する。
wakarana_userインスタンスはこの関数以外の方法(unsetや変数の上書き)では解放されない。
☆staticメソッド。

$wakarana_user : メモリから解放するwakarana_userインスタンス

wakarana_user::get_rejection_reason()

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

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

wakarana_user::get_id()

ユーザーのIDを取得する。

返り値 : ユーザーIDを返す。

wakarana_user::get_name()

ユーザー名を取得する。

返り値 : ユーザー名が登録されていればユーザー名を、なければNULLを返す。

wakarana_user::check_password($password)

入力したパスワードとそのユーザーのパスワードが一致するかどうかを確認する。
この関数は2段階認証を無視するため、ログイン認証に使用するべきではない。

$password : パスワード

返り値 : 正しいパスワードだった場合はTRUE、それ以外の場合はFALSEを返す。

wakarana_user::get_primary_email_address()

ユーザーのメインメールアドレスを取得する。

返り値 : メールアドレスが登録されていればメインメールアドレスを、なければNULLを返す。失敗した場合はFALSEを返す。

wakarana_user::get_email_addresses()

ユーザーのメールアドレス一覧を配列で取得する。

返り値 : メールアドレスが登録されていればメールアドレスがアルファベット順に格納された配列を、なければ空配列を返す。失敗した場合はFALSEを返す。

wakarana_user::get_created()

ユーザーの登録日時を取得する。

返り値 : YYYY-MM-DD hh:mm:ss形式の文字列。

wakarana_user::get_last_updated()

ユーザー情報の更新日時を取得する。

返り値 : YYYY-MM-DD hh:mm:ss形式の文字列。

wakarana_user::get_last_access()

ユーザーの最終アクセス日時を取得する。

返り値 : YYYY-MM-DD hh:mm:ss形式の文字列。

wakarana_user::get_status()

ユーザーの状態(アカウントが有効か停止されているか、等)を取得する。

返り値 : WAKARANA_STATUS_NORMALまたはWAKARANA_STATUS_DISABLEまたはWAKARANA_STATUS_UNAPPROVED。

wakarana_user::get_totp_enabled()

ユーザーの2要素認証が有効になっているかを取得する。

返り値 : 2要素認証が有効ならばTRUE、そうでない場合はFALSEを返す。

wakarana_user::get_value($custom_field_name)

ユーザーの指定したカスタムフィールドの単一の値を取得する。

$custom_field_name : カスタムフィールド名。2個以上の値の登録が可能なカスタムフィールドは指定できない。

返り値 : 成功した場合はカスタムフィールドの値、失敗した場合はFALSEを返す。値が存在しない場合はNULLとみなす。

wakarana_user::get_values($custom_field_name)

ユーザーの指定したカスタムフィールドの値を配列で取得する。

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

返り値 : カスタムフィールドの値を配列で返す。値が存在しない場合は空配列を、失敗した場合はFALSEを返す。

wakarana_user::set_password($password)

ユーザーのパスワードを変更する。

$password : パスワード

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

拒絶理由文字列 : "weak_password"(弱いパスワードである)

wakarana_user::set_name($user_name)

ユーザー名を変更する。

$user_name : ユーザー名

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

wakarana_user::add_email_address($email_address)

ユーザーのメールアドレスを追加する。
ユーザーに対して最初に登録されたメールアドレスは自動的にメインメールアドレスとなる。

$email_address : 新しいメールアドレス

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

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

wakarana_user::set_primary_email_address($email_address)

登録済みのメールアドレスをユーザーのメインメールアドレスとして設定する。
新たなメインメールアドレスが設定されることにより、元のメインメールアドレスはメインメールアドレスではなくなる。

$email_address : 登録済みのメールアドレス

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

wakarana_user::remove_email_address($email_address)

ユーザーのメールアドレスを削除する。
この関数ではプライマリメールアドレスは削除できない。

$email_address : 削除するメールアドレス

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

wakarana_user::remove_all_email_addresses()

プライマリメールアドレスを含むユーザーのメールアドレスを全て削除する。

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

wakarana_user::set_status($status)

ユーザーアカウントの状態(有効、停止、等)を切り替える。
有効以外の状態を指定した場合、そのユーザーは自動的にログアウト状態となる。

$status : WAKARANA_STATUS_NORMAL(有効)またはWAKARANA_STATUS_DISABLE(無効)またはWAKARANA_STATUS_UNAPPROVED(未承認)。

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

wakarana_user::enable_2_factor_auth($totp_key=NULL)

ユーザーのログイン時に2要素認証を要求するように設定する。

$totp_key : TOTP生成鍵。省略したときは自動で生成される。

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

wakarana_user::disable_2_factor_auth()

ユーザーのログイン時に2要素認証を要求しないように設定する。

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

wakarana_user::set_value($custom_field_name, $custom_field_value)

ユーザーの指定したカスタムフィールドの単一の値を設定する。

$custom_field_name : カスタムフィールド名。2個以上の値の登録が可能なカスタムフィールドは指定できない。
$custom_field_value : 値として保存する文字列または数値

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

wakarana_user::add_value($custom_field_name, $custom_field_value, $value_number=-1)

ユーザーの指定したカスタムフィールドに値を追加する。
同一のユーザーに対して同じ値を複数追加することはできない。

$custom_field_name : カスタムフィールド名
$custom_field_value : 値として保存する文字列または数値
$value_number : 並び順番号。既に値が存在する並び順番号を指定した場合、それより後の値の並び順番号を後ろにずらして新しい値を挿入する。既存の項目数+1よりも大きい値は使用できない。

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

wakarana_user::update_value($custom_field_name, $value_number, $custom_field_value)

ユーザーの指定したカスタムフィールドにおいて既に存在している値を上書きする。

$custom_field_name : カスタムフィールド名
$value_number : 上書きする値の並び順番号
$custom_field_value : 値として保存する文字列または数値

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

wakarana_user::increment_value($custom_field_name, $increments=1)

ユーザーの指定した数値カスタムフィールドに指定した値を加算する。値がない場合は「0」に加算を行う。
異なるユーザーが同一の値持つことを認めていないカスタムフィールドでは使用できない。

$custom_field_name : カスタムフィールド名。2個以上の値の登録が可能なカスタムフィールドは指定できない。
$increments : 加算する値

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

wakarana_user::delete_value($custom_field_name, $value_number=NULL)

ユーザーのカスタムフィールドから並び順番号を指定して値を削除する。
削除された値より後の値の並び順番号は1つ前にずれる。

$custom_field_name : カスタムフィールド名
$value_number : 削除対象の並び順番号(1から順に付番されている整数値)。NULLを指定した場合はユーザーのそのカスタムフィールド値を全て削除する。

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

wakarana_user::remove_value($custom_field_name, $custom_field_value)

ユーザーのカスタムフィールドから指定した値を削除する。
削除された値より後の値の並び順番号は1つ前にずれる。

$custom_field_name : カスタムフィールド名
$custom_field_value : 削除対象の値

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

wakarana_user::delete_all_values()

ユーザーの全てのカスタムフィールドの値を削除する。

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

wakarana_user::get_roles()

ユーザーに割り当てられたロールの一覧を取得する。

返り値 : ユーザーに割り当てられたベースロールを含む全ロールのwakarana_roleインスタンスをロール名のアルファベット順に格納した配列を返す。失敗した場合はFALSEを返す。

wakarana_user::add_role($role_id)

ユーザーにロールを付与する。既にそのユーザーに付与されているロールを指定した場合は何もしない。

$role_id : ロールID

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

wakarana_user::remove_role($role_id=NULL)

ユーザーからロールを剥奪する。ただし、ベースロールは剥奪できない。

$role_id : ロールID。NULLまたは省略した場合、全てのロールを剥奪する。

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

wakarana_user::check_permission($resource_id, $action="any")

ユーザーに権限があるかを確認する。
権限対象リソースIDに「/」が含まれる場合、「/」以下を取り除いた権限対象リソースIDの権限を持っていれば、権限があるものとみなす。

$resource_id : 権限対象リソースID
$action : 動作識別名

返り値 : ユーザーが持つロールのいずれかに権限が割り当てられている場合はTRUE、それ以外の場合はFALSEを返す。

wakarana_user::get_permissions($get_descendant_permissions=TRUE)

ユーザーに割り当てられた権限の一覧を取得する。

$get_descendant_permissions : TRUEを指定した場合、割り当てられている親権限と同一動作の子孫権限も含めて取得する。

返り値 : 権限対象リソースIDをキーとし、値として動作識別名の配列を持った連想配列を返す。権限が存在しない場合は空配列を返す。失敗した場合はFALSEを返す。

wakarana_user::get_permitted_value($permitted_value_id)

ユーザーに割り当てられている最大の権限値を取得する。

$permitted_value_id : 権限値ID

返り値 : ユーザーが持つ全ロールに割り当てられた権限値の中で最大のものを返す。どのロールにも権限値が割り当てられていない場合はNULLを、失敗した場合はFALSEを返す。

wakarana_user::get_permitted_values()

ユーザーに割り当てられた権限値の一覧を取得する。

返り値 : 権限値IDをキーとし、値としてユーザーが持つその権限値の最大値を格納した連想配列を返す。権限値が存在しない場合は空配列を返す。失敗した場合はFALSEを返す。

wakarana_user::delete_all_tokens()

ユーザーの各種トークン(ログイントークン、ワンタイムトークン、メールアドレス確認コード、パスワードリセット用トークン、2段階認証用一時トークン)を全て削除する。

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

wakarana_user::get_auth_logs()

ユーザーのログイン試行履歴を新しい順に配列で取得する。

返り値 : 成功した場合はそのユーザーの各試行履歴が格納された連想配列("succeeded"(認証に成功したか否か)、"authenticate_datetime"(試行日時), "ip_address"(IPアドレス))を、配列に入れて返す。失敗した場合はFALSEを返す。

wakarana_user::check_auth_interval($unsucceeded_only=FALSE)

ユーザーが前回のログイン試行から次に試行できるようになるまでの期間を経過しているかを調べる。

$unsucceeded_only : 失敗した試行のみを対象にする

返り値 : wakarana_config.iniで指定した期間が経過していればTRUE、そうでない場合はFALSEを返す。

wakarana_user::add_auth_log($succeeded)

ユーザーのログイン試行ログを登録する。

$succeeded : ログインが成功した場合はTRUE、失敗した場合はFALSEを指定する。

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

wakarana_user::delete_auth_logs()

ユーザーのログイン試行履歴を全て削除する。

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

wakarana_user::update_last_access($token=NULL)

現在の時刻をユーザーの最終アクセス日時として記録する。
ログイントークンを指定した場合、そのトークンの最終アクセス日時も更新する。
なお、ログイントークン発行処理とログアウト処理ではこの関数が自動的に実行される。

$token : ログイントークン文字列。

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

wakarana_user::get_login_tokens()

ユーザーに発行されている全てのログイントークンの情報を最終アクセス日時の新しい順に2次元配列で取得する。

返り値 : 成功した場合は、そのユーザーに発行されている個々のログイントークンの情報が格納された連想配列("token"(トークン文字列の冒頭6文字)、"token_created"(トークンの生成日時)、"ip_address"(トークン生成時のクライアント端末のIPアドレス)、"operating_system"(トークン生成時のクライアント端末のOS名)、"browser_name"(トークン生成時のクライアント端末のブラウザ名)、"last_access"(そのトークンでの最終アクセス日時))を、配列に入れて返す。失敗した場合はFALSEを返す。

wakarana_user::create_login_token()

ログイントークンを生成とデータベース登録処理を行うが、クライアント端末への送信は行わない。
wakarana::loginとは別のトークン送信処理を実装する必要がある環境向け。

返り値 : 成功した場合は登録されたログイントークン、失敗した場合はFALSEを返す。

wakarana_user::set_login_token()

ユーザーにトークンを割り当て、クライアント端末に送信する。

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

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

wakarana_user::delete_login_token($abbreviated_token)

ユーザーの指定したログイントークンを削除する。

$abbreviated_token : 削除対象のトークンの冒頭6文字

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

wakarana_user::delete_login_tokens()

ユーザーのログイントークンを全て削除する。

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

wakarana_user::authenticate($password, $totp_pin=NULL)

ユーザーに対するパスワードとTOTPコード(2要素認証を使用する場合)の照合を行う。
トークンの生成と送信は行わないが、内部的にログイン試行ログの参照と登録は実施する。

$password : パスワード
$totp_pin : 6桁のTOTPコード。2要素認証を使用しない場合と2要素認証の入力画面を分ける場合は省略。

返り値 : 認証された場合はTRUE、そうでない場合はFALSEを返す。

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

wakarana_user::create_email_address_verification_code($email_address, $check_registration_limit=TRUE)

メールアドレス確認コードを生成し、ユーザーに割り当てる。
前に同じユーザーに対して生成されたメールアドレス確認コードがデータベースに残っていた場合、古いコードは削除される。
この関数によりメールが送信されるわけではない。

$email_address : コードの送信先メールアドレス。
$check_registration_limit : TRUEを指定すると、ユーザーのメールアドレス登録数が上限に達している場合は確認コードを生成しない。

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

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

wakarana_user::email_address_verify($email_address, $verification_code, $verification_only=FALSE)

メールアドレスと、ユーザーのメールアドレス追加用に生成された確認コードとを照合し、認証された場合はユーザーにメールアドレスを追加する。使用済みのメールアドレス確認コードは削除される。

$email_address : コードが紐付けられたメールアドレス
$verification_code : メールアドレス確認コード。大文字小文字を区別しない。
$verification_only : TRUEを指定した場合、認証のみを実行してメールアドレスの追加を行わない

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

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

wakarana_user::get_email_address_verification_code_expire($email_address, $verification_code)

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

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

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

wakarana_user::delete_email_address_verification_code()

ユーザーに対して発行されているメールアドレス確認コードを削除する。

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

wakarana_user::create_invite_code($code_expire=NULL, $remaining_number=NULL)

ユーザー招待コードを生成する。

$code_expire : 有効期限。YYYY-MM-DD hh:mm:ss形式の文字列。NULLを指定した場合は無限とみなす。
$remaining_number : コードの使用可能回数。NULLを指定した場合は無限とみなす。

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

wakarana_user::get_invite_codes()

ユーザーが発行した有効な全ての招待コードを取得する。

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

wakarana_user::delete_invite_codes()

ユーザーが発行した全ての招待コードを削除する。

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

wakarana_user::create_password_reset_token()

ユーザーに対してパスワードリセット用トークンを発行する。

返り値 : 成功した場合はパスワードリセット用トークン、失敗した場合はFALSEを返す。

wakarana_user::delete_password_reset_token()

ユーザーに対して発行されているパスワードリセット用トークンを削除する。

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

wakarana_user::create_2sv_token()

ユーザーに対して2段階認証用の一時トークンを発行する。

返り値 : 成功した場合は一時トークン、失敗した場合はFALSEを返す。

wakarana_user::delete_2sv_token()

ユーザーに対して発行されている2段階認証用の一時トークンを削除する。

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

wakarana_user::create_one_time_token()

ユーザーが利用可能なワンタイムトークンを発行する。

返り値 : 成功した場合はワンタイムトークンを、エラーの場合はFALSEを返す。

wakarana_user::check_one_time_token($token)

ワンタイムトークンを照合する。照合が終わったワンタイムトークンは自動的にデータベースから削除される。

$token : ワンタイムトークン

返り値 : 正しいワンタイムトークンだった場合はTRUEを、それ以外の場合はFALSEを返す。

wakarana_user::delete_one_time_tokens()

ユーザーのワンタイムトークンを全て削除する。

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

wakarana_user::totp_check($totp_pin)

ユーザーに割り当てられたTOTP生成鍵とワンタイムコードを照合する。

$totp_pin : 6桁のTOTPコード

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

wakarana_user::delete_user()

ユーザーアカウントをデータベースから完全に削除する。この関数を呼び出したwakarana_userインスタンスはそれ以降動作しなくなる。

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