Easier expression of time periods

[nbachiyski]

Numbers are cool. But sometimes they stand in the way of what we have to say.

set_transient( 'plugin_slugs', $plugin_slugs, 86400 );

From the context it's obvious that 86400 is a time period and with some calculation we can see it's 24 hours/1 day in seconds. Of course, it's not very readable, so usually in the code we see a clarifying comment:

// 1 day

This definitely helps. But we could do better. We can make the whole thing read naturally in English:

set_transient( 'plugin_slugs', $plugin_slugs, DAY_IN_SECONDS );

This way we get all the information we need – we know the transient is set for one day, we can read this in plain English and we don't need to spare extra cycles to either make mathematical calculations or wait to the end of the line to see the actual period in the comment.

In the patch is attached a new file time-constants.php which contains a couple of constants.

All of them follow the pattern: <SINGULAR_OF_TIME_UNIT>_IN_<PLURAL_OF_TIME_UNIT>.

For now there are only *_IN_SECONDS and *_IN_MINUTES, since that's what we found useful on WordPress.com.

Pretty neat!

+1. Also, perhaps these constants can go in default-constants.php.

20987.patch​ is an attempt to use the constants throughout the core.

We could also probably mention them in wp_get_schedules() description:
http://core.trac.wordpress.org/browser/tags/3.4.1/wp-includes/cron.php#L284

More instances in 20987.2.patch​.

Looks like only *_IN_SECONDS have actual use cases in core.

Sergey, thanks for the awesome patch, it's a tremendous help.

The only change I would make to your patch is to replace DAY_IN_SECONDS / 2 with 12 * HOUR_IN_SECONDS. It just feels more natural to me and everywhere else we refer to it as 12 hours, not half a day.

About the minutes – westi found some use for them in the WordPress.com codebase, and I think they would do no harm.

Any objections if we just commit that?

Replying to nbachiyski:

The only change I would make to your patch is to replace DAY_IN_SECONDS / 2 with 12 * HOUR_IN_SECONDS.

Thanks, done in 20987.3.patch​.

I understand the case for SECONDS but not as much for MINUTES, as they serve no use in core, nor much of an obvious use in general.

I'm also not a fan of MONTH_IN_SECONDS, as month lengths are variously 28-31 days. (A year is at least generally 365 days in length.) We also have no use for it in core.

MONTH_IN_SECONDS is not used indeed. 20987.4.patch​ excludes it as well as *_IN_MINUTES.

In [21996]:

Introduce constants to allow for easier expression of time periods in seconds. Adds MINUTE_IN_SECONDS, HOUR_IN_SECONDS, DAY_IN_SECONDS, WEEK_IN_SECONDS, YEAR_IN_SECONDS. props nbachiyski, SergeyBiryukov. fixes #20987.

In [21997]:

Do not use time constants in files the WP bootstrap is not or may not be loaded. see #20987.

Nice :-)

Their names are extremely generic. Could those constants please be prefixed with WP_*? Else it's hard to determine where they belong when you got autocomplete in your IDE and using another system along WP.

I found some more examples, see attached patch.

In [22121]:

Use 2 * DAY_IN_SECONDS rather than 172800. props pavelevap. fixes #20987.

20987.5.patch​ adds a comment for [21997] and fixes a typo.

In 22531:

Add comments to time intervals we cannot express with the constants. Fix a comment. props SergeyBiryukov. fixes #20987.