Index: src/wp-includes/post.php
===================================================================
--- src/wp-includes/post.php (revision 25628)
+++ src/wp-includes/post.php (working copy)
@@ -189,6 +189,15 @@
$file = $uploads['basedir'] . "/$file";
if ( $unfiltered )
return $file;
+
+ /**
+ * Filter the returned file path to an attached file.
+ *
+ * @since 2.1.0
+ *
+ * @param string $file Path to the attached file.
+ * @param int $attachment_id The attachment ID.
+ */
return apply_filters( 'get_attached_file', $file, $attachment_id );
}
@@ -199,7 +208,6 @@
* '_wp_attached_file' to store the path of the attachment.
*
* @since 2.1.0
- * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID.
*
* @param int $attachment_id Attachment ID
* @param string $file File path for the attachment
@@ -209,6 +217,14 @@
if ( !get_post( $attachment_id ) )
return false;
+ /**
+ * Filter the updated path to a file attached to a post.
+ *
+ * @since 2.1.0
+ *
+ * @param string $file Updated path to the file.
+ * @param int $attachment_id The attachment ID.
+ */
$file = apply_filters( 'update_attached_file', $file, $attachment_id );
if ( $file = _wp_relative_upload_path( $file ) )
return update_post_meta( $attachment_id, '_wp_attached_file', $file );
@@ -222,7 +238,6 @@
* The path is relative to the current upload dir.
*
* @since 2.9.0
- * @uses apply_filters() Calls '_wp_relative_upload_path' on file path.
*
* @param string $path Full path to the file
* @return string relative path on success, unchanged path on failure.
@@ -236,6 +251,14 @@
$new_path = ltrim( $new_path, '/' );
}
+ /**
+ * Filter the relative path to an uploaded file.
+ *
+ * @since 2.9.0
+ *
+ * @param string $new_path Relative path to the uploaded file.
+ * @param string $path Original path to the uploaded file.
+ */
return apply_filters( '_wp_relative_upload_path', $new_path, $path );
}
@@ -1331,6 +1354,14 @@
register_taxonomy_for_object_type( $taxonomy, $post_type );
}
+ /**
+ * Fires after a post type has been registered.
+ *
+ * @since 3.3.0
+ *
+ * @param string $post_type The post type.
+ * @param array $args An array of post type arguments. @see register_post_type()
+ */
do_action( 'registered_post_type', $post_type, $args );
return $args;
@@ -1497,6 +1528,17 @@
$labels = _get_custom_object_labels( $post_type_object, $nohier_vs_hier_defaults );
$post_type = $post_type_object->name;
+
+ /**
+ * Filter the labels for a post type.
+ *
+ * The dynamic portion of the hook name, $post_type, refers
+ * to the slug used when registering the post type.
+ *
+ * @since 3.5.0
+ *
+ * @param array $labels An array of post type labels.
+ */
return apply_filters( "post_type_labels_{$post_type}", $labels );
}
@@ -1937,18 +1979,7 @@
* when calling filters.
*
* @since 2.3.0
- * @uses apply_filters() Calls 'edit_$field' and '{$field_no_prefix}_edit_pre' passing $value and
- * $post_id if $context == 'edit' and field name prefix == 'post_'.
*
- * @uses apply_filters() Calls 'edit_post_$field' passing $value and $post_id if $context == 'db'.
- * @uses apply_filters() Calls 'pre_$field' passing $value if $context == 'db' and field name prefix == 'post_'.
- * @uses apply_filters() Calls '{$field}_pre' passing $value if $context == 'db' and field name prefix != 'post_'.
- *
- * @uses apply_filters() Calls '$field' passing $value, $post_id and $context if $context == anything
- * other than 'raw', 'edit' and 'db' and field name prefix == 'post_'.
- * @uses apply_filters() Calls 'post_$field' passing $value if $context == anything other than 'raw',
- * 'edit' and 'db' and field name prefix != 'post_'.
- *
* @param string $field The Post Object field name.
* @param mixed $value The Post Object value.
* @param int $post_id Post ID.
@@ -1981,11 +2012,44 @@
$format_to_edit = array('post_content', 'post_excerpt', 'post_title', 'post_password');
if ( $prefixed ) {
- $value = apply_filters("edit_{$field}", $value, $post_id);
- // Old school
- $value = apply_filters("{$field_no_prefix}_edit_pre", $value, $post_id);
+ /**
+ * Filter a prefixed post field prior to being sanitized for the 'edit' context.
+ *
+ * The dynamic portion of the hook name, $field, refers
+ * to the prefixed post field being filtered, such as
+ * 'post_content', 'post_excerpt', 'post_title', etc.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the prefixed post field.
+ * @param int $post_id The post ID.
+ */
+ $value = apply_filters( "edit_{$field}", $value, $post_id );
+ /**
+ * Filter a prefixed post field prior to being sanitized for the 'edit' context.
+ *
+ * The dynamic portion of the hook name, $field_no_prefix. refers to normally-prefixed
+ * post fields with the 'post_' prefix removed.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the non-prefixed post field.
+ * @param int $post_id The post ID.
+ */
+ $value = apply_filters( "{$field_no_prefix}_edit_pre", $value, $post_id );
} else {
- $value = apply_filters("edit_post_{$field}", $value, $post_id);
+ /**
+ * Filter a non-prefixed post field prior to being sanitized for the 'edit' context.
+ *
+ * The dynamic portion of the hook name, $field. refers to fields with names
+ * lacking the 'post_' prefix.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ * @param int $post_id The post ID.
+ */
+ $value = apply_filters( "edit_post_{$field}", $value, $post_id );
}
if ( in_array($field, $format_to_edit) ) {
@@ -1998,18 +2062,81 @@
}
} else if ( 'db' == $context ) {
if ( $prefixed ) {
- $value = apply_filters("pre_{$field}", $value);
- $value = apply_filters("{$field_no_prefix}_save_pre", $value);
+ /**
+ * Filter a prefixed post field prior to being sanitized for the 'db' context.
+ *
+ * The dynamic portion of the hook name, $field, refers to the name
+ * of the post field, such as 'post_content', 'post_title', etc.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ */
+ $value = apply_filters( "pre_{$field}", $value );
+ /**
+ * Filter the non-prefixed post field prior to being sanitized for the 'db' context.
+ *
+ * The dynamic portion of the hook name, $field_no_prefix. refers to normally-prefixed
+ * post fields with the 'post_' prefix removed.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ */
+ $value = apply_filters( "{$field_no_prefix}_save_pre", $value );
} else {
- $value = apply_filters("pre_post_{$field}", $value);
- $value = apply_filters("{$field}_pre", $value);
+ /**
+ * Filter a non-prefixed post field prior to being sanitized for the 'db' context.
+ *
+ * The dynamic portion of the hook name, $field. refers to fields with names
+ * lacking the 'post_' prefix.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ */
+ $value = apply_filters( "pre_post_{$field}", $value );
+ /**
+ * Filter a non-prefixed post field prior to being sanitized for the 'db' context.
+ *
+ * The dynamic portion of the hook name, $field, refers to fields with names
+ * lacking the 'post_' prefix.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ */
+ $value = apply_filters( "{$field}_pre", $value );
}
} else {
// Use display filters by default.
- if ( $prefixed )
- $value = apply_filters($field, $value, $post_id, $context);
- else
- $value = apply_filters("post_{$field}", $value, $post_id, $context);
+ if ( $prefixed ) {
+ /**
+ * Filter a prefixed post field prior to being sanitized for a context other than 'edit' or 'db'.
+ *
+ * @since 2.3.0
+ *
+ * @param string $field The prefixed post field name.
+ * @param mixed $value Value of the post field.
+ * @param int $post_id The post ID.
+ * @param string $context The context to sanitize the post field in.
+ */
+ $value = apply_filters( $field, $value, $post_id, $context );
+ } else {
+ /**
+ * Filter a non-prefixed post field prior to being sanitized for a context other than 'edit' or 'db'.
+ *
+ * The dynamic portion of the hook name, $field, refers to fields with names
+ * lacking the 'post_' prefix.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $value Value of the post field.
+ * @param int $post_id The post ID.
+ * @param string $context The context to sanitize the post field in.
+ */
+ $value = apply_filters( "post_{$field}", $value, $post_id, $context );
+ }
}
if ( 'attribute' == $context )
@@ -2181,7 +2308,14 @@
'video' => array(__('Video'), __('Manage Video'), _n_noop('Video (%s)', 'Video (%s)')),
);
- return apply_filters('post_mime_types', $post_mime_types);
+ /**
+ * Filter the default post mime types.
+ *
+ * @since 2.5.0
+ *
+ * @param array $post_mime_types An array of post mime types.
+ */
+ return apply_filters( 'post_mime_types', $post_mime_types );
}
/**
@@ -2278,8 +2412,6 @@
* disabled, item is already in the trash, or $force_delete is true.
*
* @since 1.0.0
- * @uses do_action() on 'delete_post' before deletion unless post type is 'attachment'.
- * @uses do_action() on 'deleted_post' after deletion unless post type is 'attachment'.
* @uses wp_delete_attachment() if post type is 'attachment'.
* @uses wp_trash_post() if item should be trashed.
*
@@ -2299,7 +2431,16 @@
if ( $post->post_type == 'attachment' )
return wp_delete_attachment( $postid, $force_delete );
- do_action('before_delete_post', $postid);
+ /**
+ * Fires after a post is trashed, but before any post data is deleted.
+ *
+ * Attachments are deleted separately. @see wp_delete_attachment()
+ *
+ * @since 3.2.0
+ *
+ * @param int $postid The post ID.
+ */
+ do_action( 'before_delete_post', $postid );
delete_post_meta($postid,'_wp_trash_meta_status');
delete_post_meta($postid,'_wp_trash_meta_time');
@@ -2348,8 +2489,26 @@
foreach ( $post_meta_ids as $mid )
delete_metadata_by_mid( 'post', $mid );
+ /**
+ * Fires after post data is deleted, but before the post is deleted.
+ *
+ * Attachments are deleted separately. @see wp_delete_attachment()
+ *
+ * @since 1.2.1
+ *
+ * @param int $postid The post ID.
+ */
do_action( 'delete_post', $postid );
$wpdb->delete( $wpdb->posts, array( 'ID' => $postid ) );
+ /**
+ * Fires after a post has been deleted.
+ *
+ * Attachments are deleted separately. @see wp_delete_attachment()
+ *
+ * @since 2.2.0
+ *
+ * @param int $postid The post ID.
+ */
do_action( 'deleted_post', $postid );
clean_post_cache( $post );
@@ -2361,7 +2520,16 @@
wp_clear_scheduled_hook('publish_future_post', array( $postid ) );
- do_action('after_delete_post', $postid);
+ /**
+ * Fires after a post is deleted and post caches are cleaned.
+ *
+ * Attachments are deleted separately. @see wp_delete_attachment()
+ *
+ * @since 3.2.0
+ *
+ * @param int $postid The post ID.
+ */
+ do_action( 'after_delete_post', $postid );
return $post;
}
@@ -2372,8 +2540,6 @@
* If trash is disabled, the post or page is permanently deleted.
*
* @since 2.9.0
- * @uses do_action() on 'trash_post' before trashing
- * @uses do_action() on 'trashed_post' after trashing
* @uses wp_delete_post() if trash is disabled
*
* @param int $post_id Post ID.
@@ -2389,7 +2555,14 @@
if ( $post['post_status'] == 'trash' )
return false;
- do_action('wp_trash_post', $post_id);
+ /**
+ * Fires before a post is sent to the trash.
+ *
+ * @since 3.3.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'wp_trash_post', $post_id );
add_post_meta($post_id,'_wp_trash_meta_status', $post['post_status']);
add_post_meta($post_id,'_wp_trash_meta_time', time());
@@ -2399,7 +2572,14 @@
wp_trash_post_comments($post_id);
- do_action('trashed_post', $post_id);
+ /**
+ * Fires after a post is sent to the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'trashed_post', $post_id );
return $post;
}
@@ -2408,8 +2588,6 @@
* Restores a post or page from the Trash
*
* @since 2.9.0
- * @uses do_action() on 'untrash_post' before undeletion
- * @uses do_action() on 'untrashed_post' after undeletion
*
* @param int $post_id Post ID.
* @return mixed False on failure
@@ -2421,7 +2599,14 @@
if ( $post['post_status'] != 'trash' )
return false;
- do_action('untrash_post', $post_id);
+ /**
+ * Fires before a post is restored from the trash.
+ *
+ * @since 2.9.0
+ *
+ * @parma int $post_id The post ID.
+ */
+ do_action( 'untrash_post', $post_id );
$post_status = get_post_meta($post_id, '_wp_trash_meta_status', true);
@@ -2434,7 +2619,14 @@
wp_untrash_post_comments($post_id);
- do_action('untrashed_post', $post_id);
+ /**
+ * Fires after a post has been restored from the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'untrashed_post', $post_id );
return $post;
}
@@ -2443,8 +2635,6 @@
* Moves comments for a post to the trash
*
* @since 2.9.0
- * @uses do_action() on 'trash_post_comments' before trashing
- * @uses do_action() on 'trashed_post_comments' after trashing
*
* @param int|object $post Post ID or object.
* @return mixed False on failure
@@ -2458,7 +2648,14 @@
$post_id = $post->ID;
- do_action('trash_post_comments', $post_id);
+ /**
+ * Fires before post comments have been sent to the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'trash_post_comments', $post_id );
$comments = $wpdb->get_results( $wpdb->prepare("SELECT comment_ID, comment_approved FROM $wpdb->comments WHERE comment_post_ID = %d", $post_id) );
if ( empty($comments) )
@@ -2475,7 +2672,15 @@
clean_comment_cache( array_keys($statuses) );
- do_action('trashed_post_comments', $post_id, $statuses);
+ /**
+ * Fires after post comments have been sent to the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ * @param array $statuses An array of post comment statuses.
+ */
+ do_action( 'trashed_post_comments', $post_id, $statuses );
return $result;
}
@@ -2484,8 +2689,6 @@
* Restore comments for a post from the trash
*
* @since 2.9.0
- * @uses do_action() on 'untrash_post_comments' before trashing
- * @uses do_action() on 'untrashed_post_comments' after trashing
*
* @param int|object $post Post ID or object.
* @return mixed False on failure
@@ -2504,7 +2707,14 @@
if ( empty($statuses) )
return true;
- do_action('untrash_post_comments', $post_id);
+ /**
+ * Fires before post comments are restored from the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'untrash_post_comments', $post_id );
// Restore each comment to its original status
$group_by_status = array();
@@ -2523,7 +2733,14 @@
delete_post_meta($post_id, '_wp_trash_meta_comments_status');
- do_action('untrashed_post_comments', $post_id);
+ /**
+ * Fires after post comments have been restored from the trash.
+ *
+ * @since 2.9.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'untrashed_post_comments', $post_id );
}
/**
@@ -2723,6 +2940,17 @@
$maybe_empty = ! $post_content && ! $post_title && ! $post_excerpt && post_type_supports( $post_type, 'editor' )
&& post_type_supports( $post_type, 'title' ) && post_type_supports( $post_type, 'excerpt' );
+ /**
+ * Filter whether to flag content as empty when inserting or updating a post.
+ *
+ * $maybe_empty is derived from a mix of conditionals testing if $post_content, $post_title, and $post_excerpt
+ * are empty, as well as if the post type supports 'editor', 'title', and 'excerpt.
+ *
+ * @since 3.3.0
+ *
+ * @param bool $maybe_empty Whether content, title, and excerpt are empty.
+ * @param array $postarr An array of post fields passed to wp_insert_post().
+ */
if ( apply_filters( 'wp_insert_post_empty_content', $maybe_empty, $postarr ) ) {
if ( $wp_error )
return new WP_Error( 'empty_content', __( 'Content, title, and excerpt are empty.' ) );
@@ -2834,7 +3062,20 @@
else
$post_parent = 0;
- // Check the post_parent to see if it will cause a hierarchy loop
+ $prepared_postarr = compact( array_keys( $postarr ) );
+ /**
+ * Filter the post parent ID prior to inserting or updating a post.
+ *
+ * Allows checking the post_parent for a hierarchy loop.
+ *
+ * @since 3.1.0
+ *
+ * @param int $post_parent The post parent ID.
+ * @param int $post_ID The post ID.
+ * @param array $prepared_postarr A compacted array of $postarr fields modified from default values.
+ * @param array $postarr An array of post fields sanitized in the 'db' context. @see sanitize_post()
+ *
+ */
$post_parent = apply_filters( 'wp_insert_post_parent', $post_parent, $post_ID, compact( array_keys( $postarr ) ), $postarr );
if ( isset($menu_order) )
@@ -2849,11 +3090,27 @@
// expected_slashed (everything!)
$data = compact( array( 'post_author', 'post_date', 'post_date_gmt', 'post_content', 'post_content_filtered', 'post_title', 'post_excerpt', 'post_status', 'post_type', 'comment_status', 'ping_status', 'post_password', 'post_name', 'to_ping', 'pinged', 'post_modified', 'post_modified_gmt', 'post_parent', 'menu_order', 'guid' ) );
- $data = apply_filters('wp_insert_post_data', $data, $postarr);
+ /**
+ * Filter slashed post data to insert in a new or existing post.
+ *
+ * @since 2.7.0
+ *
+ * @param array $data A prepared array of post fields and their values.
+ * @param array $postarr An array of post fields sanitized in the 'db' context. @see sanitize_post()
+ */
+ $data = apply_filters( 'wp_insert_post_data', $data, $postarr );
$data = wp_unslash( $data );
$where = array( 'ID' => $post_ID );
if ( $update ) {
+ /**
+ * Fires before an existing post is updated.
+ *
+ * @since 2.5.0
+ *
+ * @param int $post_ID The post ID.
+ * @param array $data A prepared array of post fields and their values.
+ */
do_action( 'pre_post_update', $post_ID, $data );
if ( false === $wpdb->update( $wpdb->posts, $data, $where ) ) {
if ( $wp_error )
@@ -2930,13 +3187,59 @@
wp_transition_post_status($data['post_status'], $previous_status, $post);
if ( $update ) {
- do_action('edit_post', $post_ID, $post);
+ /**
+ * Fires before a post is updated.
+ *
+ * @since 1.2.1
+ *
+ * @param int $post_ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ */
+ do_action( 'edit_post', $post_ID, $post );
$post_after = get_post($post_ID);
+ /**
+ * Fires after a post is updated.
+ *
+ * @since 3.0.0
+ *
+ * @param int $post_ID The post ID.
+ * @param WP_Post $post_after The WP_Post object after being updated.
+ * @param WP_Post $post_before The WP_Post object before being updated.
+ */
do_action( 'post_updated', $post_ID, $post_after, $post_before);
}
+ /**
+ * Fires when a post of a particular post type is saved.
+ *
+ * The dynamic portion of the hook name, $post->post_type, refers to the post type slug.
+ *
+ * @since 3.6.0
+ *
+ * @param int $post_ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ * @param bool $update Whether the post is being updated or created. True for updated, false for created.
+ */
do_action( "save_post_{$post->post_type}", $post_ID, $post, $update );
+ /**
+ * Fires when a post is saved.
+ *
+ * @since 1.5.2
+ *
+ * @param int $post_ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ * @param bool $update Whether the post is being updated or created. True for updated, false for created.
+ */
do_action( 'save_post', $post_ID, $post, $update );
+ /**
+ * Fires when a post is updated or inserted.
+ *
+ * @since 2.0.0
+ *
+ * @param int $post_ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ * @param bool $update Whether the post is being updated or created. True for updated, false for created.
+ */
do_action( 'wp_insert_post', $post_ID, $post, $update );
return $post_ID;
@@ -3006,7 +3309,6 @@
*
* @since 2.1.0
* @uses $wpdb
- * @uses do_action() Calls 'edit_post', 'save_post_{$post_type}', 'save_post' and 'wp_insert_post' on post_id and post data.
*
* @param int|object $post Post ID or object.
*/
@@ -3027,9 +3329,20 @@
$post->post_status = 'publish';
wp_transition_post_status( 'publish', $old_status, $post );
+ /**
+ * Fires after a post has been published and post status changed.
+ *
+ * @since 1.2.1
+ *
+ * @param int $post->ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ */
do_action( 'edit_post', $post->ID, $post );
+ //duplicate_hook
do_action( "save_post_{$post->post_type}", $post->ID, $post, true );
+ //duplicate_hook
do_action( 'save_post', $post->ID, $post, true );
+ //duplicate_hook
do_action( 'wp_insert_post', $post->ID, $post, true );
}
@@ -3077,7 +3390,7 @@
* @param string $post_status no uniqueness checks are made if the post is still draft or pending
* @param string $post_type
* @param integer $post_parent
- * @return string unique slug for the post, based on $post_name (with a -1, -2, etc. suffix)
+ * @return string Zunique slug for the post, based on $post_name (with a -1, -2, etc. suffix)
*/
function wp_unique_post_slug( $slug, $post_ID, $post_status, $post_type, $post_parent ) {
if ( in_array( $post_status, array( 'draft', 'pending', 'auto-draft' ) ) || ( 'inherit' == $post_status && 'revision' == $post_type ) )
@@ -3097,6 +3410,14 @@
$check_sql = "SELECT post_name FROM $wpdb->posts WHERE post_name = %s AND ID != %d LIMIT 1";
$post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_ID ) );
+ /**
+ * Filter whether a unique post slug is a bad attachment slug.
+ *
+ * @since 3.1.0
+ *
+ * @param bool false Whether a unique post slug is flagged as a bad attachment slug. Default false.
+ * @param string $slug The post slug.
+ */
if ( $post_name_check || in_array( $slug, $feeds ) || apply_filters( 'wp_unique_post_slug_is_bad_attachment_slug', false, $slug ) ) {
$suffix = 2;
do {
@@ -3114,6 +3435,15 @@
$check_sql = "SELECT post_name FROM $wpdb->posts WHERE post_name = %s AND post_type IN ( '" . implode( "', '", esc_sql( $hierarchical_post_types ) ) . "' ) AND ID != %d AND post_parent = %d LIMIT 1";
$post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_ID, $post_parent ) );
+ /**
+ * Filter whether a unique post slug is a bad hierarchical slug.
+ *
+ * @since 3.1.0
+ *
+ * @param bool false Whether a unique post slug is flagged as a bad idea for a hierarchical slug. Default false.
+ * @param string $post_type The post type.
+ * @param int $post_parent The post parent ID.
+ */
if ( $post_name_check || in_array( $slug, $feeds ) || preg_match( "@^($wp_rewrite->pagination_base)?\d+$@", $slug ) || apply_filters( 'wp_unique_post_slug_is_bad_hierarchical_slug', false, $slug, $post_type, $post_parent ) ) {
$suffix = 2;
do {
@@ -3128,6 +3458,15 @@
$check_sql = "SELECT post_name FROM $wpdb->posts WHERE post_name = %s AND post_type = %s AND ID != %d LIMIT 1";
$post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_type, $post_ID ) );
+ /**
+ * Filter whether a unique post slug is a bad flat slug.
+ *
+ * @since 3.1.0
+ *
+ * @param bool false Whether the slug is a bad flat slug.
+ * @param string $slug The unique post slug.
+ * @param string $post_type The post type.
+ */
if ( $post_name_check || in_array( $slug, $feeds ) || apply_filters( 'wp_unique_post_slug_is_bad_flat_slug', false, $slug, $post_type ) ) {
$suffix = 2;
do {
@@ -3139,6 +3478,20 @@
}
}
+ /**
+ * Filter the returned unique post slug.
+ *
+ * The slug is ased on $post_name (with a -1, -2, etc. suffix).
+ *
+ * @since 3.3.0
+ *
+ * @param string $slug The unique post slug.
+ * @param int $post_ID The post ID.
+ * @param string $post_status The post status.
+ * @param string $post_type The post type.
+ * @param int $post_parent The post parent ID.
+ * @param string $original_slug The original post slug.
+ */
return apply_filters( 'wp_unique_post_slug', $slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug );
}
@@ -3284,19 +3637,46 @@
* @since 2.3.0
* @link http://codex.wordpress.org/Post_Status_Transitions
*
- * @uses do_action() Calls 'transition_post_status' on $new_status, $old_status and
- * $post if there is a status change.
- * @uses do_action() Calls '{$old_status}_to_{$new_status}' on $post if there is a status change.
- * @uses do_action() Calls '{$new_status}_{$post->post_type}' on post ID and $post.
- *
* @param string $new_status Transition to this post status.
* @param string $old_status Previous post status.
* @param object $post Post data.
*/
function wp_transition_post_status($new_status, $old_status, $post) {
- do_action('transition_post_status', $new_status, $old_status, $post);
- do_action("{$old_status}_to_{$new_status}", $post);
- do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
+ /**
+ * Fires before a post status has transitioned from one to another
+ *
+ * @since 2.3.0
+ *
+ * @param string $new_status The new post status.
+ * @param string $old_status The old post status.
+ * @param WP_Post $post The WP_Post object.
+ */
+ do_action( 'transition_post_status', $new_status, $old_status, $post );
+ /**
+ * Fires before a post status has transitioned from one specific status to another.
+ *
+ * The dynamic portions of the hook nam, $old_status, and $new_status, refer to the post
+ * status the post is changing from and to, respectively. Use this hook for targeting
+ * specific post status transitions.
+ *
+ * @since 2.3.0
+ *
+ * @param WP_Post $post The WP_Post object.
+ */
+ do_action( "{$old_status}_to_{$new_status}", $post );
+ /**
+ * Fires before a post of a particular post type's status has transitioned from one to another.
+ *
+ * The dynamic portions of the hook name, $new_status, and $post->post_type, refer to the post
+ * status the post is transitioning to, and the slug of the post type being updated, respectively.
+ * Use this hook for targeting specific new post status changes for a specific post type.
+ *
+ * @since 2.3.0
+ *
+ * @param int $post->ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ */
+ do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );
}
//
@@ -3320,7 +3700,16 @@
$pung = preg_split('/\s/', $pung);
$pung[] = $uri;
$new = implode("\n", $pung);
- $new = apply_filters('add_ping', $new);
+ /**
+ * Filter a ping before it is added to the 'pinged' list in the database.
+ *
+ * The returned value is expected to be slashed.
+ *
+ * @since 2.0.0
+ *
+ * @param string $new The new ping URL to add.
+ */
+ $new = apply_filters( 'add_ping', $new );
// expected_slashed ($new)
$new = wp_unslash($new);
return $wpdb->update( $wpdb->posts, array( 'pinged' => $new ), array( 'ID' => $post_id ) );
@@ -3348,7 +3737,16 @@
$pung[] = trim( $enclosure[ 0 ] );
}
}
- $pung = apply_filters('get_enclosed', $pung, $post_id);
+
+ /**
+ * Filter the array of already-pinged, enclosed URLs.
+ *
+ * @since 2.0.0
+ *
+ * @param array $pung The pinged URLs.
+ * @param int $post_id The post ID.
+ */
+ $pung = apply_filters( 'get_enclosed', $pung, $post_id );
return $pung;
}
@@ -3366,7 +3764,14 @@
$pung = $wpdb->get_var( $wpdb->prepare( "SELECT pinged FROM $wpdb->posts WHERE ID = %d", $post_id ));
$pung = trim($pung);
$pung = preg_split('/\s/', $pung);
- $pung = apply_filters('get_pung', $pung);
+ /**
+ * Filter the URLs already pinged for a post.
+ *
+ * @since 2.0.0
+ *
+ * @param string $pung A list of already-pinged URLs for the post.
+ */
+ $pung = apply_filters( 'get_pung', $pung );
return $pung;
}
@@ -3384,7 +3789,14 @@
$to_ping = $wpdb->get_var( $wpdb->prepare( "SELECT to_ping FROM $wpdb->posts WHERE ID = %d", $post_id ));
$to_ping = sanitize_trackback_urls( $to_ping );
$to_ping = preg_split('/\s/', $to_ping, -1, PREG_SPLIT_NO_EMPTY);
- $to_ping = apply_filters('get_to_ping', $to_ping);
+ /**
+ * Filter the URLs that need to be pinged.
+ *
+ * @since 2.0.0
+ *
+ * @param string $to_ping A list of URLs still to ping for a post.
+ */
+ $to_ping = apply_filters( 'get_to_ping', $to_ping );
return $to_ping;
}
@@ -3712,7 +4124,15 @@
if ( $cache = wp_cache_get( $cache_key, 'posts' ) ) {
// Convert to WP_Post instances
$pages = array_map( 'get_post', $cache );
- $pages = apply_filters('get_pages', $pages, $r);
+ /**
+ * Filter the array of cached page objects to return in get_pages().
+ *
+ * @since 2.1.0
+ *
+ * @param array $pages An array of WP_Post page objects.
+ * @param array $r An array of arguments for getting pages. @see get_pages()
+ */
+ $pages = apply_filters( 'get_pages', $pages, $r );
return $pages;
}
@@ -3842,7 +4262,8 @@
$pages = $wpdb->get_results($query);
if ( empty($pages) ) {
- $pages = apply_filters('get_pages', array(), $r);
+ //duplicate_hook
+ $pages = apply_filters( 'get_pages', array(), $r );
return $pages;
}
@@ -3880,9 +4301,9 @@
// Convert to WP_Post instances
$pages = array_map( 'get_post', $pages );
+ //duplicate_hook
+ $pages = apply_filters( 'get_pages', $pages, $r );
- $pages = apply_filters('get_pages', $pages, $r);
-
return $pages;
}
@@ -3944,8 +4365,6 @@
* @since 2.0.0
* @uses $wpdb
* @uses $user_ID
- * @uses do_action() Calls 'edit_attachment' on $post_ID if this is an update.
- * @uses do_action() Calls 'add_attachment' on $post_ID if this is not an update.
*
* @param string|array $object Arguments to override defaults.
* @param string $file Optional filename.
@@ -4095,9 +4514,23 @@
add_post_meta( $post_ID, '_wp_attachment_context', $context, true );
if ( $update) {
- do_action('edit_attachment', $post_ID);
+ /**
+ * Fires after an attachment is updated.
+ *
+ * @since 2.0.0
+ *
+ * @param int $post_ID The post ID.
+ */
+ do_action( 'edit_attachment', $post_ID );
} else {
- do_action('add_attachment', $post_ID);
+ /**
+ * Fires after an attachment is added.
+ *
+ * @since 2.0.0
+ *
+ * @param int $post_ID The post ID.
+ */
+ do_action( 'add_attachment', $post_ID );
}
return $post_ID;
@@ -4115,7 +4548,6 @@
*
* @since 2.0.0
* @uses $wpdb
- * @uses do_action() Calls 'delete_attachment' hook on Attachment ID.
*
* @param int $post_id Attachment ID.
* @param bool $force_delete Whether to bypass trash and force deletion. Defaults to false.
@@ -4149,7 +4581,14 @@
if ( is_multisite() )
delete_transient( 'dirsize_cache' );
- do_action('delete_attachment', $post_id);
+ /**
+ * Fires after an attachment has been trashed, but before its meta data is deleted.
+ *
+ * @since 2.0.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'delete_attachment', $post_id );
wp_delete_object_term_relationships($post_id, array('category', 'post_tag'));
wp_delete_object_term_relationships($post_id, get_object_taxonomies($post->post_type));
@@ -4164,8 +4603,22 @@
foreach ( $post_meta_ids as $mid )
delete_metadata_by_mid( 'post', $mid );
+ /**
+ * Fires after an attachment's meta data has been deleted, but before the attachment is deleted.
+ *
+ * @since 1.2.1
+ *
+ * @param int $post_id The post ID.
+ */
do_action( 'delete_post', $post_id );
$wpdb->delete( $wpdb->posts, array( 'ID' => $post_id ) );
+ /**
+ * Fires after an attachment has been deleted.
+ *
+ * @since 2.2.0
+ *
+ * @param int $post_id The post ID.
+ */
do_action( 'deleted_post', $post_id );
$uploadpath = wp_upload_dir();
@@ -4174,13 +4627,23 @@
// Don't delete the thumb if another attachment uses it
if (! $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE meta_key = '_wp_attachment_metadata' AND meta_value LIKE %s AND post_id <> %d", '%' . $meta['thumb'] . '%', $post_id)) ) {
$thumbfile = str_replace(basename($file), $meta['thumb'], $file);
- $thumbfile = apply_filters('wp_delete_file', $thumbfile);
+ /**
+ * Filter the path to a specific-sized image being deleted.
+ *
+ * This hook fires for all sizes of images.
+ *
+ * @since 2.1.0
+ *
+ * @param string $thumbfile Path to the thumbnail-sized image to be deleted.
+ */
+ $thumbfile = apply_filters( 'wp_delete_file', $thumbfile );
@ unlink( path_join($uploadpath['basedir'], $thumbfile) );
}
}
// remove intermediate and backup images if there are any
foreach ( $intermediate_sizes as $intermediate ) {
+ //duplicate_hook
$intermediate_file = apply_filters( 'wp_delete_file', $intermediate['path'] );
@ unlink( path_join($uploadpath['basedir'], $intermediate_file) );
}
@@ -4188,12 +4651,14 @@
if ( is_array($backup_sizes) ) {
foreach ( $backup_sizes as $size ) {
$del_file = path_join( dirname($meta['file']), $size['file'] );
- $del_file = apply_filters('wp_delete_file', $del_file);
+ //duplicate_hook
+ $del_file = apply_filters( 'wp_delete_file', $del_file );
@ unlink( path_join($uploadpath['basedir'], $del_file) );
}
}
- $file = apply_filters('wp_delete_file', $file);
+ //duplicate_hook
+ $file = apply_filters( 'wp_delete_file', $file );
if ( ! empty($file) )
@ unlink($file);
@@ -4222,6 +4687,14 @@
if ( $unfiltered )
return $data;
+ /**
+ * Filter the returned meta data for an attachment.
+ *
+ * @since 2.1.0
+ *
+ * @param array $data An array of attachment metadata.
+ * @param int $post->ID The attachment post ID.
+ */
return apply_filters( 'wp_get_attachment_metadata', $data, $post->ID );
}
@@ -4239,6 +4712,14 @@
if ( !$post = get_post( $post_id ) )
return false;
+ /**
+ * Filter the attachment meta data to be updated.
+ *
+ * @since 2.1.0
+ *
+ * @param array $data An array of attachment meta data.
+ * @param int $post->ID The attachment post ID.
+ */
if ( $data = apply_filters( 'wp_update_attachment_metadata', $data, $post->ID ) )
return update_post_meta( $post->ID, '_wp_attachment_metadata', $data );
else
@@ -4276,6 +4757,14 @@
if ( empty($url) ) //If any of the above options failed, Fallback on the GUID as used pre-2.7, not recommended to rely upon this.
$url = get_the_guid( $post->ID );
+ /**
+ * Filter the attachment URL.
+ *
+ * @since 2.1.0
+ *
+ * @param string $url The URL to the attachment.
+ * @param int $post->ID The attachment post ID.
+ */
$url = apply_filters( 'wp_get_attachment_url', $url, $post->ID );
if ( empty( $url ) )
@@ -4301,8 +4790,17 @@
$file = get_attached_file( $post->ID );
- if ( !empty($imagedata['thumb']) && ($thumbfile = str_replace(basename($file), $imagedata['thumb'], $file)) && file_exists($thumbfile) )
+ if ( !empty($imagedata['thumb']) && ($thumbfile = str_replace(basename($file), $imagedata['thumb'], $file)) && file_exists($thumbfile) ) {
+ /**
+ * Filter the path to the attachment thumbnail image.
+ *
+ * @since 2.1.0
+ *
+ * @param string $thumbfile Path to the attachment thumbnail image.
+ * @param int $post->ID The attachment post ID.
+ */
return apply_filters( 'wp_get_attachment_thumb_file', $thumbfile, $post->ID );
+ }
return false;
}
@@ -4330,6 +4828,14 @@
$url = str_replace(basename($url), basename($thumb), $url);
+ /**
+ * Filter the URL to the attachment thumbnail image.
+ *
+ * @since 2.1.0
+ *
+ * @param string $url URL of the attachment thumbnail image.
+ * @param int $post->ID The attachment post ID.
+ */
return apply_filters( 'wp_get_attachment_thumb_url', $url, $post->ID );
}
@@ -4394,9 +4900,35 @@
$icon_files = wp_cache_get('icon_files');
if ( !is_array($icon_files) ) {
- $icon_dir = apply_filters( 'icon_dir', ABSPATH . WPINC . '/images/crystal' );
- $icon_dir_uri = apply_filters( 'icon_dir_uri', includes_url('images/crystal') );
- $dirs = apply_filters( 'icon_dirs', array($icon_dir => $icon_dir_uri) );
+ $icon_dir = ABSPATH . WPINC . '/images/crystal';
+ /**
+ * Filter the path to the directory containing mime type icons.
+ *
+ * @since 2.0.0
+ *
+ * @param string $icon_dir Path to the mime type icons directory.
+ */
+ $icon_dir = apply_filters( 'icon_dir', $icon_dir );
+
+ $icon_dir_uri = includes_url( 'images/crystal' );
+ /**
+ * Filter the URI to the directory containing mime type icons.
+ *
+ * @since 2.0.0
+ *
+ * @param string $icon_dir_uri URI to the mime type icons directory.
+ */
+ $icon_dir_uri = apply_filters( 'icon_dir_uri', $icon_dir_uri );
+
+ $dirs = array( $icon_dir => $icon_dir_uri );
+ /**
+ * Filter the base directories containing mime type icons.
+ *
+ * @since 2.5.0
+ *
+ * @param array $dirs An array containing the icon directory path as key, icon directory URI as value.
+ */
+ $dirs = apply_filters( 'icon_dirs', $dirs );
$icon_files = array();
while ( $dirs ) {
$keys = array_keys( $dirs );
@@ -4443,7 +4975,16 @@
}
}
- return apply_filters( 'wp_mime_type_icon', $icon, $mime, $post_id ); // Last arg is 0 if function pass mime type.
+ /**
+ * Filter the returned icon URL for a mime type.
+ *
+ * @since 2.1.0
+ *
+ * @param string $icon URL to the mime type icon.
+ * @param string $mime The mime type.
+ * @param int $post_id The post ID. 0 if a mime type was passed to the function.
+ */
+ return apply_filters( 'wp_mime_type_icon', $icon, $mime, $post_id );
}
/**
@@ -4571,13 +5112,20 @@
*
* @since 0.71
*
- * @uses apply_filters() Calls 'get_lastpostdate' filter
- *
* @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
* @return string The date of the last post.
*/
-function get_lastpostdate($timezone = 'server') {
- return apply_filters( 'get_lastpostdate', _get_last_post_time( $timezone, 'date' ), $timezone );
+function get_lastpostdate( $timezone = 'server' ) {
+ $last_post_time = _get_last_post_time( $timezone, 'date' );
+ /**
+ * Filter the date the last post was published.
+ *
+ * @since 2.3.0
+ *
+ * @param string $last_post_time The post date.
+ * @param string $timezone The location to the get the time. Can be 'gmt', 'blog', or 'server'.
+ */
+ return apply_filters( 'get_lastpostdate', $last_post_time, $timezone );
}
/**
@@ -4588,18 +5136,25 @@
* 'gmt' is when the last post was modified in GMT time.
*
* @since 1.2.0
- * @uses apply_filters() Calls 'get_lastpostmodified' filter
*
* @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
* @return string The date the post was last modified.
*/
-function get_lastpostmodified($timezone = 'server') {
+function get_lastpostmodified( $timezone = 'server' ) {
$lastpostmodified = _get_last_post_time( $timezone, 'modified' );
$lastpostdate = get_lastpostdate($timezone);
if ( $lastpostdate > $lastpostmodified )
$lastpostmodified = $lastpostdate;
+ /**
+ * Filter the date the last post was modified.
+ *
+ * @since 2.3.0
+ *
+ * @param string $lastpostmodified The post modified date.
+ * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
+ */
return apply_filters( 'get_lastpostmodified', $lastpostmodified, $timezone );
}
@@ -4681,8 +5236,6 @@
* @subpackage Cache
* @since 2.0.0
*
- * @uses do_action() Calls 'clean_post_cache' on $id before adding children (if any).
- *
* @param int|object $post Post ID or object to remove from the cache
*/
function clean_post_cache( $post ) {
@@ -4702,6 +5255,14 @@
wp_cache_delete( 'wp_get_archives', 'general' );
+ /**
+ * Fires after post and its post meta has been deleted from the cache.
+ *
+ * @since 2.5.0
+ *
+ * @param int $post->ID The post ID.
+ * @param WP_Post $post The WP_Post object.
+ */
do_action( 'clean_post_cache', $post->ID, $post );
if ( is_post_type_hierarchical( $post->post_type ) )
@@ -4709,6 +5270,13 @@
if ( 'page' == $post->post_type ) {
wp_cache_delete( 'all_page_ids', 'posts' );
+ /**
+ * Fires after the page cache has been deleted.
+ *
+ * @since 2.5.0
+ *
+ * @param int $post->ID The page ID.
+ */
do_action( 'clean_page_cache', $post->ID );
}
@@ -4796,8 +5364,6 @@
* @subpackage Cache
* @since 3.0.0
*
- * @uses do_action() Calls 'clean_attachment_cache' on $id.
- *
* @param int $id The attachment ID in the cache to clean
* @param bool $clean_terms optional. Whether to clean terms cache
*/
@@ -4815,7 +5381,14 @@
if ( $clean_terms )
clean_object_term_cache($id, 'attachment');
- do_action('clean_attachment_cache', $id);
+ /**
+ * Fires after the attachment cache has been cleaned.
+ *
+ * @since 3.0.0
+ *
+ * @param int $id The attachment ID.
+ */
+ do_action( 'clean_attachment_cache', $id );
}
//
@@ -4828,7 +5401,6 @@
* @since 2.3.0
* @access private
* @uses $wpdb
- * @uses do_action() Calls 'private_to_published' on post ID if this is a 'private_to_published' call.
* @uses wp_clear_scheduled_hook() with 'publish_future_post' and post ID.
*
* @param string $new_status New post status
@@ -4842,7 +5414,16 @@
// Reset GUID if transitioning to publish and it is empty
if ( '' == get_the_guid($post->ID) )
$wpdb->update( $wpdb->posts, array( 'guid' => get_permalink( $post->ID ) ), array( 'ID' => $post->ID ) );
- do_action('private_to_published', $post->ID); // Deprecated, use private_to_publish
+
+ /**
+ * Fires when transitioning a post from the private to published post status.
+ *
+ * @since 1.5.2
+ * @deprecated Use 'private_to_publish' hook instead.
+ *
+ * @param int $post->ID The post ID.
+ */
+ do_action( 'private_to_published', $post->ID );
}
// If published posts changed clear the lastpostmodified cache
@@ -4881,13 +5462,20 @@
* @since 2.3.0
* @access private
* @uses XMLRPC_REQUEST and WP_IMPORTING constants.
- * @uses do_action() Calls 'xmlrpc_publish_post' on post ID if XMLRPC_REQUEST is defined.
*
* @param int $post_id The ID in the database table of the post being published
*/
function _publish_post_hook($post_id) {
- if ( defined('XMLRPC_REQUEST') )
- do_action('xmlrpc_publish_post', $post_id);
+ if ( defined( 'XMLRPC_REQUEST' ) ) {
+ /**
+ * Fires after XMLRPC_REQUEST is defined.
+ *
+ * @since 2.1.0
+ *
+ * @param int $post_id The post ID.
+ */
+ do_action( 'xmlrpc_publish_post', $post_id );
+ }
if ( defined('WP_IMPORTING') )
return;