WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/14/2018 01:44:50 PM (6 years ago)
Author:
johnbillion
Message:

Docs: Correct and improve docblocks for user session management functionality.

See #42505

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-session-tokens.php

    r42746 r43643  
    2424
    2525    /**
    26      * Protected constructor.
     26     * Protected constructor. Use the `get_instance()` method to get the instance.
    2727     *
    2828     * @since 4.0.0
    … …  
    3535
    3636    /**
    37      * Retrieves a session token manager instance for a user.
     37     * Retrieves a session manager instance for a user.
    3838     *
    3939     * This method contains a {@see 'session_token_manager'} filter, allowing a plugin to swap out
    … …  
    4343     *
    4444     * @param int $user_id User whose session to manage.
    45      * @return WP_User_Meta_Session_Tokens WP_User_Meta_Session_Tokens class instance by default.
     45     * @return WP_Session_Tokens The session object, which is by default an instance of
     46     *                           the `WP_User_Meta_Session_Tokens` class.
    4647     */
    4748    final public static function get_instance( $user_id ) {
    4849        /**
    49          * Filters the session token manager used.
     50         * Filters the class name for the session token manager.
    5051         *
    5152         * @since 4.0.0
    … …  
    5960
    6061    /**
    61      * Hashes a session token for storage.
     62     * Hashes the given session token for storage.
    6263     *
    6364     * @since 4.0.0
    … …  
    7677
    7778    /**
    78      * Get a user's session.
    79      *
    80      * @since 4.0.0
    81      *
    82      * @param string $token Session token
    83      * @return array User session
     79     * Retrieves a user's session for the given token.
     80     *
     81     * @since 4.0.0
     82     *
     83     * @param string $token Session token.
     84     * @return array|null The session, or null if it does not exist.
    8485     */
    8586    final public function get( $token ) {
    … …  
    8990
    9091    /**
    91      * Validate a user's session token as authentic.
     92     * Validates the given session token for authenticity and validity.
    9293     *
    9394     * Checks that the given token is present and hasn't expired.
    … …  
    104105
    105106    /**
    106      * Generate a session token and attach session information to it.
     107     * Generates a session token and attaches session information to it.
    107108     *
    108109     * A session token is a long, random string. It is used in a cookie
    109      * link that cookie to an expiration time and to ensure the cookie
    110      * becomes invalidated upon logout.
     110     * to link that cookie to an expiration time and to ensure the cookie
     111     * becomes invalidated when the user logs out.
    111112     *
    112113     * This function generates a token and stores it with the associated
    … …  
    123124         * Filters the information attached to the newly created session.
    124125         *
    125          * Could be used in the future to attach information such as
    126          * IP address or user agent to a session.
     126         * Can be used to attach further information to a session.
    127127         *
    128128         * @since 4.0.0
    … …  
    155155
    156156    /**
    157      * Update a session token.
     157     * Updates the data for the session with the given token.
    158158     *
    159159     * @since 4.0.0
    … …  
    168168
    169169    /**
    170      * Destroy a session token.
     170     * Destroys the session with the given token.
    171171     *
    172172     * @since 4.0.0
    … …  
    180180
    181181    /**
    182      * Destroy all session tokens for this user,
    183      * except a single token, presumably the one in use.
     182     * Destroys all sessions for this user except the one with the given token (presumably the one in use).
    184183     *
    185184     * @since 4.0.0
    … …  
    198197
    199198    /**
    200      * Determine whether a session token is still valid,
    201      * based on expiration.
     199     * Determines whether a session is still valid, based on its expiration timestamp.
    202200     *
    203201     * @since 4.0.0
    … …  
    211209
    212210    /**
    213      * Destroy all session tokens for a user.
     211     * Destroys all sessions for a user.
    214212     *
    215213     * @since 4.0.0
    … …  
    220218
    221219    /**
    222      * Destroy all session tokens for all users.
     220     * Destroys all sessions for all users.
    223221     *
    224222     * @since 4.0.0
    … …  
    231229
    232230    /**
    233      * Retrieve all sessions of a user.
    234      *
    235      * @since 4.0.0
    236      *
    237      * @return array Sessions of a user.
     231     * Retrieves all sessions for a user.
     232     *
     233     * @since 4.0.0
     234     *
     235     * @return array Sessions for a user.
    238236     */
    239237    final public function get_all() {
    … …  
    242240
    243241    /**
    244      * This method should retrieve all sessions of a user, keyed by verifier.
    245      *
    246      * @since 4.0.0
    247      *
    248      * @return array Sessions of a user, keyed by verifier.
     242     * Retrieves all sessions of the user.
     243     *
     244     * @since 4.0.0
     245     *
     246     * @return array Sessions of the user.
    249247     */
    250248    abstract protected function get_sessions();
    251249
    252250    /**
    253      * This method should look up a session by its verifier (token hash).
    254      *
    255      * @since 4.0.0
    256      *
    257      * @param string $verifier Verifier of the session to retrieve.
     251     * Retrieves a session based on its verifier (token hash).
     252     *
     253     * @since 4.0.0
     254     *
     255     * @param string $verifier Verifier for the session to retrieve.
    258256     * @return array|null The session, or null if it does not exist.
    259257     */
    … …  
    261259
    262260    /**
    263      * This method should update a session by its verifier.
    264      *
    265      * Omitting the second argument should destroy the session.
    266      *
    267      * @since 4.0.0
    268      *
    269      * @param string $verifier Verifier of the session to update.
     261     * Updates a session based on its verifier (token hash).
     262     *
     263     * Omitting the second argument destroys the session.
     264     *
     265     * @since 4.0.0
     266     *
     267     * @param string $verifier Verifier for the session to update.
    270268     * @param array  $session  Optional. Session. Omitting this argument destroys the session.
    271269     */
    … …  
    273271
    274272    /**
    275      * This method should destroy all session tokens for this user,
    276      * except a single session passed.
     273     * Destroys all sessions for this user, except the single session with the given verifier.
    277274     *
    278275     * @since 4.0.0
    … …  
    283280
    284281    /**
    285      * This method should destroy all sessions for a user.
     282     * Destroys all sessions for the user.
    286283     *
    287284     * @since 4.0.0
    … …  
    290287
    291288    /**
    292      * This static method should destroy all session tokens for all users.
     289     * Destroys all sessions for all users.
    293290     *
    294291     * @since 4.0.0
Note: See TracChangeset for help on using the changeset viewer.