WordPress.org
Get WordPress

Make WordPress Core

Changeset 44497


Ignore:
Timestamp:
01/09/2019 05:43:14 AM (6 years ago)
Author:
pento
Message:

Docs: Add docblocks for the PHPUnit factory objects.

Props andizer.
Fixes #44521.

Location:
trunk/tests/phpunit/includes/factory
Files:
8 edited

Legend:

Unmodified
Added
Removed

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-callback-after-create.php

    r36347 r44497  
    22
    33class WP_UnitTest_Factory_Callback_After_Create {
     4
     5    /**
     6     * @var callable
     7     */
    48    var $callback;
    59
     10    /**
     11     * WP_UnitTest_Factory_Callback_After_Create constructor.
     12     *
     13     * @param callable $callback A callback function.
     14     */
    615    function __construct( $callback ) {
    716        $this->callback = $callback;
    817    }
    918
     19    /**
     20     * Calls the set callback on given object.
     21     *
     22     * @param mixed $object The object to apply the callback on.
     23     *
     24     * @return mixed The possibly altered object.
     25     */
    1026    function call( $object ) {
    1127        return call_user_func( $this->callback, $object );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php

    r43571 r44497  
    1313     * }
    1414     * @param int   $legacy_parent Deprecated.
    15      * @param array $legacy_args   Deprecated
     15     * @param array $legacy_args   Deprecated.
     16     *
     17     * @return  int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure.
    1618     */
    1719    function create_object( $args, $legacy_parent = 0, $legacy_args = array() ) {
    … …  
    3537    }
    3638
     39    /**
     40     * Saves an attachment.
     41     *
     42     * @param string $file   The file name to create attachment object for.
     43     * @param int    $parent The post id to attach the file to.
     44     *
     45     * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure.
     46     */
    3747    function create_upload_object( $file, $parent = 0 ) {
    3848        $contents = file_get_contents( $file );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php

    r42343 r44497  
    2424    }
    2525
     26    /**
     27     * Creates a blog object.
     28     *
     29     * @param array $args Arguments for the site object.
     30     *
     31     * @return int|WP_Error Returns WP_Error object on failure, the site ID on success.
     32     */
    2633    function create_object( $args ) {
    2734        global $wpdb;
    … …  
    3946    }
    4047
     48    /**
     49     * Updates a blog object. Not implemented.
     50     *
     51     * @param int   $blog_id The blog id to update.
     52     * @param array $fields  The fields to update.
     53     *
     54     * @return void
     55     */
    4156    function update_object( $blog_id, $fields ) {}
    4257
     58    /**
     59     * Retrieves a site by given blog id.
     60     *
     61     * @param int $blog_id The blog id to retrieve.
     62     *
     63     * @return null|WP_Site The site object or null if not found.
     64     */
    4365    function get_object_by_id( $blog_id ) {
    4466        return get_site( $blog_id );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php

    r42343 r44497  
    2323    }
    2424
     25    /**
     26     * Inserts a comment.
     27     *
     28     * @param array $args The comment details.
     29     *
     30     * @return false|int The comment's ID on success, false on failure.
     31     */
    2532    function create_object( $args ) {
    2633        return wp_insert_comment( $this->addslashes_deep( $args ) );
    2734    }
    2835
     36    /**
     37     * Updates a comment.
     38     *
     39     * @param int   $comment_id The comment id.
     40     * @param array $fields     The comment details.
     41     *
     42     * @return int When updated 1, not update 0.
     43     */
    2944    function update_object( $comment_id, $fields ) {
    3045        $fields['comment_ID'] = $comment_id;
    … …  
    3247    }
    3348
     49    /**
     50     * Creates multiple comments on given post.
     51     *
     52     * @param int   $post_id                The post id to create comments for.
     53     * @param int   $count                  Total amount of comments to create.
     54     * @param array $args                   The comment details.
     55     * @param null  $generation_definitions Default values.
     56     *
     57     * @return int[] Array with the comment ids.
     58     */
    3459    function create_post_comments( $post_id, $count = 1, $args = array(), $generation_definitions = null ) {
    3560        $args['comment_post_ID'] = $post_id;
    … …  
    3762    }
    3863
     64    /**
     65     * Returns a comment.
     66     *
     67     * @param int $comment_id The comment id.
     68     *
     69     * @return null|WP_Comment WP_Comment when found, null when not found.
     70     */
    3971    function get_object_by_id( $comment_id ) {
    4072        return get_comment( $comment_id );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php

    r42343 r44497  
    2424    }
    2525
     26    /**
     27     * Creates a post object.
     28     *
     29     * @param array $args Array with elements for the post.
     30     *
     31     * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure.
     32     */
    2633    function create_object( $args ) {
    2734        return wp_insert_post( $args );
    2835    }
    2936
     37    /**
     38     * Updates an existing post object.
     39     *
     40     * @param int   $post_id The post id to update.
     41     * @param array $fields  Post data.
     42     *
     43     * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success.
     44     */
    3045    function update_object( $post_id, $fields ) {
    3146        $fields['ID'] = $post_id;
    … …  
    3348    }
    3449
     50    /**
     51     * Retrieves a object by an id.
     52     *
     53     * @param int   $post_id The post id to update.
     54     *
     55     * @return null|WP_Post WP_Post on success or null on failure.
     56     */
    3557    function get_object_by_id( $post_id ) {
    3658        return get_post( $post_id );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php

    r42343 r44497  
    2525    }
    2626
     27    /**
     28     * Creates a term object.
     29     *
     30     * @param array $args Array or string of arguments for inserting a term.
     31     *
     32     * @return array|WP_Error
     33     */
    2734    function create_object( $args ) {
    2835        $args         = array_merge( array( 'taxonomy' => $this->taxonomy ), $args );
    … …  
    3441    }
    3542
     43    /**
     44     * Updates the term.
     45     *
     46     * @param int|object   $term   The term to update.
     47     * @param array|string $fields The context in which to relate the term to the object.
     48     *
     49     * @return int The term id.
     50     */
    3651    function update_object( $term, $fields ) {
    3752        $fields = array_merge( array( 'taxonomy' => $this->taxonomy ), $fields );
    … …  
    4358    }
    4459
     60    /**
     61     * Attach terms on the given post.
     62     *
     63     * @param int          $post_id  The Post ID.
     64     * @param string|array $terms    An array of terms to set for the post, or a string of terms
     65     *                               separated by commas. Hierarchical taxonomies must always pass IDs rather
     66     *                               than names so that children with the same names but different parents
     67     *                               aren't confused.
     68     * @param string       $taxonomy Taxonomy name.
     69     * @param bool         $append   Optional. If true, don't delete existing terms, just add on. If false,
     70     *                               replace the terms with the new terms. Default true.
     71     *
     72     * @return array|false|WP_Error Array of term taxonomy IDs of affected terms. WP_Error or false on failure.
     73     */
    4574    function add_post_terms( $post_id, $terms, $taxonomy, $append = true ) {
    4675        return wp_set_post_terms( $post_id, $terms, $taxonomy, $append );
    … …  
    4877
    4978    /**
    50      * @return array|null|WP_Error|WP_Term
     79     * Create a term and returns it as a object.
     80     *
     81     * @param array $args                   Array or string of arguments for inserting a term.
     82     * @param null  $generation_definitions The default values.
     83     *
     84     * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure.
    5185     */
    5286    function create_and_get( $args = array(), $generation_definitions = null ) {
    … …  
    5690    }
    5791
     92    /**
     93     * Retrieves the term by given term id.
     94     *
     95     * @param int $term_id The term id to retrieve.
     96     *
     97     * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure.
     98     */
    5899    function get_object_by_id( $term_id ) {
    59100        return get_term( $term_id, $this->taxonomy );

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php

    r42343 r44497  
    2222    }
    2323
     24    /**
     25     * Creates an object.
     26     *
     27     * @param array $args The arguments.
     28     *
     29     * @return mixed The result. Can be anything.
     30     */
    2431    abstract function create_object( $args );
     32
     33    /**
     34     * Updates an existing object.
     35     *
     36     * @param int   $object The object id.
     37     * @param array $fields The values to update.
     38     *
     39     * @return mixed The result. Can be anything.
     40     */
    2541    abstract function update_object( $object, $fields );
    2642
     43    /**
     44     * Creates an object.
     45     *
     46     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
     47     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
     48     *
     49     * @return mixed The result. Can be anything.
     50     */
    2751    function create( $args = array(), $generation_definitions = null ) {
    2852        if ( is_null( $generation_definitions ) ) {
    … …  
    4670    }
    4771
     72    /**
     73     * Creates an object and returns its object.
     74     *
     75     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
     76     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
     77     *
     78     * @return mixed The created object. Can be anything.
     79     */
    4880    function create_and_get( $args = array(), $generation_definitions = null ) {
    4981        $object_id = $this->create( $args, $generation_definitions );
    … …  
    5183    }
    5284
     85    /**
     86     * Retrieves an object by ID.
     87     *
     88     * @param int $object_id The object id.
     89     *
     90     * @return mixed The object. Can be anything.
     91     */
    5392    abstract function get_object_by_id( $object_id );
    5493
     94    /**
     95     * Creates multiple objects.
     96     *
     97     * @param int   $count                  Amount of objects to create.
     98     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
     99     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
     100     *
     101     * @return array
     102     */
    55103    function create_many( $count, $args = array(), $generation_definitions = null ) {
    56104        $results = array();
    … …  
    61109    }
    62110
     111    /**
     112     * Combines the given argument with the generation_definitions (defaults) and applies
     113     * possibly set callbacks on it.
     114     *
     115     * @param array       $args                   Optional. The arguments to combine with defaults. Default is empty array.
     116     * @param array|null  $generation_definitions Optional. The defaults. Default is null.
     117     * @param array|null  $callbacks              Optional. Array with callbacks to apply on the fields. Default is null.
     118     *
     119     * @return array|WP_Error Combined array on success. WP_Error when default value is incorrent.
     120     */
    63121    function generate_args( $args = array(), $generation_definitions = null, &$callbacks = null ) {
    64122        $callbacks = array();
    … …  
    89147    }
    90148
     149
     150    /**
     151     * Applies the callbacks on the created object.
     152     *
     153     * @param WP_UnitTest_Factory_Callback_After_Create[] $callbacks Array with callback functions.
     154     * @param mixed                                       $created   The object to apply callbacks for.
     155     *
     156     * @return array The altered fields.
     157     */
    91158    function apply_callbacks( $callbacks, $created ) {
    92159        $updated_fields = array();
     160
    93161        foreach ( $callbacks as $field_name => $generator ) {
    94162            $updated_fields[ $field_name ] = $generator->call( $created );
    … …  
    97165    }
    98166
     167    /**
     168     * Instantiates a callback objects for the given function name.
     169     *
     170     * @param string $function The callback function.
     171     *
     172     * @return WP_UnitTest_Factory_Callback_After_Create
     173     */
    99174    function callback( $function ) {
    100175        return new WP_UnitTest_Factory_Callback_After_Create( $function );
    101176    }
    102177
     178    /**
     179     * Adds slashes to the given value.
     180     *
     181     * @param array|object|string|mixed $value The value to add slashes to.
     182     *
     183     * @return array|string The value with the possibly applied slashes.
     184     */
    103185    function addslashes_deep( $value ) {
    104186        if ( is_array( $value ) ) {

  • trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php

    r42343 r44497  
    2222    }
    2323
     24    /**
     25     * Inserts an user.
     26     *
     27     * @param array $args The user data to insert.
     28     *
     29     * @return int|WP_Error
     30     */
    2431    function create_object( $args ) {
    2532        return wp_insert_user( $args );
    2633    }
    2734
     35    /**
     36     * Updates the user data.
     37     *
     38     * @param int   $user_id The user id to update.
     39     * @param array $fields  The user data to update.
     40     *
     41     * @return int|WP_Error User id on success. WP_Error on failure.
     42     */
    2843    function update_object( $user_id, $fields ) {
    2944        $fields['ID'] = $user_id;
    … …  
    3146    }
    3247
     48    /**
     49     * Retrieves the user for given user id.
     50     *
     51     * @param int $user_id The user id to get.
     52     *
     53     * @return WP_User The user.
     54     */
    3355    function get_object_by_id( $user_id ) {
    3456        return new WP_User( $user_id );
Note: See TracChangeset for help on using the changeset viewer.