Provide a public PHP interface to initiate a password reset and deprecate _user_mail_notify() password op

Problem/Motivation

_user_mail_notify() is an internal, underscore-prefixed function. Still it is widely used in contrib and likely in custom modules. Some research in #3539178-27: Extract _user_mail_notify() into a user NotificationHandler → turned out a non-exhaustive list of modules which for various reasons attempt to send a password reset email.

Some modules dealing with password resets:

• https://www.drupal.org/project/admin_password_reset →
• https://www.drupal.org/project/diba_security_policy →
• https://www.drupal.org/project/eep →
• https://www.drupal.org/project/login_emailusername →
• https://www.drupal.org/project/login_flow →
• https://www.drupal.org/project/mass_password_change →
• https://www.drupal.org/project/mass_pwreset →
• https://www.drupal.org/project/openstory →
• https://www.drupal.org/project/pass_reset_checkbox →
• https://www.drupal.org/project/passwordless →
• https://www.drupal.org/project/patreon →
• https://www.drupal.org/project/rest_password →
• https://www.drupal.org/project/rest_register_verify_email →
• https://www.drupal.org/project/secure_password_reset →
• https://www.drupal.org/project/social →

Steps to reproduce

Proposed resolution

Expose a public API for initiating a password reset for a particular account. A call to this API should result in a password reset email sent to the address registered with that account.

This could be part of the UserInterface:

/**
  * Returns TRUE if a password reset can be initiated on this account.
  */
public function isPasswordResetEnabled(): bool;

/**
  * Initiate a password reset for the user.
  *
  * Returns TRUE if a password reset message was sent to the owner of this account.
  */
public function initiatePasswordReset(): bool;

Deprecate the password_reset op of _user_mail_notify().

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet