# Migration Guide from 12.x to 14.0

This guide describes the changes needed to upgrade your application from version 12.x to 14.0 of the CakeDC Users plugin. Both versions are compatible with CakePHP 5.0, but 12.x was a beta release, while 14.0 is the stable release with several new features and refactorings.

## CakePHP Version Requirement

Both version 12.0 and 14.0 of the CakeDC Users plugin are designed for **CakePHP 5.0+**. If you are still on the version 12.0 beta, you should already be on CakePHP 5.

## Database Migration

This version introduces the **Password Lockout** feature, which requires a new table and an additional column in the `users` table. You must run the migrations to update your database schema.

```bash
bin/cake migrations migrate -p CakeDC/Users
```

The migrations will:
- Create the `failed_password_attempts` table.
- Add the `lockout_time` (datetime) column to the `users` table.
- Update the `avatar` column type to `text` in the `social_accounts` table.

## Dependency Changes

The following dependencies have been updated:

- `cakedc/auth` has been updated to `^10.0`.

## Password Lockout Feature

A new `PasswordLockoutIdentifier` has been introduced to prevent brute-force attacks by locking accounts after a certain number of failed attempts.

To enable this, update your `config/users.php` to use the new identifier:

```php
'Auth' => [
    'Identifiers' => [
        'Password' => [
            'className' => 'CakeDC/Users.PasswordLockout',
            // ...
        ],
    ],
]
```

## Configuration Changes

### Removed Configuration Keys

Several configuration keys have been removed or refactored. Please update your `config/users.php`:

- `Users.PasswordReset.findWith`: Removed.
- `Users.reCaptcha.version`: Removed (defaults to version 2).
- `Users.passwordMeter`: This entire section has been removed from the default configuration as part of a refactor in `UserHelper`.

### 2FA Configuration

The default `qrcodeprovider` for Two-Factor Authentication is now set to `null` by default.

```php
'TwoFactor' => [
    // ...
    'qrcodeprovider' => null,
],
```

## View Helper Changes

### UserHelper

The `UserHelper` has undergone significant refactoring:

- `addPasswordMeterScript()`: This method has been removed. The password meter logic is now handled differently.
- `socialLogin()` and `socialLoginList()`: Signatures updated and internal implementation refactored.
- New methods: `socialConnectLink()` and `socialConnectLinkList()` have been added to handle social account connections.
- `addReCaptcha()`: New method to simplify adding ReCaptcha to forms.

## Magic Link (One-Time Login)

Note that the **Magic Link** (One-Time Login) feature, which was present in some 13.x versions, was temporarily removed or refactored in 14.0 and later reintroduced in 15.0. If you were using this feature in a customized way in 12.x, please plan your upgrade accordingly.
