WordPress.org

Make WordPress Core

Changeset 28106


Ignore:
Timestamp:
04/13/2014 11:05:20 PM (8 years ago)
Author:
DrewAPicture
Message:

Part II of inline documentation for hooks in wp-includes/post.php.

Documents all remaining hooks following [28041] and [28042]. Also updates the hash notation style for wp_insert_post().

Props nacin for several hook descriptions.

Fixes #25376.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/post.php

    r28042 r28106  
    13521352    }
    13531353
     1354    /**
     1355     * Fires after a post type is registered.
     1356     *
     1357     * @since 3.3.0
     1358     *
     1359     * @param string $post_type Post type.
     1360     * @param array  $args      Arguments used to register the post type.
     1361     */
    13541362    do_action( 'registered_post_type', $post_type, $args );
    13551363
     
    24022410 *
    24032411 * @since 1.0.0
    2404  * @uses do_action() on 'delete_post' before deletion unless post type is 'attachment'.
    2405  * @uses do_action() on 'deleted_post' after deletion unless post type is 'attachment'.
     2412 *
    24062413 * @uses wp_delete_attachment() if post type is 'attachment'.
    24072414 * @uses wp_trash_post() if item should be trashed.
     
    24232430        return wp_delete_attachment( $postid, $force_delete );
    24242431
    2425     do_action('before_delete_post', $postid);
     2432    /**
     2433     * Fires before a post is deleted, at the start of wp_delete_post().
     2434     *
     2435     * @since 3.2.0
     2436     *
     2437     * @see wp_delete_post()
     2438     *
     2439     * @param int $postid Post ID.
     2440     */
     2441    do_action( 'before_delete_post', $postid );
    24262442
    24272443    delete_post_meta($postid,'_wp_trash_meta_status');
     
    24582474        delete_metadata_by_mid( 'post', $mid );
    24592475
     2476    /**
     2477     * Fires immediately before a post is deleted from the database.
     2478     *
     2479     * @since 1.2.0
     2480     *
     2481     * @param int $postid Post ID.
     2482     */
    24602483    do_action( 'delete_post', $postid );
    24612484    $result = $wpdb->delete( $wpdb->posts, array( 'ID' => $postid ) );
     
    24632486        return false;
    24642487    }
     2488
     2489    /**
     2490     * Fires immediately after a post is deleted from the database.
     2491     *
     2492     * @since 2.2.0
     2493     *
     2494     * @param int $postid Post ID.
     2495     */
    24652496    do_action( 'deleted_post', $postid );
    24662497
     
    24742505    wp_clear_scheduled_hook('publish_future_post', array( $postid ) );
    24752506
    2476     do_action('after_delete_post', $postid);
     2507    /**
     2508     * Fires after a post is deleted, at the conclusion of wp_delete_post().
     2509     *
     2510     * @since 3.2.0
     2511     *
     2512     * @see wp_delete_post()
     2513     *
     2514     * @param int $postid Post ID.
     2515     */
     2516    do_action( 'after_delete_post', $postid );
    24772517
    24782518    return $post;
     
    25132553 *
    25142554 * @since 2.9.0
    2515  * @uses do_action() on 'trash_post' before trashing
    2516  * @uses do_action() on 'trashed_post' after trashing
     2555 *
    25172556 * @uses wp_delete_post() if trash is disabled
    25182557 *
     
    25302569        return false;
    25312570
    2532     do_action('wp_trash_post', $post_id);
     2571    /**
     2572     * Fires before a post is sent to the trash.
     2573     *
     2574     * @since 3.3.0
     2575     *
     2576     * @param int $post_id Post ID.
     2577     */
     2578    do_action( 'wp_trash_post', $post_id );
    25332579
    25342580    add_post_meta($post_id,'_wp_trash_meta_status', $post['post_status']);
     
    25402586    wp_trash_post_comments($post_id);
    25412587
    2542     do_action('trashed_post', $post_id);
     2588    /**
     2589     * Fires after a post is sent to the trash.
     2590     *
     2591     * @since 2.9.0
     2592     *
     2593     * @param int $post_id Post ID.
     2594     */
     2595    do_action( 'trashed_post', $post_id );
    25432596
    25442597    return $post;
     
    25492602 *
    25502603 * @since 2.9.0
    2551  * @uses do_action() on 'untrash_post' before undeletion
    2552  * @uses do_action() on 'untrashed_post' after undeletion
    25532604 *
    25542605 * @param int $post_id Post ID.
     
    25622613        return false;
    25632614
    2564     do_action('untrash_post', $post_id);
     2615    /**
     2616     * Fires before a post is restored from the trash.
     2617     *
     2618     * @since 2.9.0
     2619     *
     2620     * @param int $post_id Post ID.
     2621     */
     2622    do_action( 'untrash_post', $post_id );
    25652623
    25662624    $post_status = get_post_meta($post_id, '_wp_trash_meta_status', true);
     
    25752633    wp_untrash_post_comments($post_id);
    25762634
    2577     do_action('untrashed_post', $post_id);
     2635    /**
     2636     * Fires after a post is restored from the trash.
     2637     *
     2638     * @since 2.9.0
     2639     *
     2640     * @param int $post_id Post ID.
     2641     */
     2642    do_action( 'untrashed_post', $post_id );
    25782643
    25792644    return $post;
     
    25842649 *
    25852650 * @since 2.9.0
    2586  * @uses do_action() on 'trash_post_comments' before trashing
    2587  * @uses do_action() on 'trashed_post_comments' after trashing
    25882651 *
    25892652 * @param int|WP_Post $post Optional. Post ID or post object.
     
    25992662    $post_id = $post->ID;
    26002663
    2601     do_action('trash_post_comments', $post_id);
     2664    /**
     2665     * Fires before comments are sent to the trash.
     2666     *
     2667     * @since 2.9.0
     2668     *
     2669     * @param int $post_id Post ID.
     2670     */
     2671    do_action( 'trash_post_comments', $post_id );
    26022672
    26032673    $comments = $wpdb->get_results( $wpdb->prepare("SELECT comment_ID, comment_approved FROM $wpdb->comments WHERE comment_post_ID = %d", $post_id) );
     
    26162686    clean_comment_cache( array_keys($statuses) );
    26172687
    2618     do_action('trashed_post_comments', $post_id, $statuses);
     2688    /**
     2689     * Fires after comments are sent to the trash.
     2690     *
     2691     * @since 2.9.0
     2692     *
     2693     * @param int   $post_id  Post ID.
     2694     * @param array $statuses Array of comment statuses.
     2695     */
     2696    do_action( 'trashed_post_comments', $post_id, $statuses );
    26192697
    26202698    return $result;
     
    26252703 *
    26262704 * @since 2.9.0
    2627  * @uses do_action() on 'untrash_post_comments' before trashing
    2628  * @uses do_action() on 'untrashed_post_comments' after trashing
    26292705 *
    26302706 * @param int|WP_Post $post Optional. Post ID or post object.
     
    26452721        return true;
    26462722
    2647     do_action('untrash_post_comments', $post_id);
     2723    /**
     2724     * Fires before comments are restored for a post from the trash.
     2725     *
     2726     * @since 2.9.0
     2727     *
     2728     * @param int $post_id Post ID.
     2729     */
     2730    do_action( 'untrash_post_comments', $post_id );
    26482731
    26492732    // Restore each comment to its original status
     
    26642747    delete_post_meta($post_id, '_wp_trash_meta_comments_status');
    26652748
    2666     do_action('untrashed_post_comments', $post_id);
     2749    /**
     2750     * Fires after comments are restored for a post from the trash.
     2751     *
     2752     * @since 2.9.0
     2753     *
     2754     * @param int $post_id Post ID.
     2755     */
     2756    do_action( 'untrashed_post_comments', $post_id );
    26672757}
    26682758
     
    27982888 *     An array of elements that make up a post to update or insert.
    27992889 *
    2800  *     @type int    'ID'                    The post ID. If equal to something other than 0, the post with that ID will
    2801  *                                          be updated. Default 0.
    2802  *     @type string 'post_status'           The post status. Default 'draft'.
    2803  *     @type string 'post_type'             The post type. Default 'post'.
    2804  *     @type int    'post_author'           The ID of the user who added the post. Default the current user ID.
    2805  *     @type bool   'ping_status'           Whether the post can accept pings. Default value of 'default_ping_status' option.
    2806  *     @type int    'post_parent'           Set this for the post it belongs to, if any. Default 0.
    2807  *     @type int    'menu_order'            The order it is displayed. Default 0.
    2808  *     @type string 'to_ping'               Space or carriage return-separated list of URLs to ping. Default empty string.
    2809  *     @type string 'pinged'                Space or carriage return-separated list of URLs that have been pinged.
    2810  *                                          Default empty string.
    2811  *     @type string 'post_password          The password to access the post. Default empty string.
    2812  *     @type string 'guid'                  Global Unique ID for referencing the post.
    2813  *     @type string 'post_content_filtered' The filtered post content. Default empty string.
    2814  *     @type string 'post_excerpt'          The post excerpt. Default empty string.
     2890 *     @type int    $ID                    The post ID. If equal to something other than 0, the post with that ID will
     2891 *                                         be updated. Default 0.
     2892 *     @type string $post_status           The post status. Default 'draft'.
     2893 *     @type string $post_type             The post type. Default 'post'.
     2894 *     @type int    $post_author           The ID of the user who added the post. Default the current user ID.
     2895 *     @type bool   $ping_status           Whether the post can accept pings. Default value of 'default_ping_status' option.
     2896 *     @type int    $post_parent           Set this for the post it belongs to, if any. Default 0.
     2897 *     @type int    $menu_order            The order it is displayed. Default 0.
     2898 *     @type string $to_ping               Space or carriage return-separated list of URLs to ping. Default empty string.
     2899 *     @type string $pinged                Space or carriage return-separated list of URLs that have been pinged.
     2900 *                                         Default empty string.
     2901 *     @type string $post_password         The password to access the post. Default empty string.
     2902 *     @type string $guid'                 Global Unique ID for referencing the post.
     2903 *     @type string $post_content_filtered The filtered post content. Default empty string.
     2904 *     @type string $post_excerpt          The post excerpt. Default empty string.
    28152905 * }
    28162906 * @param bool  $wp_error Optional. Allow return of WP_Error on failure.
     
    29883078        $post_parent = 0;
    29893079
    2990     // Check the post_parent to see if it will cause a hierarchy loop
     3080    /**
     3081     * Filter the post parent -- used to check for and prevent hierarchy loops.
     3082     *
     3083     * @since 3.1.0
     3084     *
     3085     * @param int   $post_parent Post parent ID.
     3086     * @param int   $post_ID     Post ID.
     3087     * @param array $new_postarr Array of parsed post data.
     3088     * @param array $postarr     Array of sanitized, but otherwise unmodified post data.
     3089     */
    29913090    $post_parent = apply_filters( 'wp_insert_post_parent', $post_parent, $post_ID, compact( array_keys( $postarr ) ), $postarr );
    29923091
     
    30033102    // expected_slashed (everything!)
    30043103    $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' ) );
    3005     $data = apply_filters('wp_insert_post_data', $data, $postarr);
     3104
     3105    /**
     3106     * Filter slashed post data just before it is inserted into the database.
     3107     *
     3108     * @since 2.7.0
     3109     *
     3110     * @param array $data    Array of slashed post data.
     3111     * @param array $postarr Array of sanitized, but otherwise unmodified post data.
     3112     */
     3113    $data = apply_filters( 'wp_insert_post_data', $data, $postarr );
    30063114    $data = wp_unslash( $data );
    30073115    $where = array( 'ID' => $post_ID );
    30083116
    30093117    if ( $update ) {
     3118        /**
     3119         * Fires immediately before an existing post is updated in the database.
     3120         *
     3121         * @since 2.5.0
     3122         *
     3123         * @param int   $post_ID Post ID.
     3124         * @param array $data    Array of unslashed post data.
     3125         */
    30103126        do_action( 'pre_post_update', $post_ID, $data );
    30113127        if ( false === $wpdb->update( $wpdb->posts, $data, $where ) ) {
     
    30843200
    30853201    if ( $update ) {
    3086         do_action('edit_post', $post_ID, $post);
     3202        /**
     3203         * Fires once an existing post has been updated.
     3204         *
     3205         * @since 1.2.0
     3206         *
     3207         * @param int     $post_ID Post ID.
     3208         * @param WP_Post $post    Post object.
     3209         */
     3210        do_action( 'edit_post', $post_ID, $post );
    30873211        $post_after = get_post($post_ID);
     3212
     3213        /**
     3214         * Fires once an existing post has been updated.
     3215         *
     3216         * @since 3.0.0
     3217         *
     3218         * @param int     $post_ID      Post ID.
     3219         * @param WP_Post $post_after   Post object following the update.
     3220         * @param WP_Post $post_before  Post object before the update.
     3221         */
    30883222        do_action( 'post_updated', $post_ID, $post_after, $post_before);
    30893223    }
    30903224
     3225    /**
     3226     * Fires once a post has been saved.
     3227     *
     3228     * The dynamic portion of the hook name, $post->post_type, refers to
     3229     * the post type slug.
     3230     *
     3231     * @since 3.7.0
     3232     *
     3233     * @param int     $post_ID Post ID.
     3234     * @param WP_Post $post    Post object.
     3235     * @param bool    $update  Whether this is an existing post being updated or not.
     3236     */
    30913237    do_action( "save_post_{$post->post_type}", $post_ID, $post, $update );
     3238
     3239    /**
     3240     * Fires once a post has been saved.
     3241     *
     3242     * @since 1.5.0
     3243     *
     3244     * @param int     $post_ID Post ID.
     3245     * @param WP_Post $post    Post object.
     3246     * @param bool    $update  Whether this is an existing post being updated or not.
     3247     */
    30923248    do_action( 'save_post', $post_ID, $post, $update );
     3249
     3250    /**
     3251     * Fires once a post has been saved.
     3252     *
     3253     * @since 2.0.0
     3254     *
     3255     * @param int     $post_ID Post ID.
     3256     * @param WP_Post $post    Post object.
     3257     * @param bool    $update  Whether this is an existing post being updated or not.
     3258     */
    30933259    do_action( 'wp_insert_post', $post_ID, $post, $update );
    30943260
     
    31603326 * @since 2.1.0
    31613327 * @uses $wpdb
    3162  * @uses do_action() Calls 'edit_post', 'save_post_{$post_type}', 'save_post' and 'wp_insert_post' on post_id and post data.
    31633328 *
    31643329 * @param int|WP_Post $post Post ID or post object.
     
    31813346    wp_transition_post_status( 'publish', $old_status, $post );
    31823347
     3348    /** This action is documented in wp-includes/post.php */
    31833349    do_action( 'edit_post', $post->ID, $post );
     3350    /** This action is documented in wp-includes/post.php */
    31843351    do_action( "save_post_{$post->post_type}", $post->ID, $post, true );
     3352    /** This action is documented in wp-includes/post.php */
    31853353    do_action( 'save_post', $post->ID, $post, true );
     3354    /** This action is documented in wp-includes/post.php */
    31863355    do_action( 'wp_insert_post', $post->ID, $post, true );
    31873356}
     
    32513420        $post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_ID ) );
    32523421
     3422        /**
     3423         * Filter whether the post slug would make a bad attachment slug.
     3424         *
     3425         * @since 3.1.0
     3426         *
     3427         * @param bool   $bad_slug Whether the slug would be bad as an attachment slug.
     3428         * @param string $slug     The post slug.
     3429         */
    32533430        if ( $post_name_check || in_array( $slug, $feeds ) || apply_filters( 'wp_unique_post_slug_is_bad_attachment_slug', false, $slug ) ) {
    32543431            $suffix = 2;
     
    32633440        if ( 'nav_menu_item' == $post_type )
    32643441            return $slug;
    3265         // Page slugs must be unique within their own trees. Pages are in a separate
    3266         // namespace than posts so page slugs are allowed to overlap post slugs.
     3442
     3443        /*
     3444         * Page slugs must be unique within their own trees. Pages are in a separate
     3445         * namespace than posts so page slugs are allowed to overlap post slugs.
     3446         */
    32673447        $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";
    32683448        $post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_ID, $post_parent ) );
    32693449
     3450        /**
     3451         * Filter whether the post slug would make a bad hierarchical post slug.
     3452         *
     3453         * @since 3.1.0
     3454         *
     3455         * @param bool   $bad_slug    Whether the post slug would be bad in a hierarchical post context.
     3456         * @param string $slug        The post slug.
     3457         * @param string $post_type   Post type.
     3458         * @param int    $post_parent Post parent ID.
     3459         */
    32703460        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 ) ) {
    32713461            $suffix = 2;
     
    32823472        $post_name_check = $wpdb->get_var( $wpdb->prepare( $check_sql, $slug, $post_type, $post_ID ) );
    32833473
     3474        /**
     3475         * Filter whether the post slug would be bad as a flat slug.
     3476         *
     3477         * @since 3.1.0
     3478         *
     3479         * @param bool   $bad_slug  Whether the post slug would be bad as a flat slug.
     3480         * @param string $slug      The post slug.
     3481         * @param string $post_type Post type.
     3482         */
    32843483        if ( $post_name_check || in_array( $slug, $feeds ) || apply_filters( 'wp_unique_post_slug_is_bad_flat_slug', false, $slug, $post_type ) ) {
    32853484            $suffix = 2;
     
    32933492    }
    32943493
     3494    /**
     3495     * Filter the unique post slug.
     3496     *
     3497     * @since 3.3.0
     3498     *
     3499     * @param string $slug          The post slug.
     3500     * @param int    $post_ID       Post ID.
     3501     * @param string $post_status   The post status.
     3502     * @param string $post_type     Post type.
     3503     * @param int    $post_parent   Post parent ID
     3504     * @param string $original_slug The original post slug.
     3505     */
    32953506    return apply_filters( 'wp_unique_post_slug', $slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug );
    32963507}
     
    34343645 *
    34353646 * @since 2.3.0
     3647 *
    34363648 * @link http://codex.wordpress.org/Post_Status_Transitions
    3437  *
    3438  * @uses do_action() Calls 'transition_post_status' on $new_status, $old_status and
    3439  *  $post if there is a status change.
    3440  * @uses do_action() Calls '{$old_status}_to_{$new_status}' on $post if there is a status change.
    3441  * @uses do_action() Calls '{$new_status}_{$post->post_type}' on post ID and $post.
    34423649 *
    34433650 * @param string $new_status Transition to this post status.
     
    34463653 */
    34473654function wp_transition_post_status($new_status, $old_status, $post) {
    3448     do_action('transition_post_status', $new_status, $old_status, $post);
    3449     do_action("{$old_status}_to_{$new_status}", $post);
    3450     do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
     3655    /**
     3656     * Fires when a post is transitioned from one status to another.
     3657     *
     3658     * @since 2.3.0
     3659     *
     3660     * @param string  $new_status New post status.
     3661     * @param string  $old_status Old post status.
     3662     * @param WP_Post $post       Post object.
     3663     */
     3664    do_action( 'transition_post_status', $new_status, $old_status, $post );
     3665
     3666    /**
     3667     * Fires when a post is transitioned from one status to another.
     3668     *
     3669     * The dynamic portions of the hook name, $new_status and $old status,
     3670     * refer to the old and new post statuses, respectively.
     3671     *
     3672     * @since 2.3.0
     3673     *
     3674     * @param WP_Post $post Post object.
     3675     */
     3676    do_action( "{$old_status}_to_{$new_status}", $post );
     3677
     3678    /**
     3679     * Fires when a post is transitioned from one status to another.
     3680     *
     3681     * The dynamic portions of the hook name, $new_status and $post->post_type,
     3682     * refer to the new post status and post type, respectively.
     3683     *
     3684     * @since 2.3.0
     3685     *
     3686     * @param int     $post_id Post ID.
     3687     * @param WP_Post $post    Post object.
     3688     */
     3689    do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );
    34513690}
    34523691
     
    34723711    $pung[] = $uri;
    34733712    $new = implode("\n", $pung);
    3474     $new = apply_filters('add_ping', $new);
     3713
     3714    /**
     3715     * Filter the new ping URL to add for the given post.
     3716     *
     3717     * @since 2.0.0
     3718     *
     3719     * @param string $new New ping URL to add.
     3720     */
     3721    $new = apply_filters( 'add_ping', $new );
     3722
    34753723    // expected_slashed ($new)
    34763724    $new = wp_unslash($new);
     
    35003748        }
    35013749    }
    3502     $pung = apply_filters('get_enclosed', $pung, $post_id);
     3750
     3751    /**
     3752     * Filter the list of enclosures already enclosed for the given post.
     3753     *
     3754     * @since 2.0.0
     3755     *
     3756     * @param array $pung    Array of enclosures for the given post.
     3757     * @param int   $post_id Post ID.
     3758     */
     3759    $pung = apply_filters( 'get_enclosed', $pung, $post_id );
    35033760    return $pung;
    35043761}
     
    35183775    $pung = trim($pung);
    35193776    $pung = preg_split('/\s/', $pung);
    3520     $pung = apply_filters('get_pung', $pung);
     3777
     3778    /**
     3779     * Filter the list of already-pinged URLs for the given post.
     3780     *
     3781     * @since 2.0.0
     3782     *
     3783     * @param array $pung Array of URLs already pinged for the given post.
     3784     */
     3785    $pung = apply_filters( 'get_pung', $pung );
    35213786    return $pung;
    35223787}
     
    35363801    $to_ping = sanitize_trackback_urls( $to_ping );
    35373802    $to_ping = preg_split('/\s/', $to_ping, -1, PREG_SPLIT_NO_EMPTY);
    3538     $to_ping = apply_filters('get_to_ping',  $to_ping);
     3803
     3804    /**
     3805     * Filter the list of URLs yet to ping for the given post.
     3806     *
     3807     * @since 2.0.0
     3808     *
     3809     * @param array $to_ping List of URLs yet to ping.
     3810     */
     3811    $to_ping = apply_filters( 'get_to_ping', $to_ping );
    35393812    return $to_ping;
    35403813}
     
    38994172        // Convert to WP_Post instances
    39004173        $pages = array_map( 'get_post', $cache );
    3901         $pages = apply_filters('get_pages', $pages, $r);
     4174        /** This filter is documented in wp-includes/post.php */
     4175        $pages = apply_filters( 'get_pages', $pages, $r );
    39024176        return $pages;
    39034177    }
     
    40294303
    40304304    if ( empty($pages) ) {
    4031         $pages = apply_filters('get_pages', array(), $r);
     4305        /** This filter is documented in wp-includes/post.php */
     4306        $pages = apply_filters( 'get_pages', array(), $r );
    40324307        return $pages;
    40334308    }
     
    40714346    $pages = array_map( 'get_post', $pages );
    40724347
    4073     $pages = apply_filters('get_pages', $pages, $r);
     4348    /**
     4349     * Filter the retrieved list of pages.
     4350     *
     4351     * @since 2.1.0
     4352     *
     4353     * @param array $pages List of pages to retrieve.
     4354     * @param array $r     Array of get_pages() arguments.
     4355     */
     4356    $pages = apply_filters( 'get_pages', $pages, $r );
    40744357
    40754358    return $pages;
     
    41334416 * @since 2.0.0
    41344417 * @uses $wpdb
    4135  * @uses do_action() Calls 'edit_attachment' on $post_ID if this is an update.
    4136  * @uses do_action() Calls 'add_attachment' on $post_ID if this is not an update.
    41374418 *
    41384419 * @param string|array $object Arguments to override defaults.
     
    42974578
    42984579    if ( $update) {
    4299         do_action('edit_attachment', $post_ID);
     4580        /**
     4581         * Fires once an existing attachment has been updated.
     4582         *
     4583         * @since 2.0.0
     4584         *
     4585         * @param int $post_ID Attachment ID.
     4586         */
     4587        do_action( 'edit_attachment', $post_ID );
    43004588    } else {
    4301         do_action('add_attachment', $post_ID);
     4589
     4590        /**
     4591         * Fires once an attachment has been added.
     4592         *
     4593         * @since 2.0.0
     4594         *
     4595         * @param int $post_ID Attachment ID.
     4596         */
     4597        do_action( 'add_attachment', $post_ID );
    43024598    }
    43034599
     
    43174613 * @since 2.0.0
    43184614 * @uses $wpdb
    4319  * @uses do_action() Calls 'delete_attachment' hook on Attachment ID.
    43204615 *
    43214616 * @param int $post_id Attachment ID.
     
    43514646        delete_transient( 'dirsize_cache' );
    43524647
    4353     do_action('delete_attachment', $post_id);
     4648    /**
     4649     * Fires before an attachment is deleted, at the start of wp_delete_attachment().
     4650     *
     4651     * @since 2.0.0
     4652     *
     4653     * @param int $post_id Attachment ID.
     4654     */
     4655    do_action( 'delete_attachment', $post_id );
    43544656
    43554657    wp_delete_object_term_relationships($post_id, array('category', 'post_tag'));
     
    43664668        delete_metadata_by_mid( 'post', $mid );
    43674669
     4670    /** This action is documented in wp-includes/post.php */
    43684671    do_action( 'delete_post', $post_id );
    43694672    $result = $wpdb->delete( $wpdb->posts, array( 'ID' => $post_id ) );
     
    43714674        return false;
    43724675    }
     4676    /** This action is documented in wp-includes/post.php */
    43734677    do_action( 'deleted_post', $post_id );
    43744678
     
    43804684            $thumbfile = str_replace(basename($file), $meta['thumb'], $file);
    43814685            /** This filter is documented in wp-admin/custom-header.php */
    4382             $thumbfile = apply_filters('wp_delete_file', $thumbfile);
     4686            $thumbfile = apply_filters( 'wp_delete_file', $thumbfile );
    43834687            @ unlink( path_join($uploadpath['basedir'], $thumbfile) );
    43844688        }
     
    43964700            $del_file = path_join( dirname($meta['file']), $size['file'] );
    43974701            /** This filter is documented in wp-admin/custom-header.php */
    4398             $del_file = apply_filters('wp_delete_file', $del_file);
     4702            $del_file = apply_filters( 'wp_delete_file', $del_file );
    43994703            @ unlink( path_join($uploadpath['basedir'], $del_file) );
    44004704        }
     
    44024706
    44034707    /** This filter is documented in wp-admin/custom-header.php */
    4404     $file = apply_filters('wp_delete_file', $file);
     4708    $file = apply_filters( 'wp_delete_file', $file );
    44054709
    44064710    if ( ! empty($file) )
     
    44314735        return $data;
    44324736
     4737    /**
     4738     * Filter the attachment meta data.
     4739     *
     4740     * @since 2.1.0
     4741     *
     4742     * @param array|bool $data    Array of meta data for the given attachment, or false
     4743     *                            if the object does not exist.
     4744     * @param int        $post_id Attachment ID.
     4745     */
    44334746    return apply_filters( 'wp_get_attachment_metadata', $data, $post->ID );
    44344747}
     
    44484761        return false;
    44494762
     4763    /**
     4764     * Filter the updated attachment meta data.
     4765     *
     4766     * @since 2.1.0
     4767     *
     4768     * @param array $data    Array of updated attachment meta data.
     4769     * @param int   $post_id Attachment ID.
     4770     */
    44504771    if ( $data = apply_filters( 'wp_update_attachment_metadata', $data, $post->ID ) )
    44514772        return update_post_meta( $post->ID, '_wp_attachment_metadata', $data );
     
    44854806        $url = get_the_guid( $post->ID );
    44864807
     4808    /**
     4809     * Filter the attachment URL.
     4810     *
     4811     * @since 2.1.0
     4812     *
     4813     * @param string $url     URL for the given attachment.
     4814     * @param int    $post_id Attachment ID.
     4815     */
    44874816    $url = apply_filters( 'wp_get_attachment_url', $url, $post->ID );
    44884817
     
    45104839    $file = get_attached_file( $post->ID );
    45114840
    4512     if ( !empty($imagedata['thumb']) && ($thumbfile = str_replace(basename($file), $imagedata['thumb'], $file)) && file_exists($thumbfile) )
     4841    if ( !empty($imagedata['thumb']) && ($thumbfile = str_replace(basename($file), $imagedata['thumb'], $file)) && file_exists($thumbfile) ) {
     4842        /**
     4843         * Filter the attachment thumbnail file path.
     4844         *
     4845         * @since 2.1.0
     4846         *
     4847         * @param string $thumbfile File path to the attachment thumbnail.
     4848         * @param int    $post_id   Attachment ID.
     4849         */
    45134850        return apply_filters( 'wp_get_attachment_thumb_file', $thumbfile, $post->ID );
     4851    }
    45144852    return false;
    45154853}
     
    45394877    $url = str_replace(basename($url), basename($thumb), $url);
    45404878
     4879    /**
     4880     * Filter the attachment thumbnail URL.
     4881     *
     4882     * @since 2.1.0
     4883     *
     4884     * @param string $url     URL for the attachment thumbnail.
     4885     * @param int    $post_id Attachment ID.
     4886     */
    45414887    return apply_filters( 'wp_get_attachment_thumb_url', $url, $post->ID );
    45424888}
     
    46034949
    46044950        if ( !is_array($icon_files) ) {
     4951            /**
     4952             * Filter the icon directory path.
     4953             *
     4954             * @since 2.0.0
     4955             *
     4956             * @param string $path Icon directory absolute path.
     4957             */
    46054958            $icon_dir = apply_filters( 'icon_dir', ABSPATH . WPINC . '/images/media' );
    4606             $icon_dir_uri = apply_filters( 'icon_dir_uri', includes_url('images/media') );
    4607             $dirs = apply_filters( 'icon_dirs', array($icon_dir => $icon_dir_uri) );
     4959
     4960            /**
     4961             * Filter the icon directory URI.
     4962             *
     4963             * @since 2.0.0
     4964             *
     4965             * @param string $uri Icon directory URI.
     4966             */
     4967            $icon_dir_uri = apply_filters( 'icon_dir_uri', includes_url( 'images/media' ) );
     4968
     4969            /**
     4970             * Filter the list of icon directory URIs.
     4971             *
     4972             * @since 2.5.0
     4973             *
     4974             * @param array $uris List of icon directory URIs.
     4975             */
     4976            $dirs = apply_filters( 'icon_dirs', array( $icon_dir => $icon_dir_uri ) );
    46084977            $icon_files = array();
    46094978            while ( $dirs ) {
     
    46525021    }
    46535022
    4654     return apply_filters( 'wp_mime_type_icon', $icon, $mime, $post_id ); // Last arg is 0 if function pass mime type.
     5023    /**
     5024     * Filter the mime type icon.
     5025     *
     5026     * @since 2.1.0
     5027     *
     5028     * @param string $icon    Path to the mime type icon.
     5029     * @param string $mime    Mime type.
     5030     * @param int    $post_id Attachment ID. Will equal 0 if the function passed
     5031     *                        the mime type.
     5032     */
     5033    return apply_filters( 'wp_mime_type_icon', $icon, $mime, $post_id );
    46555034}
    46565035
     
    47325111        return $full ? 'WHERE 1 = 0' : ' 1 = 0 ';
    47335112
    4734     // This hook is deprecated. Why you'd want to use it, I dunno.
    4735     if ( ! $cap = apply_filters( 'pub_priv_sql_capability', '' ) )
     5113    /**
     5114     * Filter the capability to read private posts for a custom post type
     5115     * when generating SQL for getting posts by author.
     5116     *
     5117     * @since 2.2.0
     5118     * @deprecated 3.2.0 The hook transitioned from "somewhat useless" to "totally useless".
     5119     *
     5120     * @param string $cap Capability.
     5121     */
     5122    if ( ! $cap = apply_filters( 'pub_priv_sql_capability', '' ) ) {
    47365123        $cap = $post_type_obj->cap->read_private_posts;
     5124    }
    47375125
    47385126    if ( $full ) {
     
    47785166 * @since 0.71
    47795167 *
    4780  * @uses apply_filters() Calls 'get_lastpostdate' filter
    4781  *
    47825168 * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
    47835169 * @return string The date of the last post.
    47845170 */
    47855171function get_lastpostdate($timezone = 'server') {
     5172    /**
     5173     * Filter the date the last post was published.
     5174     *
     5175     * @since 2.3.0
     5176     *
     5177     * @param string $date     Date the last post was published. Likely values are 'gmt',
     5178     *                         'blog', or 'server'.
     5179     * @param string $timezone Location to use for getting the post published date.
     5180     */
    47865181    return apply_filters( 'get_lastpostdate', _get_last_post_time( $timezone, 'date' ), $timezone );
    47875182}
     
    47955190 *
    47965191 * @since 1.2.0
    4797  * @uses apply_filters() Calls 'get_lastpostmodified' filter
    47985192 *
    47995193 * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
     
    48075201        $lastpostmodified = $lastpostdate;
    48085202
     5203    /**
     5204     * Filter the date the last post was modified.
     5205     *
     5206     * @since 2.3.0
     5207     *
     5208     * @param string $lastpostmodified Date the last post was modified.
     5209     * @param string $timezone         Location to use for getting the post modified date.
     5210     */
    48095211    return apply_filters( 'get_lastpostmodified', $lastpostmodified, $timezone );
    48105212}
     
    48845286 * @since 2.0.0
    48855287 *
    4886  * @uses do_action() Calls 'clean_post_cache' on $id before adding children (if any).
    4887  *
    48885288 * @param int|WP_Post $post Post ID or post object to remove from the cache.
    48895289 */
     
    49055305    wp_cache_delete( 'wp_get_archives', 'general' );
    49065306
     5307    /**
     5308     * Fires immediately after the given post's cache is cleaned.
     5309     *
     5310     * @since 2.5.0
     5311     *
     5312     * @param int     $post_id Post ID.
     5313     * @param WP_Post $post    Post object.
     5314     */
    49075315    do_action( 'clean_post_cache', $post->ID, $post );
    49085316
     
    49125320    if ( 'page' == $post->post_type ) {
    49135321        wp_cache_delete( 'all_page_ids', 'posts' );
     5322
     5323        /**
     5324         * Fires immediately after the given page's cache is cleaned.
     5325         *
     5326         * @since 2.5.0
     5327         *
     5328         * @param int $post_id Post ID.
     5329         */
    49145330        do_action( 'clean_page_cache', $post->ID );
    49155331    }
     
    49935409 * @since 3.0.0
    49945410 *
    4995  * @uses do_action() Calls 'clean_attachment_cache' on $id.
    4996  *
    49975411 * @param int $id The attachment ID in the cache to clean
    49985412 * @param bool $clean_terms optional. Whether to clean terms cache
     
    50125426        clean_object_term_cache($id, 'attachment');
    50135427
    5014     do_action('clean_attachment_cache', $id);
     5428    /**
     5429     * Fires after the given attachment's cache is cleaned.
     5430     *
     5431     * @since 3.0.0
     5432     *
     5433     * @param int $id Attachment ID.
     5434     */
     5435    do_action( 'clean_attachment_cache', $id );
    50155436}
    50165437
     
    50255446 * @access private
    50265447 * @uses $wpdb
    5027  * @uses do_action() Calls 'private_to_published' on post ID if this is a 'private_to_published' call.
    50285448 * @uses wp_clear_scheduled_hook() with 'publish_future_post' and post ID.
    50295449 *
     
    50395459        if ( '' == get_the_guid($post->ID) )
    50405460            $wpdb->update( $wpdb->posts, array( 'guid' => get_permalink( $post->ID ) ), array( 'ID' => $post->ID ) );
    5041         do_action('private_to_published', $post->ID);  // Deprecated, use private_to_publish
     5461
     5462        /**
     5463         * Fires when a post's status is transitioned from private to published.
     5464         *
     5465         * @since 1.5.0
     5466         * @deprecated 2.3.0 Use 'private_to_publish' instead.
     5467         *
     5468         * @param int $post_id Post ID.
     5469         */
     5470        do_action('private_to_published', $post->ID);
    50425471    }
    50435472
     
    50835512 * @access private
    50845513 * @uses XMLRPC_REQUEST and WP_IMPORTING constants.
    5085  * @uses do_action() Calls 'xmlrpc_publish_post' on post ID if XMLRPC_REQUEST is defined.
    50865514 *
    50875515 * @param int $post_id The ID in the database table of the post being published
    50885516 */
    50895517function _publish_post_hook($post_id) {
    5090     if ( defined('XMLRPC_REQUEST') )
    5091         do_action('xmlrpc_publish_post', $post_id);
     5518    if ( defined( 'XMLRPC_REQUEST' ) ) {
     5519        /**
     5520         * Fires when _publish_post_hook() is called during an XML-RPC request.
     5521         *
     5522         * @since 2.1.0
     5523         *
     5524         * @param int $post_id Post ID.
     5525         */
     5526        do_action( 'xmlrpc_publish_post', $post_id );
     5527    }
    50925528
    50935529    if ( defined('WP_IMPORTING') )
Note: See TracChangeset for help on using the changeset viewer.