Add validateEmailConfirmationFromRequest method

src/VerifyEmailHelperInterface.php

@@ -65,4 +65,32 @@ public function generateSignature(string $routeName, string $userId, string $use
      * @throws VerifyEmailExceptionInterface
      */
     public function validateEmailConfirmation(string $signedUrl, string $userId, string $userEmail): void;
+
+    /**
+     * Validate a signed an email confirmation request.
+     *
+     * If something is wrong with the email confirmation, a
+     * VerifyEmailExceptionInterface will be thrown.
+     *
+     * The $userEmail should be the email address that the currently-authenticated
+     * user is trying to get validated. This is usually the current user's
+     * email address.
+     *
+     * In more a complex setup, where you allow a user to verify multiple
+     * emails, this would be the email that the currently-authenticated user
+     * is trying to validate. You may even store a user's many email addresses
+     * (and whether or not each is verified) in another database table. In
+     * that case, you would need to call this method with each unverified
+     * email in that table (for the currently-authenticated user) to see if
+     * the signature is valid for any of the email addresses. If you find the
+     * one that is valid, you could then mark that email as "confirmed".
+     *
+     * @param Request $request the currentRequest
+     * @param string $userId    currently-authenticated user's unique identifier
+     * @param string $userEmail currently-authenticated user's email, or, more specifically,
+     *                          the email that the current user is attempting to validate
+     *
+     * @throws VerifyEmailExceptionInterface
+     */
+    public function validateEmailConfirmationFromRequest(Request $request, string $userId, string $userEmail): void;
 }