WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/14/2018 01:44:50 PM (8 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.