pre_comment_approved, return values

I did some more research, but I still cannot find what is going on. I found out about a problem with akismet and the pre_comment_approved filter but Akismet is off.

This is my actual code:

function check_for_spam( $approved, $commentdata ) {
	if( !empty( $commentdata['comment_author_url'] ) ) {
		return 0; // disapproved
	}
	return $approved;
}
add_filter('pre_comment_approved', 'check_for_spam', '99', 2);

This code is in functions.php and when I add a comment with a URL the comment makes it into the database and I receive a “Please moderate” e-mail.
I would think a return of 0 means that the comment is ignored, no e-mail is sent and it certainly is not in the database. Or am I wrong??

If I return ‘spam’ everything works as expected. There is no e-mail and the comment is stored in the database, and can be found in the spam bin when in admin.

Can anyone shed some light on this?

The Codex is correct. Legal values are 0, 1, ‘spam’. A value of false or true in the DB is improper and needs to be corrected or the row deleted via phpMyAdmin. 0 means a moderator should look at the comment because WP is not sure about it. The author and/or admin gets notification. 1 means the comment is vetted and will be displayed immediately. ‘spam’ means the comment goes straight to the “spam folder”. All comments at this point will go to the DB, the value of ‘comment_approved’ dictates how the comment is displayed and what sort of notification is sent.

Certain conditions cause a wp_die() message before reaching the filter, such as a flood condition. In those cases the comment actually is discarded, though the user can recover the input values with their back button. If you desire some other functionality, it should be possible by hooking appropriate filters.

@bcworkz:
Thanks very much for your clear answer. The codex is rather vague about what the return codes actually do. The text “0 (i.e. ‘false’) if the comment should be disapproved” can mean a number of things. Maybe the codex page should be edited. Is this something you are willing to do? I have never done this before, but am willing to give it a shot if you are busy.

Today I did some more digging and apparently there is no way to use the filter to prevent the comment from making it into the DB. The three return codes 0, 1 and ‘spam’ all result in the comment being stored in one way or another. This filter seems to be the right spot to evaluate a comment and if it is not OK, just ignore it. That is why I put in a request in trac today to see if this (a fourth return code) is something that could be added to core.

Thanks again. I learned a lot about the comment system that was not obvious to see.

I actually tried to make the Codex page more clear some time ago! It was even worse before. The problem is that it seems no matter how you phrase the return value description, someone takes it the wrong way. For one thing, the 0 and 1 values returned are integer values, not text strings. Only the ‘spam’ value is a string. I can see specifying the data types would be useful information.

It’s not clear to many people that a 0 value is interpreted as false in PHP. Maybe that’s the problem, it’s not a true boolean where 0 and false are equivalent. If not worded carefully, people will try to return false (bool) or even ‘false’ (string) and not 0 (int). Maybe true and false should not be mentioned at all. Maybe it should read: “0 (int) comment will be set to be moderated”, etc. What do you think?

I would be pleased to alter the Codex if the result makes things clearer. As it stands, the only way to prevent the comment from being entered in the DB is to kill the process in the filter with wp_die(). Not very elegant, but achieves the purpose.

I think your suggestion is right: “0 (int) comment will be set to be moderated” is the right wording. It makes it obvious what the return values are. I got it from the text as it is, but I am sure things can be misinterpreted. Actually, I know that is the case, as I have seen coding examples where people returned false or true (boolean). Since things didn’t work as expected I tried some variations, just to see what happens, and partly because of the current wording. So mentioning true and false might be misleading.

Your suggestion about wp_die() is indeed what I am doing now. I do not ask for a URL in the comment form, but all spambots try to fill it in. So checking for the URL field is a good way to block spambots. A rather crude solution, but it works…

Thanks for thinking with me on this!

I just updated the Codex page. I don’t know how to make it any more clearer now ?? Your comments in this regard were most helpful, thanks!

A job well done. Thanks for the cooperation.

…and on to new adventures.