# Migration Guide from 15.x to 16.0

This guide describes the changes needed to upgrade your application from version 15.x to 16.0 of the CakeDC Users plugin.

## PHP Version Requirement

The minimum PHP version has been increased to **8.2**. If your application is running on an older version of PHP, you must upgrade it before updating the plugin.

## CakePHP Version Requirement

This version is designed for **CakePHP 5.3**. Ensure your application is updated to at least CakePHP 5.3.

## Plugin Class Renamed

The main plugin class has been renamed from `CakeDC\Users\Plugin` to `CakeDC\Users\UsersPlugin`.

### Update Plugin Loading

In your `src/Application.php`, update the plugin loading:

```php
// src/Application.php
public function bootstrap(): void
{
    parent::bootstrap();
    // Change this
    // $this->addPlugin(\CakeDC\Users\Plugin::class);
    // To this
    $this->addPlugin(\CakeDC\Users\UsersPlugin::class);
}
```

### Update Event Constants

If you are using any event constants from the `Plugin` class, you need to update them to use `UsersPlugin`.

```php
// Change this
// \CakeDC\Users\Plugin::EVENT_AFTER_LOGIN
// To this
\CakeDC\Users\UsersPlugin::EVENT_AFTER_LOGIN
```

Commonly used constants:
- `EVENT_BEFORE_LOGOUT`
- `EVENT_AFTER_LOGOUT`
- `EVENT_BEFORE_REGISTER`
- `EVENT_AFTER_REGISTER`
- `EVENT_BEFORE_SOCIAL_LOGIN_REDIRECT`
- `EVENT_AFTER_CHANGE_PASSWORD`
- `EVENT_AFTER_RESEND_TOKEN_VALIDATION`
- `EVENT_AFTER_EMAIL_TOKEN_VALIDATION`

## Authentication Configuration Changes

The authentication configuration structure in `config/users.php` has been updated to align with the latest `cakephp/authentication` practices. The `Identifiers` top-level key has been removed, and identifiers are now defined directly within each authenticator.

### Update `config/users.php`

If you have a custom `config/users.php` file, you need to move the identifier configurations.

**Old Configuration (Version 15):**

```php
'Auth' => [
    'Authenticators' => [
        'Form' => [
            'className' => 'CakeDC/Auth.Form',
            // ...
        ],
        // ...
    ],
    'Identifiers' => [
        'Password' => [
            'className' => 'Authentication.Password',
            'fields' => [
                'username' => ['username', 'email'],
                'password' => 'password',
            ],
            // ...
        ],
        // ...
    ],
]
```

**New Configuration (Version 16):**

```php
'Auth' => [
    'Authenticators' => [
        'Form' => [
            'className' => 'CakeDC/Auth.Form',
            'identifier' => [
                'Authentication.Password' => [
                    'fields' => [
                        'username' => ['username', 'email'],
                        'password' => 'password',
                    ],
                    'resolver' => [
                        'className' => 'Authentication.Orm',
                        'finder' => 'active',
                    ],
                ],
            ],
        ],
        'Token' => [
            'className' => 'Authentication.Token',
            'identifier' => [
                'Authentication.Token' => [
                    'tokenField' => 'api_token',
                    'resolver' => [
                        'className' => 'Authentication.Orm',
                        'finder' => 'active',
                    ],
                ],
            ],
        ],
        'Social' => [
            'className' => 'CakeDC/Users.Social',
            'identifier' => [
                'CakeDC/Users.Social' => [
                    'authFinder' => 'active',
                ],
            ],
        ],
        // ...
    ],
]
```

## Internal Changes

### Password Rehashing

The `LoginComponent` now handles password rehashing differently to support the new authenticator-based identifier configuration. If you have overridden `LoginComponent::handleLogin`, please review the changes in the plugin's source code.

### Traits and Behaviors

Several traits and behaviors have been updated with stricter type hints and return types to comply with CakePHP 5.3 and modern PHP standards. If you are overriding methods from these traits, ensure your method signatures match the new ones.
