Issue #2188289 by Jaypan, sun, jibran, Berdir: fix up docs for token functions and methods in regards to anonymous users and sessions

core/includes/common.inc

@@ -3010,6 +3010,11 @@ function drupal_get_private_key() {
  * @param string $value
  *   An additional value to base the token on.
  *
+ * The generated token is based on the session ID of the current user. Normally,
+ * anonymous users do not have a session, so the generated token will be
+ * different on every page request. To generate a token for users without a
+ * session, manually start a session prior to calling this function.
+ *
  * @return string
  *   A 43-character URL-safe token for validation, based on the user session ID,
  *   the hash salt provided from drupal_get_hash_salt(), and the
@@ -3017,6 +3022,7 @@ function drupal_get_private_key() {
  *
  * @see drupal_get_hash_salt()
  * @see \Drupal\Core\Access\CsrfTokenManager
+ * @see drupal_session_start()
  *
  * @deprecated as of Drupal 8.0. Use the csrf_token service instead.
  */

core/lib/Drupal.php

@@ -561,8 +561,15 @@ class Drupal {
   /**
    * Returns the CSRF token manager service.
    *
+   * The generated token is based on the session ID of the current user. Normally,
+   * anonymous users do not have a session, so the generated token will be
+   * different on every page request. To generate a token for users without a
+   * session, manually start a session prior to calling this function.
+   *
    * @return \Drupal\Core\Access\CsrfTokenGenerator
    *   The CSRF token manager.
+   *
+   * @see drupal_session_start()
    */
   public static function csrfToken() {
     return static::$container->get('csrf_token');

core/lib/Drupal/Core/Access/CsrfTokenGenerator.php

@@ -55,6 +55,11 @@ class CsrfTokenGenerator {
   /**
    * Generates a token based on $value, the user session, and the private key.
    *
+   * The generated token is based on the session ID of the current user. Normally,
+   * anonymous users do not have a session, so the generated token will be
+   * different on every page request. To generate a token for users without a
+   * session, manually start a session prior to calling this function.
+   *
    * @param string $value
    *   (optional) An additional value to base the token on.
    *
@@ -64,6 +69,7 @@ class CsrfTokenGenerator {
    *   'drupal_private_key' configuration variable.
    *
    * @see drupal_get_hash_salt()
+   * @see drupal_session_start()
    */
   public function get($value = '') {
     return Crypt::hmacBase64($value, session_id() . $this->privateKey->get() . drupal_get_hash_salt());