PHPackages winter/wn-user-plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. winter/wn-user-plugin ActiveWinter-plugin[Authentication & Authorization](/categories/authentication) winter/wn-user-plugin ===================== User plugin for Winter CMS v2.3.0(9mo ago)1233.5k↓31.5%20[7 issues](https://github.com/wintercms/wn-user-plugin/issues)[2 PRs](https://github.com/wintercms/wn-user-plugin/pulls)13MITPHPCI passing Since Jun 22Pushed 2mo ago5 watchersCompare [ Source](https://github.com/wintercms/wn-user-plugin)[ Packagist](https://packagist.org/packages/winter/wn-user-plugin)[ Docs](https://github.com/wintercms/wn-user-plugin)[ GitHub Sponsors](https://github.com/wintercms)[ Fund](https://opencollective.com/wintercms)[ RSS](/packages/winter-wn-user-plugin/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (7)Dependencies (2)Versions (15)Used By (13) Frontend User plugin ==================== [](#frontend-user-plugin) [![Build Status](https://camo.githubusercontent.com/d23bd53d6c75688ab87b3c60242ec070e6aa87b5f287f8e29fa14bb29bc2816b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f77696e746572636d732f776e2d757365722d706c7567696e2f74657374732e796d6c3f6272616e63683d6d61696e)](https://github.com/wintercms/wn-user-plugin/actions)[![MIT License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://github.com/wintercms/wn-user-plugin/blob/master/LICENCE.md) Provides frontend user management for Winter CMS. This allows you to separate out the users on the frontend of your Winter CMS website / application from the more privileged backend users that come default in Winter CMS. Supports: - Users - Groups - Registration / Activation / Login / Logout / Password Reset - Authentication / Authorization - Extensible by external plugins Requirements ------------ [](#requirements) This plugin requires either [Snowboard framework](https://wintercms.com/docs/v1.2/docs/snowboard/introduction) or the original [Ajax Framework](https://wintercms.com/docs/v1.2/docs/ajax/introduction) to be included in your layout or page in order to handle form requests. Installation ------------ [](#installation) This plugin is available for installation via [Composer](http://getcomposer.org/). ``` composer require winter/wn-user-plugin ``` After installing the plugin you will need to run the migrations and (if you are using a [public folder](https://wintercms.com/docs/develop/docs/setup/configuration#using-a-public-folder)) [republish your public directory](https://wintercms.com/docs/develop/docs/console/setup-maintenance#mirror-public-files). ``` php artisan migrate ``` Managing users -------------- [](#managing-users) Users are managed on the Users tab found in the back-end. Each user provides minimal data fields - **Name**, **Surname**, **Email** and **Password**. The Name can represent either the person's first name or their full name, making the Surname field optional, depending on the complexity of your site. Below the **Email** field is an checkbox to block all outgoing mail sent to the user. This is a useful feature for accounts with an email address that is bouncing mail or has reported spam. When checked, no mail will ever be sent to this address, except for the mail template used for resetting the password. Plugin settings --------------- [](#plugin-settings) This plugin creates a Settings menu item, found by navigating to **Settings > Users > User settings**. This page allows the setting of common features, described in more detail below. #### Registration [](#registration) Registration to the site is allowed by default. If you are running a closed site, or need to temporarily disable registration, you may disable this feature by switching **Allow user registration** to the OFF setting. #### Activation [](#activation) Activation is a process of vetting a user who joins the site. By default, users are activated automatically when they register and an activated account is required to sign in. The **Activation mode** specifies the activation workflow: - **Automatic**: This mode will automatically activate a user when they first register. This is the same as disabling activation entirely and is the default setting. - **User**: The user can activate their account by responding to a confirmation message sent to their nominated email address. - **Administrator**: The user can only be activated by an administrator via the back-end area. You can allow users to sign in without activating by switching **Sign in requires activation** to the OFF setting. This is useful for minimising friction when registering, however with this approach it is often a good idea to disable any "identity sensitive" features until the user has been activated, such as posting content. Alternatively, you could implement a grace period that deletes users (with sufficient warning!) who have not activated within a given period of time. Users have the ability to resend the activation email by clicking **Send the verification email again** found in the Account component. #### Sign in [](#sign-in) By default a User will sign in to the site using their email address as a unique identifier. You may use a unique login name instead by changing the **Login attribute** value to Username. This will introduce a new field called **Username** for each user, allowing them to specify their own short name or alias for identification. Both the Email address and Username must be unique to the user. If a user experiences too many failed sign in attempts, their account will be temporarily suspended for a period of time. This feature is enabled by default and will suspend an account for 15 minutes after 5 failed sign in attempts, for a given IP address. You may disable this feature by switching **Throttle attempts** to the OFF setting. As a security precaution, you may restrict users from having sessions across multiple devices at the same time. Enable the **Prevent concurrent sessions** setting to use this feature. When a user signs in to their account, it will automatically sign out the user for all other sessions. #### Notifications [](#notifications) When a user is first activated -- either by registration, email confirmation or administrator approval -- they are sent a welcome email. To disable the welcome email, select "Do not send a notification" from the **Welcome mail template** dropdown. The default message template used is `winter.user::mail.welcome` and you can customize this by selecting **Mail > Mail Templates** from the settings menu. Session component ----------------- [](#session-component) The session component should be added to a layout that has registered users. It has no default markup. ### User variable [](#user-variable) You can check the logged in user by accessing the `{{ user }}` Twig variable: ``` {% if user %} Hello {{ user.name }} {% else %} Nobody is logged in {% endif %} ``` ### Signing out [](#signing-out) The Session component allows a user to sign out of their session. ``` Sign out ``` ### Page restriction [](#page-restriction) The Session component allows the restriction of a page or layout by allowing only signed in users, only guests or no restriction. This example shows how to restrict a page to users only: ``` title = "Restricted page" url = "/users-only" [session] security = "user" redirect = "home" ``` The `security` property can be user, guest or all. The `redirect` property refers to a page name to redirect to when access is restricted. ### Route restriction [](#route-restriction) Access to routes can be restricted by applying the `AuthMiddleware`. ``` Route::group(['middleware' => ['web', 'Winter\User\Classes\AuthMiddleware']], function () { // All routes here will require authentication }); ``` Account component ----------------- [](#account-component) The account component provides a user sign in form, registration form, activation form and update form. To display the form: ``` title = "Account" url = "/account/:code?" [account] redirect = "home" paramCode = "code" == {% component 'account' %} ``` If the user is logged out, this will display a sign in and registration form. Otherwise, it will display an update form. The `redirect` property is the page name to redirect to after the submit process is complete. The `paramCode` is the URL routing code used for activating the user, only used if the feature is enabled. Reset Password component ------------------------ [](#reset-password-component) The reset password component allows a user to reset their password if they have forgotten it. ``` title = "Forgotten your password?" url = "/forgot-password/:code?" [resetPassword] paramCode = "code" == {% component 'resetPassword' %} ``` This will display the initial restoration request form and also the password reset form used after the verification email has been received by the user. The `paramCode` is the URL routing code used for resetting the password. Using a login name ------------------ [](#using-a-login-name) By default the User plugin will use the email address as the login name. To switch to using a user defined login name, navigate to the backend under System > Users > User Settings and change the Login attribute under the Sign in tab to be **Username**. Then simply ask for a username upon registration by adding the username field: ``` Full Name Email Username Password Register ``` We can add any other additional fields here too, such as `phone`, `company`, etc. Password length requirements ---------------------------- [](#password-length-requirements) By default, the User plugin requires a minimum password length of 8 characters for all users when registering or changing their password. You can change this length requirement by going to config/config.php. Inside the file, change the value of the `minPasswordLength` parameter to your own. Error handling -------------- [](#error-handling) ### Flash messages [](#flash-messages) This plugin makes use of Winter CMS's [Flash API](https://wintercms.com/docs/v1.2/markup/tags/flash). In order to display the error messages, you need to place the following snippet in your layout or page. ``` {% flash %} {{ message }} {% endflash %} ``` ### AJAX errors [](#ajax-errors) The User plugin displays AJAX error messages in a simple `alert()`-box by default. However, this might scare non-technical users. You can change the default behavior of an AJAX error from displaying an `alert()` message, like this: ``` $(window).on('ajaxErrorMessage', function (event, message) { // This can be any custom JavaScript you want alert('Something bad happened, mate, here it is: ' + message); // This will stop the default alert() message event.preventDefault(); }) ``` ### Checking if a login name is already taken [](#checking-if-a-login-name-is-already-taken) > **NOTE**: Implementing the below example may be a privacy risk as it allows unauthenticated users to query your service to see if given email addresses are signed up to your service or not. Here is a simple example of how you can quickly check if an email address / username is available in your registration forms. First, inside the page code, define the following AJAX handler to check the login name, here we are using the email address: ``` public function onCheckEmail() { return ['isTaken' => Auth::findUserByLogin(post('email')) ? 1 : 0]; } ``` For the email input we use the `data-request` and `data-track-input` attributes to call the `onCheckEmail` handler any time the field is updated. The `data-request-success` attribute will call some jQuery code to toggle the alert box. ``` Email address Sorry, that login name is already taken. ``` Overriding functionality ------------------------ [](#overriding-functionality) Here is how you would override the `onSignin()` handler to log any error messages. Inside the page code, define this method: ``` function onSignin() { try { return $this->account->onSignin(); } catch (Exception $ex) { Log::error($ex); } } ``` Here the local handler method will take priority over the **account** component's event handler. Then we simply inherit the logic by calling the parent handler manually, via the component object (`$this->account`). Auth facade ----------- [](#auth-facade) There is an `Auth` facade you may use for common tasks, it primarily inherits the `Winter\Storm\Auth\Manager` class for functionality. You may use `Auth::register` to register an account: ``` $user = Auth::register([ 'name' => 'Some User', 'email' => 'some@website.tld', 'password' => 'changeme', 'password_confirmation' => 'changeme', ]); ``` The second argument can specify if the account should be automatically activated: ``` // Auto activate this user $user = Auth::register([...], true); ``` The `Auth::check` method is a quick way to check if the user is signed in. ``` // Returns true if signed in. $loggedIn = Auth::check(); ``` To return the user model that is signed in, use `Auth::getUser` instead. ``` // Returns the signed in user $user = Auth::getUser(); ``` You may authenticate a user by providing their login and password with `Auth::authenticate`. ``` // Authenticate user by credentials $user = Auth::authenticate([ 'login' => post('login'), 'password' => post('password') ]); ``` The second argument is used to store a non-expire cookie for the user. ``` $user = Auth::authenticate([...], true); ``` You can also authenticate as a user simply by passing the user model along with `Auth::login`. ``` // Sign in as a specific user Auth::login($user); ``` The second argument is the same. ``` // Sign in and remember the user Auth::login($user, true); ``` You may look up a user by their login name using the `Auth::findUserByLogin` method. ``` $user = Auth::findUserByLogin('some@email.tld'); ``` Guest users ----------- [](#guest-users) Creating a guest user allows the registration process to be deferred. For example, making a purchase without needing to register first. Guest users are not able to sign in and will be added to the user group with the code `guest`. Use the `Auth::registerGuest` method to create a guest user, it will return a user object and can be called multiple times. The unique identifier is the email address, which is a required field. ``` $user = Auth::registerGuest(['email' => 'person@acme.tld']); ``` When a user registers with the same email address using the `Auth::register` method, they will inherit the existing guest user account. ``` // This will not throw an "Email already taken" error $user = Auth::register([ 'email' => 'person@acme.tld', 'password' => 'changeme', 'password_confirmation' => 'changeme', ]); ``` > **Important**: If you are using guest accounts, it is important to disable sensitive functionality for user accounts that are not verified, since it may be possible for anyone to inherit a guest account. You may also convert a guest to a registered user with the `convertToRegistered` method. This will generate a random password and sends an invitation using the `winter.user::mail.invite` template. ``` $user->convertToRegistered(); ``` To disable the notification and password reset, pass the first argument as false. ``` $user->convertToRegistered(false); ``` Events ------ [](#events) This plugin will fire some global events that can be useful for interacting with other plugins. - `winter.user.beforeRegister`: Before the user's registration is processed. Passed the `$data` variable by reference to enable direct modifications to the `$data` provided to the `Auth::register()` method. - `winter.user.register`: The user has successfully registered. Passed the `$user` object and the submitted `$data` variable. - `winter.user.beforeAuthenticate`: Before the user is attempting to authenticate using the Account component. - `winter.user.login`: The user has successfully signed in. - `winter.user.logout`: The user has successfully signed out. - `winter.user.activate`: The user has activated their own account by email validation. - `winter.user.deactivate`: The user has opted-out of the site by deactivating their account. This should be used to disable any content the user may want removed. - `winter.user.reactivate`: The user has reactivated their own account by signing back in. This should revive the users content on the site. - `winter.user.getNotificationVars`: Fires when sending a user notification to enable passing more variables to the email templates. Passes the `$user` model the template will be for. - `winter.user.view.extendListToolbar`: Fires when the user listing page's toolbar is rendered. - `winter.user.view.extendPreviewToolbar`: Fires when the user preview page's toolbar is rendered. Here is an example of hooking an event: ``` Event::listen('winter.user.deactivate', function($user) { // Hide all posts by the user }); ``` A common requirement is to adapt another to a legacy authentication system. In the example below, the `WordPressLogin::check` method would check the user password using an alternative hashing method, and if successful, update to the new one used by Winter CMS. ``` Event::listen('winter.user.beforeAuthenticate', function($component, $credentials) { $login = array_get($credentials, 'login'); $password = array_get($credentials, 'password'); /* * No such user exists */ if (!$user = Auth::findUserByLogin($login)) { return; } /* * The user is logging in with their old WordPress account * for the first time. Rehash their password using the new * Winter CMS system. */ if (WordPressLogin::check($user->password, $password)) { $user->password = $user->password_confirmation = $password; $user->forceSave(); } }); ``` ### Health Score 52 — FairBetter than 96% of packages Maintenance62 Regular maintenance activity Popularity39 Limited adoption so far Community36 Small or concentrated contributor base Maturity66 Established project with proven stability Bus Factor1 Top contributor holds 58.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~202 days Recently: every ~192 days Total 12 Last Release 299d ago Major Versions v1.5.4 → v2.0.02021-04-26 PHP version history (2 changes)v1.5.0PHP >=5.5.9 v2.0.0PHP >=7.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7253840?v=4)[Luke Towers](/maintainers/LukeTowers)[@LukeTowers](https://github.com/LukeTowers) --- Top Contributors [![daftspunk](https://avatars.githubusercontent.com/u/1392869?v=4)](https://github.com/daftspunk "daftspunk (328 commits)")[![LukeTowers](https://avatars.githubusercontent.com/u/7253840?v=4)](https://github.com/LukeTowers "LukeTowers (52 commits)")[![bennothommo](https://avatars.githubusercontent.com/u/15900351?v=4)](https://github.com/bennothommo "bennothommo (42 commits)")[![gergo85](https://avatars.githubusercontent.com/u/2959112?v=4)](https://github.com/gergo85 "gergo85 (30 commits)")[![mjauvin](https://avatars.githubusercontent.com/u/2013630?v=4)](https://github.com/mjauvin "mjauvin (24 commits)")[![TheServat](https://avatars.githubusercontent.com/u/12908537?v=4)](https://github.com/TheServat "TheServat (8 commits)")[![vojtasvoboda](https://avatars.githubusercontent.com/u/374917?v=4)](https://github.com/vojtasvoboda "vojtasvoboda (8 commits)")[![alekseybobkov](https://avatars.githubusercontent.com/u/481606?v=4)](https://github.com/alekseybobkov "alekseybobkov (7 commits)")[![gabsource](https://avatars.githubusercontent.com/u/1851314?v=4)](https://github.com/gabsource "gabsource (7 commits)")[![WebVPF](https://avatars.githubusercontent.com/u/61043464?v=4)](https://github.com/WebVPF "WebVPF (5 commits)")[![RomainMazB](https://avatars.githubusercontent.com/u/53976837?v=4)](https://github.com/RomainMazB "RomainMazB (4 commits)")[![rubenvanerk](https://avatars.githubusercontent.com/u/20305359?v=4)](https://github.com/rubenvanerk "rubenvanerk (4 commits)")[![AIC-BV](https://avatars.githubusercontent.com/u/89913092?v=4)](https://github.com/AIC-BV "AIC-BV (4 commits)")[![yapsr](https://avatars.githubusercontent.com/u/3018553?v=4)](https://github.com/yapsr "yapsr (4 commits)")[![scottbedard](https://avatars.githubusercontent.com/u/7980426?v=4)](https://github.com/scottbedard "scottbedard (4 commits)")[![buuug7](https://avatars.githubusercontent.com/u/12119289?v=4)](https://github.com/buuug7 "buuug7 (3 commits)")[![ShahiemS](https://avatars.githubusercontent.com/u/188719889?v=4)](https://github.com/ShahiemS "ShahiemS (3 commits)")[![joakimbo](https://avatars.githubusercontent.com/u/10329253?v=4)](https://github.com/joakimbo "joakimbo (2 commits)")[![alvaro-canepa](https://avatars.githubusercontent.com/u/5142298?v=4)](https://github.com/alvaro-canepa "alvaro-canepa (2 commits)")[![alxy](https://avatars.githubusercontent.com/u/2057062?v=4)](https://github.com/alxy "alxy (2 commits)") --- Tags authenticationhacktoberfestpluginuserwintercmspluginAuthenticationuserwinterwinter cms ### Embed Badge ![Health badge](/badges/winter-wn-user-plugin/health.svg) ``` [![Health](https://phpackages.com/badges/winter-wn-user-plugin/health.svg)](https://phpackages.com/packages/winter-wn-user-plugin) ``` ### Alternatives [lab404/laravel-auth-checker Laravel Auth Checker allows you to log users authentication, devices authenticated from and lock intrusions. 223164.9k2](/packages/lab404-laravel-auth-checker)[winter/wn-blog-plugin Blog plugin for Winter CMS 2042.1k3](/packages/winter-wn-blog-plugin)[winter/wn-sitemap-plugin Sitemap plugin for Winter CMS 1042.6k1](/packages/winter-wn-sitemap-plugin)[asgardcms/user-module User module for AsgardCMS. Handles the authentication and authorisation as well as the user management. 1129.5k2](/packages/asgardcms-user-module) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)