Add clearer guidance for filter return values

[dgw]

Pre-requisites

• I have read the Contributing Guidelines
• I am using AI and have read the AI Policy

Change Description

This is my attempt at addressing @ozh's documentation suggestion in YOURLS/dont-log-bots#5 (comment)

I was trying to get it done fairly quickly in between things IRL, so I'm sure there's room for improvement. But the important thing is having an open PR at all, reminding us to address the documentation gap. 🙂

[dgw]

@LeoColomb The build succeeded when the lint was failing, and now the build is failing after linter auto-fixes (to text I didn't touch, fwiw). Would appreciate you taking a look when you have a minute!

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	website	a6649af	Commit Preview URL Branch Preview URL	Aug 18 2026, 07:43 PM

[ozh]

Hey,

a bit late into the conversation -- thanks @dgw for proposing this documentation improvement

I have a suggestion for the shunt code sample: instead of

yourls_add_filter('shunt_update_clicks', 'yp_dont_log_conditional');
yourls_add_filter('shunt_log_redirect', 'yp_dont_log_conditional');

function yp_dont_log_conditional($value = yourls_shunt_default()) {
    if (yp_dont_log_conditions_match()) {
        return true;
    }
    return $value;
}

simply

yourls_add_filter('shunt_update_clicks', 'yp_dont_log_conditional');
yourls_add_filter('shunt_log_redirect', 'yp_dont_log_conditional');

function yp_dont_log_conditional( $dont_shunt ) {
    if (yp_dont_log_conditions_match()) {
        return true;
    }
    return $dont_shunt;
}

Bigger improvement: the function doesn't rely on 1.10.4+ yourls_shunt_default() so it's fully compatible with older installs. Shunt filter function don't need a default value since they are guaranteed to get a defined value.

Little improvement: naming the param $dont_shunt might make it more explicit that if conditions are not met in your filter function, you return something that does not shunt.

Thoughts ?

[dgw]

Good point about <1.10.4, and not needing a default value.

How about $original_value for the param name? I think it'd flow nicer in the prose that mentions it than trying to word around the name $dont_shunt.

Lemme open another PR with these tweaks as separate commits and we can continue there.

[ozh]

Yes $original_value is maybe nicer