Simpleauth の使用方法

Auth パッケージの はじめに で述べたとおり、認証システムは 3 つのドライバで成り立っており、 それぞれがシステムの一部として機能します:

Simpleauth Login ドライバは、ローカルのデータベーステーブルに保存するユーザアカウントの、 生成・更新・削除・検証のロジックを提供します。ユーザアカウントの情報を得たり、パスワードの作成やリセット、 ログインやログアウト (ユーザセッションの作成) を扱うためのものです。

Simpleauth グループ ドライバは、グループ定義情報を simpleauth の設定ファイルに保持しています。 これは、ユーザーがグループのメンバーであるかどうかやグループそのものの情報、またグループに定義されているロールを取得するためのロジックを提供します。

Simpleauth ACL ドライバはロール(役割)駆動型であり、ACL 定義情報を simpleauth の設定ファイルに保持しています。 これは、あるユーザがその名前のロールにアクセス可能かどうかというロジックを提供します。

静的 vs 動的

はじめに、で説明したように、Auth パッケージを使用すると、単一のドライバセットを提供し、利用可能な方法のほとんどに静的なインタフェースを提供します。 これらのメソッドは、"静的: はい" として以下に定義されます。 静的としてマークされてものを含むすべてのメソッドは Auth インスタンスオブジェクト上のチェーンを介してアクセス可能です。

クラスメソッド

validate_user($username_or_email = '', $password = '')

validate_user メソッドはユーザーの資格情報を検証します。このメソッドでは、有効な資格情報としてメールアドレスとユーザー名の両方をサポートしています。

静的 はい
パラメータ
パラメータ デフォルト 説明
$username_or_email
''
ユーザーのユーザー名またはメールアドレスのいずれか
$password
''
ユーザのパスワード
返り値 mixed 。認証に失敗すれば false を、成功した場合は配列でユーザ情報を返す。
// ユーザ名とパスワードを検証
if ($user = Auth::validate_user($name, $pass))
{
	// $name と $pass との組み合わせが検証されたならユーザーの表示名を印字
	echo $user['username'];
}

このメソッドはユーザ名とパスワードの指定された組合せが正しければ検証のみを行います。ユーザーはログインされません!

login($username_or_email = '', $password = '')

login メソッドはログインリクエストを扱います。 パラメータが指定されていない場合は、 simpleauth.php 設定ファイルに設定されたフォームのフィールド名を使用しポストされたデータから取得します。 ログインする前に内部で validate_user() を呼び出し、リクエストを検証します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$username_or_email
''
ユーザーのユーザー名またはメールアドレスのいずれか
$password
''
ユーザのパスワード
返り値 boolean。ログインに成功すれば true を、そうでなければ false を返す。
// ログインを実行
if (Auth::login($name, $pass))
{
	// ユーザーは正常にログインされている
}

ログイン成功後、 'username' と現在の 'login_hash' が、セッション変数として利用できます。

check()

ログインしているユーザーがいるかどうかを check メソッドは検査します。

静的 はい
パラメータ なし
戻り値 boolean。ユーザーがログインしていれば true を、そうでなければ false を返す。
// ログインしていないのであればログインを
if ( ! Auth::check())
{
	Response::redirect('/login');
}

force_login($user_id = '')

force_login メソッドは強制的なログインリクエストを扱います。ユーザ id が手元にありパスワードがわかっていないときに自動ログインさせるために利用できます。これは、例えば「ログイン状態を保持する」機能を実装するために利用できます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$user_id required ログインさせたいユーザの id
返り値 boolean。ログインに成功すれば true を、そうでなければ false を返す。
// ユーザー 12121 の強制ログインを実行
if (Auth::force_login(12121))
{
	// ユーザーは正常にログインされている。以前にログインしていたユーザーはログアウトされます!
}

logout()

logout メソッドは現在ログインしているユーザをログアウトさせます。

静的 はい
パラメータ なし
返り値 boolean。ログアウトが成功し場合、 true を、そうでなければ false を返す。
// ログアウトを実行
Auth::logout();

ゲストユーザをサポートする場合は、ログアウト成功後に現在のユーザとしてゲストをセットアップします。

create_user($username, $password, $email, $group = 1, Array $profile_fields = array())

create_user メソッドは、ユーザ情報テーブルに新しいユーザレコードを作成します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$username required 作成したいユーザー名
$password required ユーザーに割り当てるパスワード
$email required 作成するユーザの電子メールアドレス
$group 1 このユーザーを割り当てるグループ。デフォルトではユーザーはグループ 1 に割り当てられます。
$profile_fields
array()
このユーザに割り当てる任意の追加プロフィールフィールドもしくはユーザメタデータ
例外 SimpleUserUpdateException
返り値 mixed 。作成されたユーザレコードの id を返す。作成に失敗した場合は false を返す。
// 新しいユーザーを作成
Auth::create_user(
	'anewuser',
	'thisismysecretpassword',
	'anewuser@example.org',
	1,
	array(
		'fullname' => 'A. New User',
	)
);

update_user($values, $username = null)

update_user メソッドを使用すると、指名されたユーザー、もしくは、 現在ログインしているユーザー、どちらかのユーザレコードを更新することができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$values
array()
カラム名と値がペアになった連想配列、もしくは更新したいプロフィールフィールド
$username
null
更新したいユーザのユーザ名
例外 SimpleUserUpdateException
返り値 boolean。カラムが更新されれば true を、どのカラムも変更がなければ false を返す。
// 現在のユーザーのデータを更新
Auth::update_user(
	array(
		'email'        => 'anewemail@example.org',  // 新しいメールアドレスを設定する
		'password'     => 'thisismynewpassword',    // 新しいパスワードを設定
		'old_password' => 'thisismysecretpassword', // その為には現在のパスワードを与える!
		'phone'        => '+1 (555) 123-1212',	    // それから、メタデータに電話番号を追加
	)
);

このメソッドは主にユーザがプロファイルの更新を行うことができるように設けられています。そして、セキュリティ対策として、 ユーザー名を変更することはできず、また、パスワードを変更する場合は、現在のパスワードを $values に "old_password" として渡す必要があります。

change_password($old_password, $new_password, $username = null)

change_password は、ユーザパスワードの変更ができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$old_password required ユーザの現在のパスワード
$new_password required ユーザの新しいパスワード
$username
null
パスワードを変更したいユーザのユーザ名
例外 SimpleUserUpdateException
返り値 boolean。パスワードが変更されれば true を、 $old_password が正しくなければ false を返す。
// 現在のユーザのパスワードを変更 (訳注:'reset the password' になっているが、'change' の間違いと思われる)
Auth::change_password('thisismynewpassword','thisismysecretpassword');

このメソッドはユーザーがパスワードを変更できるようにするために設けられています。 また、セキュリティ対策として、現在のパスワードを "old_password" に渡す必要があります。

reset_password($username)

reset_password メソッドは、ユーザに新しいランダムなパスワードを割り当てます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$username required パスワードをリセットしたいユーザのユーザ名
例外 SimpleUserUpdateException
返り値 string、生成されたランダムなパスワード。
// 現在のユーザーのパスワードをリセット
$new_password = Auth::reset_password('thisusername');

delete_user($username)

delete_user メソッドは、ユーザアカウントを削除します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$username required 削除したいユーザのユーザ名
例外 SimpleUserUpdateException
返り値 boolean。ユーザアカウントが削除されれば true を、削除に失敗した場合(ユーザが存在しなかった場合)は false を返す。
// ユーザーを削除
Auth::delete_user('thisusername');

create_login_hash()

create_login_hash メソッドは、現在ログインしているユーザのログインハッシュを生成します。

静的 はい
パラメータ なし
返り値 string、生成されたログインハッシュ。
// ランダムなハッシュを新たに生成
Auth::create_login_hash();

このメソッドは、ユーザーがログインしたとき標準的に使用されますが、ユーザーのログイン中、 定期的にハッシュを回転させることにより追加のセキュリティ対策としてこのメソッドを使用することができます。

同一ユーザの複数の同時ログインが有効になっている場合、ログインハッシュ保護が使用されないことに注意!

get($field, $default = null)

get メソッドは、ユーザレコードからかメタデータからのユーザプロパティの一般的な getter です。

静的 はい
パラメータ
パラメータ デフォルト 説明
$field required 値が欲しいプロパティの名前
$default
null
プロパティが設定されていない場合に返される値
返り値 mixed。
// ユーザの作成日を取得
$created_at = Auth::get('created_at');

get_user_id()

get_user_id メソッドは、ドライバの id 、現在ログインしているユーザの id の配列を返します。 アクティブな複数のログインドライバを持つことができるので、この構造を使用して、 それぞれが現在ログインしているユーザごとに異なる id を持つことができます。

静的 はい
パラメータ なし
返り値 mixed 。ユーザがログイン中なら、 array([0]=>driver_id, [1]=>user_id) 形式の数値配列を、そうでなければ false を返す。
// すべてのログインID情報を取得
$id_info = Auth::get_user_id();

// ドライバおよび id 情報を印字
if ($id_info)
{
	foreach ($id_info as $info)
	{
		echo 'Driver: ',$info[0],' with ID ',$info[1],'<br />';
	}
}
else
{
	echo 'Nobody is logged in!';
}

// ドライバを一つのみ使用する場合、次のようにできます。
list($driver, $userid) = Auth::get_user_id();

// または、ユーザー id のみ必要な場合
list(, $userid) = Auth::get_user_id();

ゲストユーザをサポートしている場合、ゲストユーザのユーザ id が返るので false は返ることはありません。

get_groups()

get_groups メソッドは、ログインしているユーザが所属するグループを返します。

静的 はい
パラメータ なし
返り値 mixed 。ユーザがログイン中なら、 array(array(driver, group_id)) 形式の配列を、そうでなければ false を返します。
// すべてのグループID情報を取得
$id_info = Auth::get_groups();

// ドライバおよび id 情報を印字
if ($id_info)
{
	foreach ($id_info as $info)
	{
		echo 'Driver: ',$info[0],' with group ID ',$info[1],'<br />';
	}
}
else
{
	echo 'Nobody is logged in!';
}

// ドライバを一つのみ使用する場合、次のようにできます。
list($driver, $groupid) = Auth::get_groups();

ゲストユーザをサポートしている場合、ゲストユーザのグループ情報が返るので false は返ることはありません。

get_email()

get_email メソッドは、現在ログインしているユーザに対応するメールアドレスを返します。

静的 はい
パラメータ なし
返り値 mixed 。ユーザがログイン中ならメールアドレスを、ログイン中のユーザがいない場合は false を返す。
// 現在のユーザの電子メールアドレスを取得
$email = Auth::get_email();

// false と empty の間に差があることに注意:
if ($email === false)
{
	// 誰もログインしていない
}
if (empty($email))
{
	// ユーザーがログインしているが電子メールアドレスを持っていない
}

ゲストユーザをサポートしている場合、ゲストユーザのメールアドレスが返るので false は返ることはありません。

get_screen_name()

get_screen_name メソッドは、現在ログインしているユーザの表示名を返します。

静的 はい
パラメータ なし
返り値 mixed 。表示名の文字列を返す。ログイン中のユーザがいなければ false を返す。
// 現在のユーザーの表示名を取得
$name = Auth::get_screen_name();

// 名前は必須、存在しないならば誰もログインしていないことを意味する
if (empty($name))
{
	// 誰もログインしていない
}

ゲストユーザをサポートしている場合、ゲストユーザのユーザー名が返るので false は返ることはありません。

get_profile_fields($field = null, $default = null)

get_profile_fields メソッドは、現在ログインしているユーザの 1 つもしくは全てのプロフィールフィールドのを返します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$field
null
取得したいプロフィールフィールド名
$default
null
取得したいプロフィールフィールドが存在しなかったときのデフォルト返り値
返り値 mixed
// すべてのプロフィールフィールドが定義される
$profile = Auth::get_profile_fields();

member($group, $user = null)

member メソッドは、ユーザーがそのグループのメンバーかどうかをチェックします。

静的 はい
パラメータ
パラメータ デフォルト 説明
$group required チェックしたいグループの id
$user
null
チェックしたいユーザー。 get_user_id() で返されるユーザー id か、null の場合は現在ログインしているユーザー。
返り値 boolean。ユーザーがそのグループのメンバーならば true を、そうでなければ false を返します。
// 現在のユーザーが管理者であるかどうかを検査
if (Auth::member(100))
{
	// 管理者グループに属している!
}

groups($driver = null)

groups メソッドを使用すると、定義されているすべてのグループ、または特定のドライバで定義されているすべてのグループを取得することができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$driver
null
グループを取得したいグループドライバの名前
返り値 array。グループドライバが存在しないか、全くグループが定義されていない場合、空の配列が返されます。
// 定義済みのすべてのグループを取得 (すべてのロードされたグループドライバ用)
$groups = Auth::groups();

// デフォルトのグループドライバからすべてのグループを取得
$groups = Auth::group()->groups();

// 指定のドライバからすべてのグループを取得
$groups = Auth::group('Simplegroup')->groups();

特定のドライバで定義されたグループの場合は、 Auth グループドライバインスタンスに対してこのメソッドを呼び出す必要があります。

複数のドライバを使用する場合、このメソッドはグループ id がすべてのドライバにおいて一意の場合にのみ確実に動作します!

roles($driver = null)

roles メソッドを使用すると、定義されているすべてのロール、または特定のドライバで定義されているすべてのロールを取得することができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$driver
null
ロールを取得したい ACL ドライバの名前 (訳注:'the group driver' になっているが、'the acl driver' の間違いと思われる)
返り値 array。ACL ドライバが存在しないか、全くロールが定義されていない場合、空の配列が返されます。
// 定義済みのすべてのロールを取得 (すべてのロードされた ACL ドライバ用)
$roles = Auth::roles();

// デフォルトの ACL ドライバからすべてのロールを取得
$roles = Auth::acl()->roles();

// 指定のドライバからすべてのロールを取得
$roles = Auth::acl('Simpleacl')->roles();

特定のドライバで定義されたロールの場合は、 Auth ACL ドライバインスタンスに対してこのメソッドを呼び出す必要があります。

複数のドライバを使用する場合、このメソッドはロール id がすべてのドライバにおいて一意の場合にのみ確実に動作します!

get_name($group = null)

get_name メソッドを使用すると、特定のグループの名前を取得することができます。 グループが指定されていない場合は、現在ログインしているユーザのグループ名を返します。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$group
null
名前を取得したいグループの id
返り値 グループの名前、もしくは、与えられた id を持つグループが存在しない場合は null
// 現在ログインしているユーザーのグループのすべての名前を取得
$name = Auth::group()->get_name();

// 特定のドライバから特定のグループの名前を取得
$name = Auth::group('Simplegroup')->get_name(100);	// 'Administrators' が返る

複数のドライバを使用する場合、このメソッドはグループ id がすべてのドライバにおいて一意の場合にのみ確実に動作します!

has_access($condition)

has_access メソッドは現在ログインしているユーザーが特定の権限を持つ特定の場所へのアクセス権を持っているかどうかを検査することができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$condition required 検査したいアクセス条件
返り値 boolean。アクセス権を持っていれば true 、そうでなければ false
// ユーザーがブログ記事を読むためのアクセス権を持っているかどうかを検査
if (Auth::has_access('blog.read'))
{
	// はい、ユーザーはアクセス権を持っています
}

// 複数のログインインスタンスがある場合、このメソッドを呼び出すためにはインスタンスを使用します。
// また、一度に複数の権限を検査することもできます
if (Auth::instance('simpleauth')->has_access('blog.[read,write,delete]'))
{
	// はい、ユーザーはアクセス権を持っており、読み取りも書き込みも削除も可能です
}

// また、配列として検査する権限を指定することもできます
if (Auth::has_access(array('blog' => array('read'), 'comments' => array('read')))
{
	// はい、ユーザーはブログとコメントの読み取りのアクセス権を持っています
}

// 複数のログインインスタンスがある場合、特定の ACL ドライバーを選ぶことができます
if (Auth::acl('simpleacl')->has_access('blog.[read,write,delete]'))
{
	// はい、ユーザーはアクセス権を持っており、読み取りも書き込みも削除も可能です
}

guest_login()

guest_login メソッドは、ゲストログインが可能か確認します。

静的 はい
パラメータ なし
返り値 boolean。ゲストログインがサポートされていれば true を、そうでなければ false を返す。
// ログインしておらずゲストユーザーも有効になっていない場合、 login にリダイレクト
if ( ! Auth::check() and ! Auth::guest_login())
{
	Response::redirect('/login');
}

remember_me($user_id = null)

remember_me メソッドは、 remember_me クッキーを設定することができます。 $user_id が指定されていない場合は、現在ログインしているユーザーが使用されます。

静的 はい
パラメータ
パラメータ デフォルト パラメータ
$user_id
null
記憶するユーザーの id
返り値 boolean。正しく remember me クッキーが設定されていれば true を、 user_id が存在しないか remember_me 機能が設定で無効になっている場合 false が返されます。
// ログインフォームの POST を処理し、必要に応じて remember-me クッキーを設定
if (\Input::method() == 'POST')
{
	// 資格情報を検査
	if (\Auth::instance()->login(\Input::param('username'), \Input::param('password')))
	{
		// ユーザーは覚えてほしい?
		if (\Input::param('rememberme', false))
		{
			// remember-me クッキーを作成
			\Auth::remember_me();
		}
		else
		{
			// 存在する場合、 remember-me クッキーを削除
			\Auth::dont_remember_me();
		}

		// ログインしホームページに移動
		\Response::redirect('/');
	}
	else
	{
		// ログイン失敗、エラーメッセージを表示
		$data['username']    = \Input::param('username');
		$data['login_error'] = \Lang::get('login.failure');
	}
}

dont_remember_me()

dont_remember_me メソッドは remember_me クッキーが存在する場合にそれを破棄します。

静的 はい
パラメータ なし
例は remember_me() を参照してください