# Migration Guide from 14.x to 15.0

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

## Database Migration

This version introduces the **Magic Link** (One-Time Login) feature, which requires new columns in the `users` table. You must run the migrations to update your database schema.

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

The migration adds the following columns to the `users` table:
- `login_token` (string, 32)
- `login_token_date` (datetime)
- `token_send_requested` (boolean)

## Dependency Changes

Several dependencies have been updated. If you have these in your `composer.json`, ensure they are updated:

- `cakedc/auth` has been updated to `^10.1`.
- `robthree/twofactorauth` now supports `^3.0 || ^2.0`.
- `endroid/qr-code` now supports `^6.0 || ^5.0`.

## Configuration Changes

### 2FA QR Code Provider

The default configuration for the 2FA QR code provider has been updated to automatically use `EndroidQrCodeProvider` if the `endroid/qr-code` package is installed.

In your `config/users.php`:

```php
'TwoFactor' => [
    // ...
    // Now defaults to EndroidQrCodeProvider if available
    'qrcodeprovider' => class_exists('\RobThree\Auth\Providers\Qr\EndroidQrCodeProvider') ? (new \RobThree\Auth\Providers\Qr\EndroidQrCodeProvider()) : null,
],
```

### Magic Link (One-Time Login)

The Magic Link feature is enabled by default. If you want to customize or disable it, you can add the following to your `config/users.php`:

```php
'OneTimeLogin' => [
    'enabled' => true,
    'tokenLifeTime' => 600, // 10 minutes
    'DeliveryHandlers' => [
        'Email' => [
            'className' => \CakeDC\Users\Model\Behavior\OneTimeDelivery\EmailDelivery::class
        ],
    ],
],
```

And update your `Auth` configuration to include the `OneTimeToken` authenticator:

```php
'Auth' => [
    'Authenticators' => [
        // ...
        'OneTimeToken' => [
            'className' => 'CakeDC/Auth.OneTimeToken',
            'skipTwoFactorVerify' => true,
            'loginUrl' => [
                '/login',
            ],
        ]
    ],
]
```

## Internal Changes

### UsersController and RegisterBehavior

- The `UsersController` now uses the `OneTimeTokenTrait` to support the Magic Link feature.
- The `RegisterBehavior::buildValidator()` method has been updated to call `validationDefault()` before applying registration-specific validation. This ensures that any default validation rules (like field length or types) are also applied during registration.

### Validation Rule Names

Several validation rule names have been simplified across `UsersTable` and `SocialAccountsTable`. If you were relying on specific rule names to remove or modify them in your application, please note that many names like `valid_user_token_expires`, `valid_activation_date`, `valid_tos_date`, `valid_id`, etc., have been changed to simply `valid`.

### Password Meter Configuration

The `UserHelper` now uses `Users.passwordMinLength` instead of `Users.passwordMeter.pswMinLength` for the password meter's minimum length. If you had customized this value, please update your configuration.

```php
// Change this
// Configure::write('Users.passwordMeter.pswMinLength', 10);
// To this
Configure::write('Users.passwordMinLength', 10);
```

### UsersController

If you have overridden `UsersController`, note that it now uses the `OneTimeTokenTrait`. Ensure your custom controller remains compatible if you are overriding `initialize` or other core methods.
