nojimage / cakephp-remember-me

v5.3.0 2026-10-08 04:08 UTC

Requires

• php: >=8.1
• ext-json: *
• cakephp/authentication: ^3.3.4 || ^4.0
• cakephp/core: ^5.0
• cakephp/orm: ^5.0

Requires (Dev)

• cakephp/cakephp: ^5.0
• cakephp/cakephp-codesniffer: ^5.1
• cakephp/migrations: ^4.6 || ^5.0
• phpstan/phpstan: ^2.3
• phpunit/phpunit: ^10.5.5 || ^11.1.3 || ^12.0.9

MIT

• Authentication
• cakephp
• auth
• cookie
• remember-me

Published on Packagist.org on 2026-10-08 04:23 UTC

README

This plugin provides an authentication handler that enables permanent login via cookie. This plugin uses a method of issuing a token instead of setting an encrypted username / password in a cookie.

This library is inspired by Barry Jaspan's article "Improved Persistent Login Cookie Best Practice", and Gabriel Birke's library "https://github.com/gbirke/rememberme".

Installation

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

php composer.phar require nojimage/cakephp-remember-me:^5.0

Load the plugin by adding the following statement in your project's src/Application.php:

$this->addPlugin('RememberMe');

or running the console command

bin/cake plugin load RememberMe

Run migration:

bin/cake migrations migrate -p RememberMe

Usage with Authentication plugin

If you're using cakephp/authentication, use RememberMeTokenIdentifier and CookieAuthenticator. Both cakephp/authentication 3.x (3.3.4 or later) and 4.x are supported.

Example of loading RememberMe's Identifier and Authenticator into the getAuthenticationService hook within Application:

// in your src/Application.php
class Application extends ...
{
    public function getAuthenticationService(...): void
    {
        $service = new AuthenticationService();
        $fields = [
            'username' => 'email',
            'password' => 'password'
        ];
        // ... setup other authenticators

        // setup RememberMe
        $service->loadAuthenticator('RememberMe.Cookie', [
            'identifier' => [
                'className' => 'RememberMe.RememberMeToken',
                'fields' => $fields,
            ],
            'fields' => $fields,
            'loginUrl' => '/users/login',
        ]);
    }
}

With cakephp/authentication 3.x, an identifier array is keyed by the identifier name:

        $service->loadAuthenticator('RememberMe.Cookie', [
            'identifier' => [
                'RememberMe.RememberMeToken' => ['fields' => $fields],
            ],
            'fields' => $fields,
            'loginUrl' => '/users/login',
        ]);

'identifier' => 'RememberMe.RememberMeToken' (without options) works on both versions. $service->loadIdentifier() still works on 3.x, but it is deprecated since 3.3.0 and removed in 4.x.

With 4.x, if identifier is omitted, a RememberMeTokenIdentifier is created with the authenticator's fields and tokenStorageModel. Its resolver uses the Users model, so set identifier when your user model is different.

more document for getAuthenticationService, see: Quick Start - CakePHP Authentication 4.x

RememberMe.RememberMeTokenIdentifier options

The examples below use the 4.x format. With 3.x, put the options in 'identifier' => ['RememberMe.RememberMeToken' => [...]].

fields

The fields for the lookup.

default: ['username' => 'username']

    $service->loadAuthenticator('RememberMe.Cookie', [
        'identifier' => [
            'className' => 'RememberMe.RememberMeToken',
            'fields' => [
                'username' => 'email',
            ],
        ],
    ]);

resolver

The identity resolver. If you change your Resolver, it must extend Authentication\Identifier\Resolver\OrmResolver.

default: 'Authentication.Orm'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'identifier' => [
            'className' => 'RememberMe.RememberMeToken',
            'resolver' => [
                'className' => 'Authentication.Orm',
                'userModel' => 'Administrators',
            ],
        ],
    ]);

tokenStorageModel

A model used for finding login cookie tokens.

default: 'RememberMe.RememberMeTokens'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'identifier' => [
            'className' => 'RememberMe.RememberMeToken',
            'tokenStorageModel' => 'YourTokensModel',
        ],
    ]);

userTokenFieldName

A property name when adding token data to identity.

default: 'remember_me_token'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'identifier' => [
            'className' => 'RememberMe.RememberMeToken',
            'userTokenFieldName' => 'cookie_token',
        ],
    ]);

RememberMe.CookeAuthenticator options

identifier

The identifier used to verify login cookie tokens. See above.

default: null (a RememberMeTokenIdentifier is created)

loginUrl

The login URL. Default is null and all pages will be checked.

default: null

    $service->loadAuthenticator('RememberMe.Cookie', [
        'loginUrl' => '/users/login',
    ]);

urlChecker

The URL checker class or object.

default: 'Authentication.Default'

The behavior of Authentication.Default depends on the cakephp/authentication version:

• 3.x: compares the URL as a string. It accepts an array of URLs and the useRegex option.
• 4.x: compares the URL through Router::url(), so a route array is also accepted. Use 'Authentication.Multi' for multiple URLs, and 'Authentication.String' for regular expressions.

    $service->loadAuthenticator('RememberMe.Cookie', [
        'urlChecker' => 'Authentication.Multi',
        'loginUrl' => [
            '/en/users/login',
            '/ja/users/login',
        ],
    ]);

rememberMeField

When this key is input by form authentication, it issues a login cookie.

default: 'remember_me'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'rememberMeField' => 'remember_me',
    ]);

fields

Array that maps username to the specified POST data fields.

default: ['username' => 'username']

    $service->loadAuthenticator('RememberMe.Cookie', [
        'fields' => [
            'username' => 'email',
        ],
    ]);

cookie

Write option for login cookie.

• name: Cookie name (default: 'rememberMe')
• expire: Cookie expiration (default: '+30 days')
• path: Path (default: '/')
• domain: Domain, (default: '')
• secure: Secure flag (default: true)
• httpOnly: Http only flag (default: true)

    $service->loadAuthenticator('RememberMe.Cookie', [
        'cookie' => [
            'name' => 'rememberMe',
            'expires' => '+30 days',
            'secure' => true,
            'httpOnly' => true,
        ],
    ]);

tokenStorageModel

A model used for storing login cookie tokens.

default: 'RememberMe.RememberMeTokens'

    $service->loadAuthenticator('RememberMe.Cookie', [
        'tokenStorageModel' => 'YourTokensModel',
    ]);

always

When this option is set to true, a login cookie is always issued after successful authentication.

default: false

    $service->loadAuthenticator('RememberMe.Cookie', [
        'always' => true,
    ]);

dropExpiredToken

When this option is set to true, expired tokens are dropped after successful authentication.

default: true

    $service->loadAuthenticator('RememberMe.Cookie', [
        'dropExpiredToken' => false,
    ]);