[wp-hackers] Incorrect documentation for register_post_status

[J.D. Grimes]

Take a look at the registration of the core post types: https://core.trac.wordpress.org/browser/trunk/src/wp-includes/post.php#L111

public => true is used for publish.
protected => true is used for future, draft, and pending. 
private => true is used for private.
internal => true is used for trash, auto-draft, and inherit.

So the protected property means that a post status shouldn’t be visible on the front end to users without the required caps. In other words, it would make the status behave like a draft or pending post.

The docs should be updated to say that a post status should be registered with one of these set to true. They basically represent a ‘visibility’ property for the status, but instead they are each a separate property (but they probably shouldn’t have been, IMHO). I think it is intended that one of them should always be used, and not more than one.

-J.D.

On Jul 7, 2014, at 7:43 AM, Nikola Nikolov <nikolov.tmw at gmail.com> wrote:

> That's the thing - I don't want posts with that status to be public.
> 
> However, in theory(according to the documentation), setting
> "show_in_admin_all_list" to true should make posts with that post status
> visible in the "All" section of the posts list.
> 
> What I'm not sure about is what the "protected" property of a post status
> is used for.
> 
> 
> On Mon, Jul 7, 2014 at 10:26 AM, Pascal Birchler <pascal.birchler at gmail.com>
> wrote:
> 
>> How does your code look like? It seems like setting the `public` argument
>> to true should be enough. See the lines above:
>> 
>> https://github.com/WordPress/WordPress/blob/3.9-branch/wp-includes/query.php#L2810
>> 
>> 
>> 2014-07-04 15:38 GMT+02:00 Nikola Nikolov <nikolov.tmw at gmail.com>:
>> 
>>> I had to add a new custom post status and so I looked-up the
>> documentation
>>> for the register_post_status()
>>> <http://codex.wordpress.org/Function_Reference/register_post_status>
>>> function and adjusted the sample code from there.
>>> 
>>> I found a way to add the post status to the status drop-down on the
>>> add/edit posts screens and changed the status of one of the posts.
>>> 
>>> It all worked as expected - the post status was now updated for that
>> post.
>>> 
>>> Then I went back to the posts screen for my custom post type and I saw
>> the
>>> post status link on top, showing me that there's 1 post with that post
>>> status. That's also correct.
>>> 
>>> However the post disappeared from the list of posts, even though I've set
>>> "show_in_admin_all_list" to true in the arguments for the post status.
>>> 
>>> So I looked around and found out that in /wp-includes/query.php on line
>>> #2819
>>> <
>>> 
>> https://github.com/WordPress/WordPress/blob/3.9-branch/wp-includes/query.php#L2819
>>>> 
>>> ,
>>> WordPress is getting registered post statuses with
>> show_in_admin_all_list =
>>> true AND protected = true
>>> 
>>> The *protected* argument is not documented anywhere, but after I set that
>>> to true in my arguments list, the post appeared again.
>>> 
>>> I would go in and document that myself, but I really have no clue what
>>> *protected* is used for and I don't want to advise people to add it in
>> just
>>> because it works.
>>> 
>>> If anyone has more insight, I'd be happy to hear it.
>>> 
>>> Nikola
>>> _______________________________________________
>>> wp-hackers mailing list
>>> wp-hackers at lists.automattic.com
>>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>>> 
>> _______________________________________________
>> wp-hackers mailing list
>> wp-hackers at lists.automattic.com
>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>> 
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers