openclerk / users
Requires
- league/oauth2-client: ~0.6
- openclerk/config: ^0.1
- openclerk/db: ^0.1
- openclerk/events: ^0.2
- soundasleep/lightopenid: dev-master
- soundasleep/php-helpers: dev-master
This package is auto-updated.
Last update: 2024-10-14 10:11:41 UTC
README
A library for User management in Openclerk, supporting password, OpenID and OAuth2 login.
Installing
Include openclerk/users
as a requirement in your project composer.json
,
and run composer update
to install it into your project:
{ "require": { "openclerk/users": "dev-master" }, "repositories": [{ "type": "vcs", "url": "https://github.com/openclerk/users" }] }
Make sure that you run all of the migrations that can be discovered through component-discovery; see the documentation on openclerk/db for more information.
$migrations = new AllMigrations(db()); if ($migrations->hasPending(db())) { $migrations->install(db(), $logger); }
Features
- Automatic session management
- Autologin
- Optionally require emails for all non-password users with
users_require_email
config parameter - Forgot password/reset password functionality
- Users can optionally have multiple OpenID/OAuth2 identities and one password associated with an account
Using
This project uses openclerk/db for database management and openclerk/config for config management.
First configure the component with site-specific values:
Openclerk\Config::merge(array( "users_require_email" => false, "user_password_reset_expiry" => "3 days", "user_password_salt" => "abc123", "autologin_expire_days" => 30, "openid_host" => "localhost", "oauth2_google_client_id" => "abc123.apps.googleusercontent.com", "oauth2_google_client_secret" => "abc123", "oauth2_facebook_app_id" => "1234567", "oauth2_facebook_app_secret" => "abc123", )); session_start();
You can now register and login users using a variety of authentication methods. The component assumes that only one user can own any one email address, and that all users need to define an email address as their primary key.
// get current user $user = Users\User::getInstance(db()); // logout any current user Users\User::logout(db()); // get a user instance $user = Users\User::findUser(db(), $user_id);
Password
// signup $user = Users\UserPassword::trySignup(db(), $email /* may not be null */, $password); if ($user) { echo "<h2>Signed up successfully</h2>"; } // login $user = Users\UserPassword::tryLogin(db(), $email /* may not be null */, $password); if ($user) { echo "<h2>Logged in successfully as $user</h2>"; $user->persist(db()); } // forgot password $secret = Users\UserPassword::forgottenPassword(db(), $email); echo "Secret = $secret\n"; // complete forgot password Users\UserPassword::completePasswordReset(db(), $email, $secret, $new_password); // add password to existing user $user = Users\User::getInstance(db()); $result = Users\UserPassword::addPassword(db(), $user, $password);
OpenID
You need to set a redirect value for all the OpenID callbacks, normally the same URL as the current script.
// signup $user = Users\UserOpenID::trySignup(db(), $email /* may be null */, $openid, "http://localhost/register.php"); if ($user) { echo "<h2>Signed up successfully</h2>"; } // login $user = Users\UserOpenID::tryLogin(db(), $openid, "http://localhost/login.php"); if ($user) { echo "<h2>Logged in successfully as $user</h2>"; $user->persist(db()); } // add identity to existing user $user = Users\User::getInstance(db()); $result = Users\UserOpenID::addIdentity(db(), $user, $openid, "http://localhost/add.php");
OAuth2
For Google OAuth2, login to your Google Developers Console, create a new Project, and visit APIs & Auth:
-
APIs: Enable Contacts API and Google+ API
-
Credentials: create a new Client ID of type web applicaton, setting your permissible Redirect URI to the login and redirect URLs used in your application. Use the generated Client ID and Client Secret in your site configuration (above).
For Facebook OAuth2, login to your Facebook Developers Console, create a new App, and visit the Dashboard page for this app to get your App ID and App Secret.
For GitHub OAuth2, register a new GitHub application, and use the generated Client ID and Client Secret in your site configuration (above).
// signup $user = Users\UserOAuth2::trySignup(db(), Users\OAuth2Providers::google("http://localhost/register.php")); if ($user) { echo "<h2>Signed up successfully</h2>"; } // login $user = Users\UserOAuth2::tryLogin(db(), Users\OAuth2Providers::google("http://localhost/login.php")); if ($user) { echo "<h2>Logged in successfully as $user</h2>"; $user->persist(db()); } // add identity to existing user $user = Users\User::getInstance(db()); $result = Users\UserOAuth2::addIdentity(db(), $user, Users\OAuth2Providers::google("http://localhost/add.php"));
More OAuth2 providers provided by default will be coming soon.
Events
openid_validate
Triggered when OpenID validation occurs, after the user has returned with an OpenID mode.
If any event returns false
, OpenID validation will be cancelled.
Event parameter: $light object
oauth2_auth
Triggered when OpenID authentication occurs, after the user has returned with an OAuth2 code.
If any event returns false
, OpenID validation will be cancelled.
Event parameter: $provider object
user_deleted
Triggered when a user is deleted through User::delete()
.
TODO
- Track last_login
- Removing identities
- Tests
- Publish on Packagist
- Add user names, other user properties
- Documentation on adding additional user parameters
- Documentation on autologin with cookies
- How to add, change, remove email addresses
- More events