Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add TimezoneChange XML doc #1731

Merged
merged 2 commits into from
Jun 4, 2022
Merged

Docs: Add TimezoneChange XML doc #1731

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b91ac6c
Docs: Add TimezoneChange XML doc
GaryJones Jun 20, 2019
c6e560b
Docs: Refresh restricted datetime functions docs
GaryJones Mar 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions WordPress/Docs/DateTime/RestrictedFunctionsStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
<documentation title="Restricted Date and Time Functions">
<standard>
<![CDATA[
The restricted functions date_default_timezone_set() and date() should not be used.
]]>
</standard>
<standard>
<![CDATA[
Using the PHP native date_default_timezone_set() function isn't allowed, because WordPress Core needs the default time zone to be set to UTC for timezone calculations using the WP Core API to work correctly.
]]>
</standard>
<code_comparison>
<code title="Valid: Using DateTime object.">
<![CDATA[
$date = new <em>DateTime()</em>;
$date->setTimezone(
new DateTimeZone( 'Europe/Amsterdam' )
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be an idea to "WordPressify" this code sample a little more and use something like get_option() with gmt_offset or timezone_string to retrieve the timezone to be passed to new DateTimeZone() ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the basic PHP example is fine there, people tend to change default time zone to something that is not normal WP time zone.

Again, there is a problem of choice between a technical 1:1 code equivalent and idiomatic rewrite, that is hard to decide on for brief out-of-context example.

);
]]>
</code>
<code title="Invalid: Using date_default_timezone_set().">
<![CDATA[
<em>date_default_timezone_set</em>( 'Europe/Amsterdam' );
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Using the PHP native date() function isn't allowed, as it is affected by runtime timezone changes which can cause the date/time to be incorrectly displayed. Use gmdate() instead.
]]>
</standard>
<code_comparison>
<code title="Valid: Using gmdate().">
<![CDATA[
$last_updated = <em>gmdate</em>(
'Y-m-d\TH:i:s',
strtotime( $plugin['last_updated'] )
);
]]>
</code>
<code title="Invalid: Using date().">
<![CDATA[
$last_updated = <em>date</em>(
'Y-m-d\TH:i:s',
strtotime( $plugin['last_updated'] )
);
]]>
</code>
</code_comparison>
</documentation>