diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-callback-after-create.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-callback-after-create.php index d02d9a3070..9b00e7279a 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-callback-after-create.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-callback-after-create.php @@ -1,12 +1,28 @@ callback = $callback; } + /** + * Calls the set callback on given object. + * + * @param mixed $object The object to apply the callback on. + * + * @return mixed The possibly altered object. + */ function call( $object ) { return call_user_func( $this->callback, $object ); } diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php index 7e12d5ae88..d9072fcb9d 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php @@ -12,7 +12,9 @@ class WP_UnitTest_Factory_For_Attachment extends WP_UnitTest_Factory_For_Post { * @type string $file Path of the attached file. * } * @param int $legacy_parent Deprecated. - * @param array $legacy_args Deprecated + * @param array $legacy_args Deprecated. + * + * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. */ function create_object( $args, $legacy_parent = 0, $legacy_args = array() ) { // Backward compatibility for legacy argument format. @@ -34,6 +36,14 @@ class WP_UnitTest_Factory_For_Attachment extends WP_UnitTest_Factory_For_Post { return wp_insert_attachment( $r, $r['file'], $r['post_parent'] ); } + /** + * Saves an attachment. + * + * @param string $file The file name to create attachment object for. + * @param int $parent The post id to attach the file to. + * + * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. + */ function create_upload_object( $file, $parent = 0 ) { $contents = file_get_contents( $file ); $upload = wp_upload_bits( basename( $file ), null, $contents ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php index f78416196b..5a5b5d3718 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php @@ -23,6 +23,13 @@ class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing { ); } + /** + * Creates a blog object. + * + * @param array $args Arguments for the site object. + * + * @return int|WP_Error Returns WP_Error object on failure, the site ID on success. + */ function create_object( $args ) { global $wpdb; $meta = isset( $args['meta'] ) ? $args['meta'] : array( 'public' => 1 ); @@ -38,8 +45,23 @@ class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing { return $blog; } + /** + * Updates a blog object. Not implemented. + * + * @param int $blog_id The blog id to update. + * @param array $fields The fields to update. + * + * @return void + */ function update_object( $blog_id, $fields ) {} + /** + * Retrieves a site by given blog id. + * + * @param int $blog_id The blog id to retrieve. + * + * @return null|WP_Site The site object or null if not found. + */ function get_object_by_id( $blog_id ) { return get_site( $blog_id ); } diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php index 87294bc1ae..4ca3b2fd6d 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php @@ -22,20 +22,52 @@ class WP_UnitTest_Factory_For_Comment extends WP_UnitTest_Factory_For_Thing { ); } + /** + * Inserts a comment. + * + * @param array $args The comment details. + * + * @return false|int The comment's ID on success, false on failure. + */ function create_object( $args ) { return wp_insert_comment( $this->addslashes_deep( $args ) ); } + /** + * Updates a comment. + * + * @param int $comment_id The comment id. + * @param array $fields The comment details. + * + * @return int When updated 1, not update 0. + */ function update_object( $comment_id, $fields ) { $fields['comment_ID'] = $comment_id; return wp_update_comment( $this->addslashes_deep( $fields ) ); } + /** + * Creates multiple comments on given post. + * + * @param int $post_id The post id to create comments for. + * @param int $count Total amount of comments to create. + * @param array $args The comment details. + * @param null $generation_definitions Default values. + * + * @return int[] Array with the comment ids. + */ function create_post_comments( $post_id, $count = 1, $args = array(), $generation_definitions = null ) { $args['comment_post_ID'] = $post_id; return $this->create_many( $count, $args, $generation_definitions ); } + /** + * Returns a comment. + * + * @param int $comment_id The comment id. + * + * @return null|WP_Comment WP_Comment when found, null when not found. + */ function get_object_by_id( $comment_id ) { return get_comment( $comment_id ); } diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php index 105f99171a..e56ca0f191 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php @@ -23,15 +23,37 @@ class WP_UnitTest_Factory_For_Post extends WP_UnitTest_Factory_For_Thing { ); } + /** + * Creates a post object. + * + * @param array $args Array with elements for the post. + * + * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure. + */ function create_object( $args ) { return wp_insert_post( $args ); } + /** + * Updates an existing post object. + * + * @param int $post_id The post id to update. + * @param array $fields Post data. + * + * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success. + */ function update_object( $post_id, $fields ) { $fields['ID'] = $post_id; return wp_update_post( $fields ); } + /** + * Retrieves a object by an id. + * + * @param int $post_id The post id to update. + * + * @return null|WP_Post WP_Post on success or null on failure. + */ function get_object_by_id( $post_id ) { return get_post( $post_id ); } diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php index 449022ff69..76c1aac14b 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php @@ -24,6 +24,13 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { ); } + /** + * Creates a term object. + * + * @param array $args Array or string of arguments for inserting a term. + * + * @return array|WP_Error + */ function create_object( $args ) { $args = array_merge( array( 'taxonomy' => $this->taxonomy ), $args ); $term_id_pair = wp_insert_term( $args['name'], $args['taxonomy'], $args ); @@ -33,6 +40,14 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { return $term_id_pair['term_id']; } + /** + * Updates the term. + * + * @param int|object $term The term to update. + * @param array|string $fields The context in which to relate the term to the object. + * + * @return int The term id. + */ function update_object( $term, $fields ) { $fields = array_merge( array( 'taxonomy' => $this->taxonomy ), $fields ); if ( is_object( $term ) ) { @@ -42,12 +57,31 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { return $term_id_pair['term_id']; } + /** + * Attach terms on the given post. + * + * @param int $post_id The Post ID. + * @param string|array $terms An array of terms to set for the post, or a string of terms + * separated by commas. Hierarchical taxonomies must always pass IDs rather + * than names so that children with the same names but different parents + * aren't confused. + * @param string $taxonomy Taxonomy name. + * @param bool $append Optional. If true, don't delete existing terms, just add on. If false, + * replace the terms with the new terms. Default true. + * + * @return array|false|WP_Error Array of term taxonomy IDs of affected terms. WP_Error or false on failure. + */ function add_post_terms( $post_id, $terms, $taxonomy, $append = true ) { return wp_set_post_terms( $post_id, $terms, $taxonomy, $append ); } /** - * @return array|null|WP_Error|WP_Term + * Create a term and returns it as a object. + * + * @param array $args Array or string of arguments for inserting a term. + * @param null $generation_definitions The default values. + * + * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. */ function create_and_get( $args = array(), $generation_definitions = null ) { $term_id = $this->create( $args, $generation_definitions ); @@ -55,6 +89,13 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { return get_term( $term_id, $taxonomy ); } + /** + * Retrieves the term by given term id. + * + * @param int $term_id The term id to retrieve. + * + * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. + */ function get_object_by_id( $term_id ) { return get_term( $term_id, $this->taxonomy ); } diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php index 7ec51e78c0..5ae495967d 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php @@ -21,9 +21,33 @@ abstract class WP_UnitTest_Factory_For_Thing { $this->default_generation_definitions = $default_generation_definitions; } + /** + * Creates an object. + * + * @param array $args The arguments. + * + * @return mixed The result. Can be anything. + */ abstract function create_object( $args ); + + /** + * Updates an existing object. + * + * @param int $object The object id. + * @param array $fields The values to update. + * + * @return mixed The result. Can be anything. + */ abstract function update_object( $object, $fields ); + /** + * Creates an object. + * + * @param array $args Optional. The arguments for the object to create. Default is empty array. + * @param null $generation_definitions Optional. The default values for the object. Default is null. + * + * @return mixed The result. Can be anything. + */ function create( $args = array(), $generation_definitions = null ) { if ( is_null( $generation_definitions ) ) { $generation_definitions = $this->default_generation_definitions; @@ -45,13 +69,37 @@ abstract class WP_UnitTest_Factory_For_Thing { return $created; } + /** + * Creates an object and returns its object. + * + * @param array $args Optional. The arguments for the object to create. Default is empty array. + * @param null $generation_definitions Optional. The default values for the object. Default is null. + * + * @return mixed The created object. Can be anything. + */ function create_and_get( $args = array(), $generation_definitions = null ) { $object_id = $this->create( $args, $generation_definitions ); return $this->get_object_by_id( $object_id ); } + /** + * Retrieves an object by ID. + * + * @param int $object_id The object id. + * + * @return mixed The object. Can be anything. + */ abstract function get_object_by_id( $object_id ); + /** + * Creates multiple objects. + * + * @param int $count Amount of objects to create. + * @param array $args Optional. The arguments for the object to create. Default is empty array. + * @param null $generation_definitions Optional. The default values for the object. Default is null. + * + * @return array + */ function create_many( $count, $args = array(), $generation_definitions = null ) { $results = array(); for ( $i = 0; $i < $count; $i++ ) { @@ -60,6 +108,16 @@ abstract class WP_UnitTest_Factory_For_Thing { return $results; } + /** + * Combines the given argument with the generation_definitions (defaults) and applies + * possibly set callbacks on it. + * + * @param array $args Optional. The arguments to combine with defaults. Default is empty array. + * @param array|null $generation_definitions Optional. The defaults. Default is null. + * @param array|null $callbacks Optional. Array with callbacks to apply on the fields. Default is null. + * + * @return array|WP_Error Combined array on success. WP_Error when default value is incorrent. + */ function generate_args( $args = array(), $generation_definitions = null, &$callbacks = null ) { $callbacks = array(); if ( is_null( $generation_definitions ) ) { @@ -88,18 +146,42 @@ abstract class WP_UnitTest_Factory_For_Thing { return $args; } + + /** + * Applies the callbacks on the created object. + * + * @param WP_UnitTest_Factory_Callback_After_Create[] $callbacks Array with callback functions. + * @param mixed $created The object to apply callbacks for. + * + * @return array The altered fields. + */ function apply_callbacks( $callbacks, $created ) { $updated_fields = array(); + foreach ( $callbacks as $field_name => $generator ) { $updated_fields[ $field_name ] = $generator->call( $created ); } return $updated_fields; } + /** + * Instantiates a callback objects for the given function name. + * + * @param string $function The callback function. + * + * @return WP_UnitTest_Factory_Callback_After_Create + */ function callback( $function ) { return new WP_UnitTest_Factory_Callback_After_Create( $function ); } + /** + * Adds slashes to the given value. + * + * @param array|object|string|mixed $value The value to add slashes to. + * + * @return array|string The value with the possibly applied slashes. + */ function addslashes_deep( $value ) { if ( is_array( $value ) ) { $value = array_map( array( $this, 'addslashes_deep' ), $value ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php index e2e2564b8c..2b32a33c09 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php @@ -21,15 +21,37 @@ class WP_UnitTest_Factory_For_User extends WP_UnitTest_Factory_For_Thing { ); } + /** + * Inserts an user. + * + * @param array $args The user data to insert. + * + * @return int|WP_Error + */ function create_object( $args ) { return wp_insert_user( $args ); } + /** + * Updates the user data. + * + * @param int $user_id The user id to update. + * @param array $fields The user data to update. + * + * @return int|WP_Error User id on success. WP_Error on failure. + */ function update_object( $user_id, $fields ) { $fields['ID'] = $user_id; return wp_update_user( $fields ); } + /** + * Retrieves the user for given user id. + * + * @param int $user_id The user id to get. + * + * @return WP_User The user. + */ function get_object_by_id( $user_id ) { return new WP_User( $user_id ); }