README

A CakePHP 3 plugin that enhances Cake's stock AuthComponent to provide a userEntity() method.

Requirements

CakePHP 3.0.0+
PHP 5.6+

Installation

Pull the plugin into your project using composer:

$ composer require loadsys/cakephp-auth-userentity:~1.0

To use this plugin in your app, you must override the stock AuthComponent with the one from this plugin. This is typically done in AppController::initialize():

$this->loadComponent('Auth', [
	/**
	 * Name the plugin's Component as the class to use. This is **required**
	 * in order to use the plugin.
	 */
	'className' => 'AuthUserEntity.UserEntityAuth',

	/**
	 * Name the Entity class that will be used as the container for the
	 * array data in Auth->user(). Defaults to `\Cake\ORM\Entity`, which
	 * is safe for all apps, but will exclude any custom logic you may
	 * have defined in your app's "user" Entity class.
	 */
	'entityClass' => '\App\Model\Entity\User',

	/**
	 * Any options to pass to the new Entity when it is created. The defaults
	 * are:
	 *
	 *   [
	 *       'markClean' => true,    // Force the Entity to appear clean.
	 *       'source' => 'AuthUser', // The repository this record originated from.
	 *                               // We default to a fake name to make it clear
	 *                               // the Entity doesn't represent a "true" ORM
	 *                               // record.
	 *   ]
	 */
	'entityOptions' => [
		'associated' => ['Permissions', 'Groups'],
	],

	/**
	 * (The rest of your normal Auth configs follow here.)
	 */
	// ...
]);

Usage

Once installed, you will be able to retrieve a User entity from your controllers like so:

	// Get the whole entity:
	$user = $this->Auth->userEntity();

	// Or to get a specific property (which will engage any
	// _getProperty() methods you have defined in your Entity class):
	$userEmail = $this->Auth->userEntity('email');

	// Internally, the Entity::get() interface is used, so you can pass
	// nested keys (but remember that this data must be loaded into the
	// Auth session data!):
	$groupName = $this->Auth->userEntity('group.name');

	// Or to call a function from your entity:
	if (!$this->Auth->userEntity()->isAdmin()) {
		$this->Flash->error('Only admins can use this method.');
		return $this->redirect('/');
	}

Like the stock AuthComponent's ::user() method, null will be returned whenever there is no authenticated User data available in the Session. It's also important to remember that only the data that is saved into the Auth session will be available in the Entity, but you can use lazy loading in the Entity class to fetch additional properties as needed or adjust the find query used to authenticate users so associated data is available in the Auth session.

Also keep in mind that currently only the top-level data is marshaled, so sub-properties will exist only as arrays and not Entities themselves.

Contributing

Reporting Issues

Please use GitHub Isuses for listing any known defects or issues.

Development

When developing this plugin, please fork and issue a PR for any new development.

License

MIT

Copyright

Loadsys Web Strategies 2015

loadsys / cakephp-auth-userentity

Maintainers

Details