PHP Wiki

intl_date_format

sepehrphp (sepehrphp@undisclosed.example.com) — 2026-09-28T13:04:09+00:00

2026/09/27 18:39		current
Line 1:		Line 1:
-	====== PHP RFC: intl_date_format() ======	+	====== PHP RFC: intl_date_format ======
-	* Version: 1.0	+
-	* Date: 2026-09-27	+	* Version: 1.0
-	* Author: Sepehr Mahmoudi <sepehrphpr@gmail.com>	+	* Date: 2026-09-28
-	* Target Version: PHP 8.7	+	* Author: Sepehr Mahmoudi (sepehrphpr@gmail.com)
-	* Status: Draft	+	* Target Version: PHP 8.7
-	* First Published at: https://wiki.php.net/rfc/intl_date_format	+	* Status: Draft

	===== Introduction =====		===== Introduction =====
		+	This proposal introduces a new procedural function ''intl_date_format()'' to the ''ext/intl'' extension. The goal is to provide a simplified, developer-friendly interface for formatting date and time using ''IntlDateFormatter'''s capabilities, without the overhead of instantiating and configuring objects for simple use cases.

-	This RFC proposes adding a new function ''intl_date_format()'' to the ''intl'' extension that provides a simple, unified interface for formatting dates across different calendar systems (Gregorian, Persian, Islamic, etc.) using ICU's calendar capabilities.	+	===== Motivation =====
-		+	Currently, using ''IntlDateFormatter'' for standard formatting requires significant boilerplate code: instantiating an object, setting the timezone and calendar, and finally calling the ''format'' method. Adding a procedural function, similar to the core ''date()'' function, will improve ergonomics and development speed for internationalized applications.
-	Currently, PHP developers must manually instantiate ''IntlDateFormatter'' and configure calendar types through locale strings or setter methods. This RFC introduces a procedural function that simplifies calendar-aware date formatting for common use cases.	+
-		+
-	===== Proposal =====	+
-		+
-	Add a new function to the ''intl'' extension:	+

		+	===== Proposed Function Signature =====
	<code php>		<code php>
	function intl_date_format(		function intl_date_format(
-	string\|int $date,	+	DateTimeInterface\|int\|string\|float $datetime,
-	string $calendar = 'gregorian',	+	?string $locale = null,
-	string $locale = 'en_US',	+	int $dateType = IntlDateFormatter::MEDIUM,
-	string $pattern = 'yyyy/MM/dd'	+	int $timeType = IntlDateFormatter::MEDIUM,
-	): string\|false	+	IntlTimeZone\|DateTimeZone\|string\|null $timezone = null,
		+	IntlCalendar\|int\|null $calendar = null,
		+	string $pattern = ""
		+	): string {}
	</code>		</code>

-	==== Parameters ====	+	===== Parameters =====
		+	* ''$datetime'': The date/time to format. Can be a ''DateTimeInterface'' object, a Unix timestamp (int/float), or a valid date string.
		+	* ''$locale'': The locale to use (e.g., ''fa_IR'', ''en_US''). If ''null'', the default system locale is used.
		+	* ''$dateType'': The date formatter constant (e.g., ''IntlDateFormatter::MEDIUM'').
		+	* ''$timeType'': The time formatter constant (e.g., ''IntlDateFormatter::MEDIUM'').
		+	* ''$timezone'': The timezone. Can be a ''DateTimeZone'' object, ''IntlTimeZone'' object, or a string identifier.
		+	* ''$calendar'': The calendar type (e.g., ''IntlDateFormatter::TRADITIONAL'').
		+	* ''$pattern'': An optional ICU pattern string. If provided, this overrides the ''$dateType'' and ''$timeType'' arguments.

-	* ''$date'' (''string\|int'', required)	+	===== Error Handling =====
-	* Unix timestamp as integer (e.g., ''time()'', ''strtotime()'')	+	This function adheres to modern PHP 8.7 error handling standards:
-	* ISO 8601 date string (e.g., ''2026-09-27'' or ''2026-09-27T14:30:00Z'')	+	* ''TypeError'': Thrown if invalid data types are passed for any parameter.
-	* When an integer is provided, it represents seconds since Unix epoch	+	* ''ValueError'': Thrown if invalid numerical values are passed for constants.
-	* ICU internally converts timestamps to milliseconds for processing	+	* ''IntlException'': Thrown if the underlying ICU engine encounters an error during formatting.
-		+	* The function will always return a ''string'' on success and will never return ''false''.
-	* ''$calendar'' (''string'', optional, default: ''gregorian'')	+
-	* Calendar system identifier for date formatting	+
-	* Supported values: ''gregorian'', ''persian'', ''islamic'', ''islamic-civil'', ''japanese'', ''buddhist'', ''chinese'', ''indian'', ''coptic'', ''ethiopic'', ''hebrew''	+
-	* The function automatically appends ''@calendar=<value>'' to the locale string	+
-	* Invalid calendar names will trigger an error	+
-		+
-	* ''$locale'' (''string'', optional, default: ''en_US'')	+
-	* ICU locale identifier (e.g., ''fa_IR'', ''ar_SA'', ''en_US'', ''de_DE'')	+
-	* Controls language, number formatting, and regional conventions	+
-	* Should not include ''@calendar='' suffix (handled automatically by the function)	+
-	* Invalid locale will fall back to ''en_US'' with a warning	+
-		+
-	* ''$pattern'' (''string'', optional, default: ''yyyy/MM/dd'')	+
-	* ICU date format pattern defining output structure	+
-	* Common pattern symbols:	+
-	* ''yyyy'': 4-digit year, ''yy'': 2-digit year	+
-	* ''MM'': 2-digit month, ''MMM'': short month name, ''MMMM'': full month name	+
-	* ''dd'': 2-digit day, ''d'': day without leading zero	+
-	* ''EEEE'': full weekday name, ''EEE'': short weekday name	+
-	* ''HH'': 24-hour, ''hh'': 12-hour, ''mm'': minutes, ''ss'': seconds	+
-	* ''a'': AM/PM marker	+
-	* Full pattern syntax: [[https://unicode-org.github.io/icu/userguide/format_parse/datetime/\|ICU Date Format Patterns]]	+
-		+
-	==== Return Value ====	+
-		+
-	* Success: Returns the formatted date string according to the specified calendar, locale, and pattern	+
-	* Failure: Returns ''false'' and emits a warning when:	+
-	* Invalid date format (unparseable string or invalid timestamp)	+
-	* Unsupported or invalid calendar name	+
-	* ICU formatting error	+
-		+
-	==== Error Handling ====	+
-		+
-	The function follows PHP's standard error handling conventions for ''intl'' functions:	+
-		+
-	* **Invalid ''$date'': Returns ''false'' and emits ''E_WARNING''**	+
-	* Non-numeric string that cannot be parsed as ISO 8601	+
-	* Timestamp out of valid range	+
-		+
-	* **Invalid ''$calendar'': Returns ''false'' and emits ''E_WARNING''**	+
-	* Calendar name not recognized by ICU	+
-		+
-	* **Invalid ''$locale'': Emits ''E_WARNING'' and falls back to ''en_US''**	+
-	* Malformed locale identifier	+
-		+
-	* Invalid ''$pattern'': Returns ''false'' and emits ''E_WARNING''	+
-	* Malformed ICU pattern syntax	+
-		+
-	* ICU internal error: Returns ''false'' and emits ''E_WARNING''	+
-	* Detailed error message available via ''intl_get_error_message()''	+
-		+
-	Example error handling:	+
-		+
-	<code php>	+
-	<?php	+
-	$result = intl_date_format('invalid-date', 'persian', 'fa_IR');	+
-	if ($result === false) {	+
-	echo "Error: " . intl_get_error_message() . "\n";	+
-	echo "Error code: " . intl_get_error_code() . "\n";	+
-	}	+
-	?>	+
-	</code>	+

	===== Examples =====		===== Examples =====

-	==== Example 1: Persian (Jalali) Calendar ====	+	==== 1. Quick format with defaults ====
	<code php>		<code php>
-	<?php	+	echo intl_date_format(new DateTime(), 'fa_IR');
-	// Format current timestamp in Persian calendar	+	// Output example: ۷ مهر ۱۴۰۵، ۱۸:۳۰:۰۰
-	echo intl_date_format(time(), 'persian', 'fa_IR');	+
-	// Output: 1405/07/05	+
-		+
-	echo intl_date_format(time(), 'persian', 'fa_IR', 'd MMMM yyyy');	+
-	// Output: ۵ مهر ۱۴۰۵	+
-	?>	+
	</code>		</code>

-	==== Example 2: Islamic (Hijri) Calendar ====	+	==== 2. Full Persian date (no time) using Traditional calendar ====
	<code php>		<code php>
-	<?php	+	echo intl_date_format(
-	// Format specific date in Islamic calendar	+	datetime: '2026-09-28',
-	$date = '2026-09-27';	+	locale: 'fa_IR',
-	echo intl_date_format($date, 'islamic', 'ar_SA', 'd MMMM yyyy');	+	dateType: IntlDateFormatter::FULL,
-	// Output: ٢٤ ربيع الأول ١٤٤٨	+	timeType: IntlDateFormatter::NONE,
-		+	calendar: IntlDateFormatter::TRADITIONAL
-	echo intl_date_format($date, 'islamic-civil', 'en_US');	+	);
-	// Output: 1448/03/24	+	// Output example: دوشنبه ۷ مهر ۱۴۰۵
-	?>	+
	</code>		</code>

-	==== Example 3: Gregorian Calendar with Multiple Locales ====	+	==== 3. Timestamp with specific timezone ====
	<code php>		<code php>
-	<?php	+	echo intl_date_format(
-	$timestamp = strtotime('2026-09-27');	+	datetime: 1790610000,
-		+	locale: 'en_US',
-	// English	+	timezone: 'America/New_York'
-	echo intl_date_format($timestamp, 'gregorian', 'en_US', 'EEEE, MMMM d, yyyy');	+	);
-	// Output: Sunday, September 27, 2026	+	// Output example: Sep 28, 2026, 10:00:00 AM
-		+
-	// German	+
-	echo intl_date_format($timestamp, 'gregorian', 'de_DE', 'EEEE, d. MMMM yyyy');	+
-	// Output: Sonntag, 27. September 2026	+
-	?>	+
	</code>		</code>

-	==== Example 4: ISO 8601 String Input ====	+	==== 4. Using a custom pattern ====
	<code php>		<code php>
-	<?php	+	echo intl_date_format(
-	// Using ISO 8601 date string instead of timestamp	+	datetime: '2026-09-28 15:30:00',
-	$isoDate = '2026-09-27T14:30:00Z';	+	locale: 'fa_IR@calendar=persian',
-		+	pattern: 'yyyy/MM/dd'
-	echo intl_date_format($isoDate, 'persian', 'fa_IR', 'yyyy/MM/dd HH:mm');	+	);
-	// Output: 1405/07/05 14:30	+	// Output: ۱۴۰۵/۰۷/۰۷
-		+
-	echo intl_date_format($isoDate, 'gregorian', 'en_US', 'MMM d, yyyy h:mm a');	+
-	// Output: Sep 27, 2026 2:30 PM	+
-	?>	+
	</code>		</code>

-	===== Backward Incompatible Changes =====	+	===== Backward Compatibility =====
-		+	This is a new function and does not introduce any breaking changes.
-	None. This is a new function.	+
-		+
-	===== Proposed PHP Version(s) =====	+
-		+
-	PHP 8.7	+
-		+
-	===== RFC Impact =====	+
-		+
-	==== To SAPIs ====	+
-		+
-	None.	+
-		+
-	==== To Existing Extensions ====	+
-		+
-	This adds a new function to the existing ''intl'' extension. No changes to existing ''intl'' functions..	+
-		+
-	===== Unaffcache ====	+
-		+
-	None.	+
-		+
-	===== Open Issues =====	+
-		+
-	None at this time.	+
-		+
-	===== Unaffected PHP Functionality =====	+
-		+
-	* Existing ''IntlDateFormatter'' class remains unchanged	+
-	* All existing date/time functions (''date()'', ''strftime()'', etc.) are unaffected	+
-	* No changes to ''DateTime'' or ''DateTimeImmutable'' classes	+
-		+
-	===== Future Scope =====	+
-		+
-	* Add support for additional calendar systems as ICU expands	+
-	* Consider object-oriented wrapper class for advanced use cases	+
-	* Explore integration with ''DateTimeInterface'' for calendar conversion	+
-	* Potential ''intl_date_parse()'' function for reverse operation	+
-		+
-	===== Proposed Voting Choices =====	+

-	Accept ''intl_date_format()'' as proposed? Yes/No (requires 2/3 majority).	+	===== Performance =====
		+	To avoid overhead caused by frequently instantiating formatters in tight loops, the implementation utilizes an internal C-level LRU Cache to store and reuse formatter instances.

-	Voting opens: TBD
-	Voting closes: TBD (minimum 2

io_terminal - Clarify scope, implementation status, test coverage, and open issues

prateekbhujel (prateekbhujel@undisclosed.example.com) — 2026-09-28T09:56:50+00:00

2026/09/27 17:36		current
Line 92:		Line 92:
	final readonly class TerminalSize		final readonly class TerminalSize
	{		{
-	public readonly int $cols;	+	public int $cols;
-	public readonly int $rows;	+	public int $rows;

	private function __construct() {}		private function __construct() {}
Line 144:		Line 144:
	''Terminal::getSize()'' queries the size of the terminal associated with the output side of the session.		''Terminal::getSize()'' queries the size of the terminal associated with the output side of the session.

-	On success it returns a ''TerminalSize'' object containing the number of columns and rows. It returns ''false'' if a native terminal size cannot be obtained.	+	On success it returns a ''TerminalSize'' object containing the number of columns and rows. It returns ''false'' if a native terminal size cannot be obtained (including environments where dimensions report 0x0).

	No fallback to the ''COLUMNS'' or ''LINES'' environment variables is performed by this API.		No fallback to the ''COLUMNS'' or ''LINES'' environment variables is performed by this API.
Line 168:		Line 168:
	The optional ''$timeout'' controls how long the method waits for input. A ''null'' timeout waits indefinitely. A zero duration performs a non-blocking poll.		The optional ''$timeout'' controls how long the method waits for input. A ''null'' timeout waits indefinitely. A zero duration performs a non-blocking poll.

-	On POSIX, ''$sequenceTimeout'' controls the short wait used while reading multi-byte input and terminal escape sequences. If it is omitted, the implementation uses a 25 ms sequence timeout. Windows receives structured console input events and does not use this value.	+	On POSIX, ''$sequenceTimeout'' controls the short wait used while reading multi-byte input and terminal escape sequences. If it is omitted, the implementation defaults to a 25 ms sequence timeout for blocking reads, or 0 ms for non-blocking reads. Windows receives structured console input events and does not use this value.

	Both timeout parameters use ''Time\Duration''. Negative durations result in a ''ValueError''.		Both timeout parameters use ''Time\Duration''. Negative durations result in a ''ValueError''.
Line 178:		Line 178:
	Enter completes the input. Backspace removes the previous character. Escape, Ctrl+C, and Ctrl+D cancel the read.		Enter completes the input. Backspace removes the previous character. Escape, Ctrl+C, and Ctrl+D cancel the read.

-	If the read cannot be completed, or if the terminal mode cannot be restored, the method throws ''Io\Terminal\TerminalException''.	+	If the read cannot be completed, or if cancelled by the user, the method restores the original terminal mode and throws ''Io\Terminal\TerminalException''.

	''TerminalException'' extends ''Io\IoException''.		''TerminalException'' extends ''Io\IoException''.
Line 188:		Line 188:
	Without native support, PHP libraries need external processes, FFI, or other platform-specific workarounds for these operations.		Without native support, PHP libraries need external processes, FFI, or other platform-specific workarounds for these operations.

-	The API proposed here is based on experience from the ext-terminal extension and from integrating that extension with Symfony Console/TUI. The core proposal is intentionally smaller than the complete ext-terminal API.	+	The proposed API targets terminal dimensions, mode management, simple key input, and hidden input. It is not a complete terminal event or protocol interface. The linked Symfony pull requests describe integration work; full TUI event handling (such as raw modifier states, key releases, or mouse events via ''readEvent()'') is intentionally left for future scope.

	===== Backward Incompatible Changes =====		===== Backward Incompatible Changes =====
Line 230:		Line 230:
	===== Open Issues =====		===== Open Issues =====

-	None currently.	+	The following points remain under review during discussion:
		+
		+	* Mode-token ownership and lifetime across multiple descriptors referencing the same terminal device.
		+	* Timeout semantics for partial multibyte/escape sequences during zero-duration non-blocking polling.
		+	* Signal handler cooperation (SIGWINCH) with pcntl.
		+	* Positive terminal test coverage on POSIX and Windows.
		+
		+	The API descriptions and implementation will be updated as these points are finalized.

	===== Future Scope =====		===== Future Scope =====
Line 236:		Line 243:
	The following functionality exists in the reference extension or has been explored separately, but is not proposed by this RFC:		The following functionality exists in the reference extension or has been explored separately, but is not proposed by this RFC:

-	* lower-level terminal input events	+	* lower-level terminal input events (e.g. ''readEvent()'' with key releases and modifiers)
	* ANSI support detection		* ANSI support detection
	* terminal color-depth detection		* terminal color-depth detection
Line 253:		Line 260:
	The available choices will be Yes, No, and Abstain.		The available choices will be Yes, No, and Abstain.

-	Acceptance requires a 2/3 majority of Yes votes over No votes.	+	Acceptance requires a 2/3 majority of Yes votes over No votes (Abstain votes are excluded from the calculation).

	===== Patches and Tests =====		===== Patches and Tests =====
Line 265:		Line 272:
	https://github.com/prateekbhujel/php-terminal		https://github.com/prateekbhujel/php-terminal

-	The implementation includes PHPT coverage for terminal construction, terminal sizing, raw mode and restoration, key input, escape sequences, timeout validation, and secret input.	+	The proposed implementation includes PHPT tests for construction, terminal sizing, mode handling, key input, escape sequences, timeout validation, and secret-input error paths. Additional regression tests for multi-descriptor ownership and positive PTY terminal coverage are under active development. Passing tests in a non-terminal environment do not by themselves establish correct interactive behavior on POSIX or Windows.

	===== Implementation =====		===== Implementation =====

-	Not implemented.	+	A proposed implementation is under review in php-src PR #23941:
		+	https://github.com/php/php-src/pull/23941
		+
		+	It has not yet been merged. Implementation review and validation are ongoing.

	===== References =====		===== References =====
Line 301:		Line 311:
	===== Changelog =====		===== Changelog =====

		+	* 2026-09-28: Clarify scope, implementation status, test coverage, and open review questions.
	* 2026-09-27: Initial draft.		* 2026-09-27: Initial draft.
-

rfc - Add Io\Terminal RFC to the Under Discussion index.

prateekbhujel (prateekbhujel@undisclosed.example.com) — 2026-09-28T08:22:05+00:00

2026/09/27 15:57		current
Line 18:		Line 18:

	This section is for RFCs that have been announced on the PHP "internals" mail list.		This section is for RFCs that have been announced on the PHP "internals" mail list.
		+	* [[rfc:io_terminal\|Io\Terminal]] (Created 2026-09-27, Discussion started 2026-09-27)
	* [[rfc:time_instant_class\|Time\Instant and Time\Clock]] (Created 2026-09-21)		* [[rfc:time_instant_class\|Time\Instant and Time\Clock]] (Created 2026-09-21)
	* [[rfc:reldateformatter\|IntlRelativeDateTimeFormatter]] (Created 2026-08-07, Discussion started 2026-08-07)		* [[rfc:reldateformatter\|IntlRelativeDateTimeFormatter]] (Created 2026-08-07, Discussion started 2026-08-07)

duration_class - Revert accidental edit

prateekbhujel (prateekbhujel@undisclosed.example.com) — 2026-09-27T17:39:06+00:00

2026/09/27 15:38		current
Line 1:		Line 1:
-	====== PHP RFC: Io\Terminal ======	+	====== PHP RFC: Duration class ======
-		+	* Version: 1.0
-	* Version: 0.1	+	* Date: 2026-06-18
-	* Date: 2026-09-27	+	* Author: Tim Düsterhus, tim@tideways-gmbh.com, Derick Rethans, derick@php.net
-	* Author: Pratik Bhujel, prateekbhujelpb@gmail.com	+	* Status: Implemented
-	* Status: Draft	+	* Implementation: https://github.com/php/php-src/commit/1cf46237a56540c14d84d0f04b245a10d4ee5bc5 and https://github.com/php/php-src/commit/ed2ffe6f70f6d7f8391f46b1fac88b60b97cdb6b
-	* Target Version: PHP 8.7	+	* Discussion thread: https://news-web.php.net/php.internals/131376
-	* Implementation: https://github.com/php/php-src/pull/23941	+	* Voting thread: https://news-web.php.net/php.internals/131998
-	* Discussion thread: tbd	+
-	* Voting thread: tbd	+

	===== Introduction =====		===== Introduction =====

-	PHP does not currently provide a cross-platform API for basic terminal operations such as querying the terminal size, switching the terminal into raw mode, reading individual keys, or reading secret input without echo.	+	Measuring and defining elapsed time is a ubiquitous concept in programming languages. Use cases where accurately defining such duration include defining timeouts for network requests, defining (exponential) back-off policies or defining operations that need to happen on a fixed schedule. PHP does not yet have a way to represent “stop-watch time” duration in a structured and intuitive way.

-	Userland libraries generally implement these features using platform-specific workarounds. On POSIX systems this often involves invoking tools such as ''stty'', while Windows requires the Win32 Console API.	+	Instead existing APIs resort to <php>int</php> parameters representing a number of seconds, milliseconds, nanoseconds or any other unit that appears to be appropriate for a given use case. Sometimes durations are also split into separate parameters defining the <php>$seconds</php> and <php>$microsecond</php> separately. And sometimes it's a floating point value which comes with its own issues due to a possible lack of precision.

-	This RFC proposes a small native terminal API in the ''Io\Terminal'' namespace.	+	The existing <php>DateInterval</php> class is also unsuitable to define durations for the use-cases previously mentioned, due to its support for days and larger units which cannot be unambiguously mapped into a fixed number of seconds due to daylight saving time and months having different lengths.

-	<code php>	+	This RFC proposes the addition a <php>Time\Duration</php> class that represents durations as measured by a “stop-watch” or an “egg-timer” in a structured way with nanosecond precision.
		+
		+
		+	<PHP>
	<?php		<?php

-	use Io\Terminal\Key;	+	// Sleep for half a second
-	use Io\Terminal\Terminal;	+	sleep(\Time\Duration::fromMilliseconds(500));
-	use Time\Duration;	+

-	$terminal = Terminal::create();	+	?>
		+	</PHP>

-	$size = $terminal->getSize();	+	===== Proposal =====
-	if ($size !== false) {	+
-	printf("%dx%d\n", $size->cols, $size->rows);	+
-	}	+

-	$mode = $terminal->enableRawMode();	+	Add a new always-available class <php>Time\Duration</php> with the following stub:

-	try {	+	<PHP>
-	$key = $terminal->readKey(Duration::fromSeconds(5));	+	<?php

-	if ($key === Key::Escape) {	+	namespace Time;
-	echo "Escape pressed\n";	+
		+	/**
		+	* Represents a “stop-watch” or “egg-timer” duration as an abstraction over a number
		+	* of (fractional) seconds with nanosecond precision. It is unaffected by any timezones
		+	* or “time and date” as shown on a clock.
		+	*
		+	* The maximum representable range is 9223372035999999999 nanoseconds (roughly 292 years).
		+	* Any operation that will overflow, will throw a Time\TimeException.
		+	*
		+	* @strict-properties
		+	*/
		+	final readonly class Duration
		+	{
		+	/**
		+	* Will be limited to 9_223_372_035 even on 64-bit platforms to allow for a possible
		+	* future scope `->getTotalNanoseconds(): int`
		+	*/
		+	public readonly int $seconds;
		+	public readonly int $nanoseconds;
		+
		+	/**
		+	* Will be normalized to false if both $seconds and $nanoseconds are 0.
		+	*/
		+	public readonly bool $negative;
		+
		+	/**
		+	* Create a duration representing $seconds seconds and $nanoseconds nanoseconds. Neither parameter
		+	* may be negative. $nanoseconds must be less than 1_000_000_000 (the number of nanoseconds in a
		+	* second).
		+	*
		+	* This constructor creates a Duration from its “atomic” components.
		+	*/
		+	public static function fromSeconds(int $seconds, int $nanoseconds = 0): self
		+	{
	}		}
-	} finally {	+
-	if ($mode !== false) {	+	/**
-	$terminal->restoreMode($mode);	+	* Create a duration representing $nanoseconds nano-seconds. $nanoseconds must not be negative.
		+	*/
		+	public static function fromNanoseconds(int $nanoseconds): self
		+	{
	}		}
-	}
-	</code>

-	===== Proposal =====	+	/**
		+	* Create a duration representing $microseconds micro-seconds. $microseconds must not be negative.
		+	*/
		+	public static function fromMicroseconds(int $microseconds): self
		+	{
		+	}

-	The RFC adds an object-oriented terminal API under ''Io\Terminal''.	+	/**
		+	* Create a duration representing $milliseconds milli-seconds. $milliseconds must not be negative.
		+	*/
		+	public static function fromMilliseconds(int $milliseconds): self
		+	{
		+	}

-	The proposed API is:	+	/**
		+	* Create a duration representing $minutes minutes. $minutes must not be negative.
		+	*/
		+	public static function fromMinutes(int $minutes): self
		+	{
		+	}

-	<code php>	+	/**
-	<?php	+	* Create a duration representing $hours hours. $hours must not be negative.
		+	*/
		+	public static function fromHours(int $hours): self
		+	{
		+	}

-	namespace Io\Terminal;	+	/**
		+	* Parse a ISO-8601 duration string. ISO-8601 duration strings with a date component will be rejected.
		+	* The biggest allowed component is H.
		+	*/
		+	public static function fromIso8601DurationString(string $specification): self
		+	{
		+	}

-	class TerminalException extends \Io\IoException {}	+	/**
		+	* Negates the duration.
		+	*
		+	* @return self -$this
		+	*/
		+	public function negate(): self
		+	{
		+	}
		+
		+	/**
		+	* Returns the duration with `$seconds` and `$nanoseconds` unchanged and
		+	* `$negative` set to `false`.
		+	*
		+	* @return self abs($this)
		+	*/
		+	public function absolute(): self
		+	{
		+	}

-	enum Key	+	/**
-	{	+	* Add the given duration to the duration.
-	case Up;	+	*
-	case Down;	+	* @return self $this + $duration
-	case Right;	+	*/
-	case Left;	+	public function add(self $duration): self
-	case Enter;	+	{
-	case Backspace;	+	}
-	case Escape;	+
-	case Tab;	+
-	case Home;	+
-	case End;	+
-	case Delete;	+
-	case PageUp;	+
-	case PageDown;	+
-	case Resize;	+
-	case F1;	+
-	case F2;	+
-	case F3;	+
-	case F4;	+
-	case F5;	+
-	case F6;	+
-	case F7;	+
-	case F8;	+
-	case F9;	+
-	case F10;	+
-	case F11;	+
-	case F12;	+
-	}	+

-	final readonly class TerminalSize	+	/**
-	{	+	* Subtract the given duration from the duration.
-	public readonly int $cols;	+	*
-	public readonly int $rows;	+	* @return self $this - $duration
		+	*/
		+	public function sub(self $duration): self
		+	{
		+	}

-	private function __construct() {}	+	/**
-	}	+	* Multiply the length of the duration by the given factor. $factor must not be negative.
		+	*
		+	* @return self $this * $factor
		+	*/
		+	public function multiplyBy(int $factor): self
		+	{
		+	}

-	final class ModeToken	+	/**
-	{	+	* Divide the length of the duration by the given divisor. $divisor must be positive.
-	private function __construct() {}	+	*
		+	* Fractional nanoseconds will be truncated.
		+	*
		+	* @return self $this / $factor
		+	*/
		+	public function divideBy(int $divisor): self
		+	{
		+	}
		+
		+	/**
		+	* Returns -1, 0, 1 if $a is less than, equal to, or greater than $b respectively.
		+	*/
		+	public static function compare(self $a, self $b): int
		+	{
		+	}
	}		}
		+	</PHP>

-	final class Terminal	+	The <php>Time\Duration</php> class will also implement internal “comparison handlers”, which means that direct comparisons with operators such as <php><</php> will work. Other operators (such as <php>+</php> for addition) will not be overloaded.
-	{	+
-	private function __construct() {}	+

-	public static function create(): Terminal {}	+	Additionally add the <php>Time\TimeException</php> base exception as per the [[https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables\|Throwable policy]]:

		+	<PHP>
		+	namespace Time;
		+
		+	class TimeException extends \Exception { }
		+	</PHP>
		+
		+	==== Naming of the mathematical operations ====
		+
		+	According to PHP’s naming policy “Abbreviations and acronyms as well as initialisms SHOULD be avoided wherever possible”, which is why the RFC proposes full verbs for multiplication, division, negation and taking absolutes.
		+
		+	At the same time the naming policy also specifies that “Diverging from this policy […] is allowed to keep internal consistency within a single extension, if the name follows an established, language-agnostic standard, or for other reasons, if those reasons are properly justified and voted on as part of the RFC process”.
		+
		+	While there naturally is no existing precedent within the extension (or namespace), there is cross-extension precedent for abbreviated names in ext/bcmath, ext/gmp, the standard library, and PHP’s own tokenizer, specifically:
		+
		+	* BcMath\Number::mul() BcMath\Number::div(), bcmul(), bcdiv()
		+	* gmp_mul(), gmp_div(), gmp_neg(), gmp_abs()
		+	* abs(), intdiv(), fdiv()
		+	* T_MUL_EQUAL, T_DIV_EQUAL
		+
		+	There is also some cross-language precedent. JavaScript’s Temporal.Duration has ''abs()''. Rust’s std::time::Duration has ''checked_mul()'' and ''checked_div()''.
		+
		+	The RFC therefore leaves up the choice between full and abbreviated names up to a (weighted) secondary vote. For multiplication the ''By'' suffix is dropped when abbreviating. Division will keep the ''By'' suffix (''divBy'') to enable a future scope ''divInto'' method that divides a Duration by a Duration.
		+
		+	==== The new polling API ====
		+
		+	If this RFC is accepted for PHP 8.6, the polling API introduced in [[poll_api\|PHP RFC: Polling API]] for PHP 8.6 will be adjusted to make use of the <php>Time\Duration</php> class instead of separate <php>$timeout</php> and <php>$timeoutMicroseconds</php> parameters:
		+
		+	<PHP>
		+	namespace Io\Poll;
		+
		+	final class Context
		+	{
	/**		/**
-	* @param resource $input	+	* […]
-	* @param resource\|null $output	+	*
		+	* @param ?Time\Duration $timeout Timeout.
		+	* null means wait indefinitely.
		+	* Time\Duration::fromNanoseconds(0) means return immediately (non-blocking poll).
		+	* Must be !$timeout->negative
		+	*
		+	* […]
	*/		*/
-	public static function fromStreams($input, $output = null): Terminal {}	+	public function wait(
		+	?Time\Duration $timeout = null,
		+	?int $maxEvents = null
		+	): array {}
		+	}
		+	</PHP>

-	public function getSize(): TerminalSize\|false {}	+	==== Passing Duration objects to APIs unable to handle nanosecond precision ====

-	public function enableRawMode(): ModeToken\|false {}	+	This RFC leaves the behavior of passing a <php>Time\Duration</php> object that has more precision than an API can handle to the target API in question, since depending on the use case a different behavior might be the correct.

-	public function restoreMode(?ModeToken $mode = null): bool {}	+	A non-exhaustive list of possible options:

-	public function readKey(	+	* Always round up to the nearest representable value. This behavior makes most sense for “at least this amount of time” APIs (e.g. <php>sleep()</php>).
-	?\Time\Duration $timeout = null,	+	* Always round down to the nearest representable value.
-	?\Time\Duration $sequenceTimeout = null,	+	* Throw for unrepresentable values. This behavior makes sense if the rounding error would be unacceptably large.
-	): Key\|string\|false {}	+

-	public function readSecret(): string {}	+	==== Design Considerations ====
-	}	+
-	</code>	+

-	''Terminal'' and ''ModeToken'' are not serializable.	+	<php>Time\Duration</php> is intended as the first part and basic building block of a modernized date and time library for PHP, while already providing value by itself. For this initial version the exposed API is intentionally small, while including all important parts for future classes to build onto.

-	==== Creating a terminal session ====	+	Its design is roughly modeled after Golang’s ''time.Duration'', Java’s ''java.time.Duration'', and Rust’s ''std::time::Duration'', which just like <php>Time\Duration</php> are a structured representation of a number of nanoseconds.

-	''Terminal::create()'' creates a terminal session using the process standard input and standard output.	+	The split between <php>$seconds</php> and <php>$nanoseconds</php> in the public API is intended to match how seconds are used as a base unit in human communication and science. It also improves compatibility with 32-bit versions of PHP, since signed 32-bit integers are sufficiently large to represent the number of nanoseconds in a second, while the separate seconds component allows to represent roughly 68 years. <php>$seconds</php> will be limited to <php>9_223_372_035</php> on 64-bit systems (roughly 292 years) to possibly allow representing the entire duration as a single nanosecond value in future scope.

-	''Terminal::fromStreams()'' creates a terminal session using an explicit input stream and an optional output stream. If the output stream is omitted, the input stream is also used as the output stream.	+	Creating Duration objects happens via named constructors for all possible resolutions such that users are able to select the most appropriate resolution for their use case. Except for the <php>fromSeconds()</php> “base” constructor (which matches the second and nanosecond split described above) all constructors intentionally only take a single value in order to avoid multiple input combinations for the same constructor misleadingly resulting in the same duration due to overflow (e.g. 1 millisecond and 1500 microseconds being equivalent to 2 milliseconds and 500 microseconds). For the <php>fromSeconds()</php> constructor an overflow in the nanosecond component is rejected.

-	The constructor is private. Terminal instances are created using these named constructors.	+	Negative durations are represented by an explicit <php>$negative</php> property. This makes it easy to deal with absolute values by just ignoring the value of <php>$negative</php>. It also avoids ambiguity with regard to signs for negative durations: Should both <php>$seconds</php> and <php>$nanoseconds</php> be negative for a negative duration?

-	==== Terminal size ====	+	Creating a negative duration intentionally requires a separate call to <php>->negate()</php>, since use cases for those are expected to be rare. They are expected to mainly come up when subtracting one duration from another and when calculating differences between two “Instants” after more parts of the modernized date and time library are added.

-	''Terminal::getSize()'' queries the size of the terminal associated with the output side of the session.	+	==== Examples ====

-	On success it returns a ''TerminalSize'' object containing the number of columns and rows. It returns ''false'' if a native terminal size cannot be obtained.	+	Note that these examples show possible hypothetical use-cases. The RFC does not propose a change to existing functions to accept <php>Time\Duration</php> objects, except for the <php>Io\Poll\Context</php> as described previously.

-	No fallback to the ''COLUMNS'' or ''LINES'' environment variables is performed by this API.	+	<PHP>
		+	<?php

-	==== Raw mode ====	+	use Time\Duration;

-	''Terminal::enableRawMode()'' enables raw input mode for the session input and returns a ''ModeToken''. It returns ''false'' if raw mode cannot be enabled.	+	$oneSecond = Duration::fromSeconds(1);
		+	$halfSecond = $oneSecond->divideBy(2);

-	''Terminal::restoreMode()'' restores a saved terminal mode. A token can be passed explicitly, or the method can be called without an argument to restore the active mode owned by the ''Terminal'' instance.	+	$onePointFiveSeconds = $oneSecond->add($halfSecond);

-	''ModeToken'' is an opaque object. An active token restores its saved terminal mode when it is destroyed. A ''Terminal'' instance also restores an active mode it owns when the object is destroyed. Active modes are restored during normal request shutdown as well.	+	// Sleep for 1.5 seconds
		+	sleep($onePointFiveSeconds);

-	These restoration mechanisms are intended to avoid leaving a terminal in raw or no-echo mode after ordinary PHP control flow exits. They cannot provide a guarantee for process termination that bypasses PHP shutdown entirely.	+	$negativeHour = Duration::fromHours(1)->negate();

-	==== Reading keys ====	+	$durations = [
		+	$oneSecond,
		+	$negativeHour,
		+	$onePointFiveSeconds,
		+	$halfSecond,
		+	];

-	''Terminal::readKey()'' reads one logical key from the session input.	+	usort($durations, Duration::compare(...)); // Will sort to [-1h, 0.5s, 1s, 1.5s]

-	Recognized special keys are returned as ''Io\Terminal\Key'' enum cases. Printable input is returned as a string. Input that does not map to a known enum case is also returned as a string rather than discarded.	+	$baseDelay = Duration::fromMilliseconds(100);
		+	$attempt = 5;
		+	$delay = $baseDelay->multiplyBy(2 $attempt); // $delay is equal** to 3.2 seconds

-	''Key::Resize'' is returned when a terminal resize event is observed.	+	?>
		+	</PHP>

-	The optional ''$timeout'' controls how long the method waits for input. A ''null'' timeout waits indefinitely. A zero duration performs a non-blocking poll.	+	A proof of concept user-land implementation is as follows. This implementation is non-authoritative and may contain bugs.

-	On POSIX, ''$sequenceTimeout'' controls the short wait used while reading multi-byte input and terminal escape sequences. If it is omitted, the implementation uses a 25 ms sequence timeout. Windows receives structured console input events and does not use this value.	+	<file php proof_of_concept.php>
		+	<?php

-	Both timeout parameters use ''Time\Duration''. Negative durations result in a ''ValueError''.	+	namespace Time;

-	==== Reading secret input ====	+	class TimeException extends \Exception { }

-	''Terminal::readSecret()'' reads input without echoing the entered characters.	+	/**
		+	* Represents a “stop-watch” or “egg-timer” duration as an abstraction over a number
		+	* of (fractional) seconds with nanosecond precision. It is unaffected by any timezones
		+	* or “time and date” as shown on a clock.
		+	*
		+	* The maximum representable range is 9223372035999999999 nanoseconds (roughly 292 years).
		+	* Any operation that will overflow, will throw a Time\TimeException.
		+	*
		+	* @strict-properties
		+	*/
		+	final readonly class Duration
		+	{
		+	private function __construct(
		+	public readonly int $seconds,
		+	public readonly int $nanoseconds,
		+	public readonly bool $negative,
		+	) {
		+	if ($seconds > 9_223_372_035) {
		+	throw new TimeException('The maximum representable range is 9_223_372_035 seconds (roughly 292 years)');
		+	}

-	Enter completes the input. Backspace removes the previous character. Escape, Ctrl+C, and Ctrl+D cancel the read.	+	\assert($seconds >= 0);
		+	\assert($nanoseconds >= 0);
		+	\assert($nanoseconds < 1_000_000_000);
		+	\assert($seconds > 0 \|\| $nanoseconds > 0 \|\| !$negative);
		+	}

-	If the read cannot be completed, or if the terminal mode cannot be restored, the method throws ''Io\Terminal\TerminalException''.	+	/**
		+	* Create a duration representing $seconds seconds and $nanoseconds nanoseconds. Neither parameter
		+	* may be negative. $nanoseconds must be less than 1_000_000_000 (the number of nanoseconds in a
		+	* second).
		+	*
		+	* This contructor creates a Duration from its “atomic” components.
		+	*/
		+	public static function fromSeconds(int $seconds, int $nanoseconds = 0): self
		+	{
		+	if ($seconds < 0) {
		+	throw new \ValueError('$seconds must not be negative');
		+	}
		+	if ($nanoseconds < 0 \|\| $nanoseconds >= 1_000_000_000) {
		+	throw new \ValueError('$nanoseconds must be between 0 and 999_999_999');
		+	}

-	''TerminalException'' extends ''Io\IoException''.	+	return new self($seconds, $nanoseconds, false);
		+	}

-	===== Motivation =====	+	/**
		+	* Create a duration representing $nanoseconds nano-seconds. $nanoseconds must not be negative.
		+	*/
		+	public static function fromNanoseconds(int $nanoseconds): self
		+	{
		+	$seconds = \intdiv($nanoseconds, 1_000_000_000);
		+	$nanoseconds = $nanoseconds % 1_000_000_000;

-	Terminal handling is inherently platform-specific. POSIX systems expose terminal functionality through APIs such as ''termios'' and ''ioctl'', while Windows uses the Win32 Console API.	+	return self::fromSeconds($seconds, $nanoseconds);
		+	}

-	Without native support, PHP libraries need external processes, FFI, or other platform-specific workarounds for these operations.	+	/**
		+	* Create a duration representing $microseconds micro-seconds. $microseconds must not be negative.
		+	*/
		+	public static function fromMicroseconds(int $microseconds): self
		+	{
		+	*return self::fromNanoseconds($microseconds 1_000);**
		+	}

-	The API proposed here is based on experience from the ext-terminal extension and from integrating that extension with Symfony Console/TUI. The core proposal is intentionally smaller than the complete ext-terminal API.	+	/**
		+	* Create a duration representing $milliseconds milli-seconds. $milliseconds must not be negative.
		+	*/
		+	public static function fromMilliseconds(int $milliseconds): self
		+	{
		+	*return self::fromMicroseconds($milliseconds 1_000);**
		+	}
		+
		+	/**
		+	* Create a duration representing $minutes minutes. $minutes must not be negative.
		+	*/
		+	public static function fromMinutes(int $minutes): self
		+	{
		+	*return self::fromSeconds($minutes 60);**
		+	}
		+
		+	/**
		+	* Create a duration representing $hours hours. $hours must not be negative.
		+	*/
		+	public static function fromHours(int $hours): self
		+	{
		+	*return self::fromMinutes($hours 60);**
		+	}
		+
		+	/**
		+	* Parse a ISO-8601 period. ISO-8601 periods with a date component will be rejected.
		+	* The biggest allowed component is H.
		+	*/
		+	public static function fromIso8601String(string $specification): self
		+	{
		+	*/ Omitted /*
		+	}
		+
		+	/**
		+	* Negates the duration.
		+	*
		+	* @return self -$this
		+	*/
		+	public function negate(): self
		+	{
		+	if ($this->seconds === 0 && $this->nanoseconds === 0) {
		+	return $this;
		+	}
		+
		+	return clone($this, ['negative' => !$this->negative]);
		+	}
		+
		+	/**
		+	* Add the given duration to the duration.
		+	*
		+	* @return self $this + $duration
		+	*/
		+	public function add(self $duration): self
		+	{
		+	*/ (+x) + (-y) == (+x) - (+y) /*
		+	if (!$this->negative && $duration->negative) {
		+	return $this->sub($duration->negate());
		+	}
		+	*/ (-x) + (+y) == (+y) - (+x) /*
		+	if ($this->negative && !$duration->negative) {
		+	return $duration->sub($this->negate());
		+	}
		+	*/ (-x) + (-y) = -((+x) + (+y)) /*
		+	if ($this->negative && $duration->negative) {
		+	return $this->negate()->add($duration->negate())->negate();
		+	}
		+
		+	\assert(!$this->negative);
		+	\assert(!$duration->negative);
		+
		+	$seconds = $this->seconds + $duration->seconds;
		+	$nanoseconds = $this->nanoseconds + $duration->nanoseconds;
		+
		+	$seconds += \intdiv($nanoseconds, 1_000_000_000);
		+	$nanoseconds = $nanoseconds % 1_000_000_000;
		+
		+	return self::fromSeconds($seconds, $nanoseconds);
		+	}
		+
		+	/**
		+	* Subtract the given duration from the duration.
		+	*
		+	* @return self $this - $duration
		+	*/
		+	public function sub(self $duration): self
		+	{
		+	*/ (+x) - (-y) == (+x) + (+y) /*
		+	if (!$this->negative && $duration->negative) {
		+	return $this->add($duration->negate());
		+	}
		+	*/ (-x) - (+y) == -((+x) + (+y)) /*
		+	if ($this->negative && !$duration->negative) {
		+	return $this->negate()->add($duration)->negate();
		+	}
		+	*/ (-x) - (-y) == (-x) + (+y) /*
		+	if ($this->negative && $duration->negative) {
		+	return $this->add($duration->negate());
		+	}
		+
		+	\assert(!$this->negative);
		+	\assert(!$duration->negative);
		+
		+	if (self::compare($this, $duration) >= 0) {
		+	$seconds = $this->seconds - $duration->seconds;
		+	$nanoseconds = $this->nanoseconds - $duration->nanoseconds;
		+	if ($nanoseconds < 0) {
		+	$nanoseconds += 1_000_000_000;
		+	$seconds--;
		+	}
		+
		+	return self::fromSeconds($seconds, $nanoseconds);
		+	} else {
		+	*/ (+x) - (+y) = -((+y) - (+x)) /*
		+	return $duration->sub($this)->negate();
		+	}
		+	}
		+
		+	/**
		+	* Multiply the length of the duration by the given factor. $factor must not be negative.
		+	*
		+	* @return self $this * $factor
		+	*/
		+	public function multiplyBy(int $factor): self
		+	{
		+	if ($factor < 0) {
		+	throw new \ValueError('$factor must not be negative');
		+	}
		+
		+	*$seconds = $this->seconds $factor;**
		+	*$nanoseconds = $this->nanoseconds $factor;**
		+
		+	$seconds += \intdiv($nanoseconds, 1_000_000_000);
		+	$nanoseconds = $nanoseconds % 1_000_000_000;
		+
		+	return new self($seconds, $nanoseconds, negative: $this->negative);
		+	}
		+
		+	/**
		+	* Divide the length of the duration by the given divisor. $divisor must be positive.
		+	*
		+	* Fractional nanoseconds will be truncated.
		+	*
		+	* @return self $this / $factor
		+	*/
		+	public function divideBy(int $divisor): self
		+	{
		+	if ($divisor <= 0) {
		+	throw new \ValueError('$divisor must be positive');
		+	}
		+
		+	$seconds = \intdiv($this->seconds, $divisor);
		+	*$nanoseconds = $this->nanoseconds + (($this->seconds % $divisor) 1_000_000_000);**
		+	$nanoseconds = \intdiv($nanoseconds, $divisor);
		+
		+	return new self($seconds, $nanoseconds, negative: $this->negative);
		+	}
		+
		+	/**
		+	* Returns -1, 0, 1 if $a is less than, equal to, or greater than $b respectively.
		+	*/
		+	public static function compare(self $a, self $b): int
		+	{
		+	if ($a->negative && !$b->negative) {
		+	return -1;
		+	}
		+	if (!$a->negative && $b->negative) {
		+	return 1;
		+	}
		+
		+	if ($a->negative && $b->negative) {
		+	return - ($a->seconds <=> $b->seconds) ?: - ($a->nanoseconds <=> $b->nanoseconds);
		+	}
		+
		+	if (!$a->negative && !$b->negative) {
		+	return ($a->seconds <=> $b->seconds) ?: ($a->nanoseconds <=> $b->nanoseconds);
		+	}
		+
		+	throw new \Error('unreachable');
		+	}
		+	}
		+	</file>

	===== Backward Incompatible Changes =====		===== Backward Incompatible Changes =====

-	No existing PHP API is changed.	+	This RFC is introducing a single class and starts using the <php>Time</php> for PHP’s standard library. Adding new symbols is not considered a breaking change as per our policy. The naming of the class and namespace is in line with PHP’s naming policy.

-	The RFC introduces the following names:	+	A GitHub search for ''language:php "namespace Time;" symbol:Duration'' reveals a total of 7 hits. There are two notable hits with:

-	* ''Io\Terminal\Terminal''	+	* https://github.com/marc-mabe/php-timelib/blob/5092160dfae9c3bf9484a6c86c6809688f7341bd/polyfill/Duration.php#L21
-	* ''Io\Terminal\TerminalSize''	+	* https://github.com/jiripudil/php-ext-time-prototype/blob/06b97b9e0c8f4878d68aee3a7571fc079f3ebc17/polyfill/src/Duration.php#L16
-	* ''Io\Terminal\ModeToken''	+
-	* ''Io\Terminal\TerminalException''	+
-	* ''Io\Terminal\Key''	+

-	Userland code declaring one of these exact names would conflict with the new internal symbol.	+	which both try to solve the same problem in a very similar way and confirming there is an interest in having this API.

	===== Proposed PHP Version(s) =====		===== Proposed PHP Version(s) =====

-	PHP 8.7.	+	Next minor (8.6).

	===== RFC Impact =====		===== RFC Impact =====
-
	==== To the Ecosystem ====		==== To the Ecosystem ====

-	CLI libraries may use the native API when it is available and retain their existing fallbacks for older PHP versions.	+	None.
-		+
-	The ext-terminal extension can continue to serve as a backport and as a place to experiment with functionality that is outside this RFC.	+

	==== To Existing Extensions ====		==== To Existing Extensions ====

-	The implementation is part of ''ext/standard''.	+	Existing extensions may want to start using this new class where-ever a duration is required.
-		+
-	No existing extension API is removed or changed.	+

	==== To SAPIs ====		==== To SAPIs ====

-	The main use case is CLI and other environments attached to a terminal.	+	None.
-		+
-	The API itself is available independently of SAPI. Operations that require a terminal return ''false'' or throw ''TerminalException'' as described above when the associated stream is not a usable terminal.	+

	===== Open Issues =====		===== Open Issues =====

-	None currently.	+	None.

	===== Future Scope =====		===== Future Scope =====

-	The following functionality exists in the reference extension or has been explored separately, but is not proposed by this RFC:	+	The introduction of this class and the associated <php>Time</php> namespace is intended to lay the groundwork for a new date and time library in upcoming PHP versions. It is intentionally designed with a minimal, but useful, API that future additions will be able to build on.

-	* lower-level terminal input events	+	Some ideas that have been taken into account when designing the <php>Time\Duration</php> class:
-	* ANSI support detection	+
-	* terminal color-depth detection	+
-	* setting the terminal title	+
-	* emitting a terminal bell	+
-	* environment-variable based terminal-size fallbacks	+

-	These can be considered separately if there is sufficient need and the API semantics are clear.	+	* Calculating the difference between two points in time (“Instant”) will return a <php>Time\Duration</php> object.
		+	* Calendar-based calculations with units larger than one hour (days, weeks, months) will use a dedicated class that only works with a full DateTime carrying both a time and date and a timezone. It will be possible to construct such a “calendar interval” from a <php>Time\Duration</php>, but not the other way around.
		+	* There are two possible division operations on Durations: Duration by scalar and Duration by Duration. The naming of Duration by scalar was carefully selected to allow Duration by Duration (“divide into”) as future scope.
		+
		+	Additional classes will be added to the exception hierarchy when other classes are added (e.g. <php>TimeOverflowException</php> or <php>DurationException</php>).

	===== Voting Choices =====		===== Voting Choices =====

-	The primary vote will be:	+	Primary Vote requiring a 2/3 majority to accept the RFC:

-	''Implement the Io\Terminal API as described in this RFC?''	+	<doodle title="Implement the Time\Duration class as outlined in the RFC?" voteType="single" closed="true" closeon="2026-07-31T17:00:00Z">
		+	* Yes
		+	* No
		+	* Abstain
		+	</doodle>

-	The available choices will be Yes, No, and Abstain.	+	Secondary Vote to decide whether the “mathematical operation methods” should use full or abbreviated names. This vote is weighted and requires a 2/3 supermajority for abbreviated names to be selected.

-	Acceptance requires a 2/3 majority of Yes votes over No votes.	+	<doodle title="Should the mathematical operation methods of Time\Duration use full or abbreviated names?" voteType="single" closed="true" closeon="2026-07-31T17:00:00Z">
		+	* multiplyBy, divideBy, negate, absolute
		+	* mul, divBy, neg, abs
		+	* Abstain
		+	</doodle>

	===== Patches and Tests =====		===== Patches and Tests =====

-	Implementation:	+	* https://github.com/php/php-src/pull/23073
-		+	* https://github.com/php/php-src/pull/23092
-	https://github.com/php/php-src/pull/23941	+
-		+
-	Reference extension:	+
-		+
-	https://github.com/prateekbhujel/php-terminal	+
-		+
-	The implementation includes PHPT coverage for terminal construction, terminal sizing, raw mode and restoration, key input, escape sequences, timeout validation, and secret input.	+

	===== Implementation =====		===== Implementation =====

-	TODO: After acceptance.	+	* Time\TimeException and Time\Duration: https://github.com/php/php-src/commit/1cf46237a56540c14d84d0f04b245a10d4ee5bc5
		+	* Polling API changes: https://github.com/php/php-src/commit/ed2ffe6f70f6d7f8391f46b1fac88b60b97cdb6b

	===== References =====		===== References =====

-	Previous discussion:	+	* PHP Date/Time API Brainstorm document: https://docs.google.com/document/d/1pxPSRbfATKE4TFWw72K3p7ir-02YQbTf3S3SIxOKWsk/edit?usp=sharing
-		+
-	* https://externals.io/message/131004	+
-	* https://externals.io/message/132523	+
-	* https://externals.io/message/132526	+
-	* https://externals.io/message/132530	+
-		+
-	Related work:	+
-		+
-	* https://github.com/prateekbhujel/php-terminal	+
-	* https://github.com/php/php-src/pull/23941	+
-	* https://github.com/symfony/symfony/pull/66173	+
-	* https://github.com/symfony/symfony/pull/66271	+
-	* https://github.com/symfony/symfony/pull/66272	+

	===== Rejected Features =====		===== Rejected Features =====

-	Earlier iterations considered a larger API. The following are not part of this RFC:	+	- Adding a “unit” enum with a single constructor instead of multiple named constructors.
-		+	- Adding constructors with multiple (named) parameters, such as “hoursAndMinutes”. The <php>fromSeconds()</php> constructor is an intentional exception, because it works with the two “base units”.
-	* exposing the same operations through both procedural functions and object methods	+
-	* separate stdin, stdout, and stderr terminal objects instead of a single terminal session	+
-	* a public constructor in addition to named constructors	+
-	* separate ''getWidth()'' and ''getHeight()'' methods in addition to ''getSize()''	+
-	* compatibility-only APIs from older ext-terminal releases	+
-	* the complete ext-terminal 1.x API	+

	===== Changelog =====		===== Changelog =====

-	* 2026-09-27: Initial draft.	+	* 2026-07-03: Fix mistake proof-of-concept implementation.
		+	* 2026-07-03: Add secondary vote for naming of the mathematical operations.
		+	* 2026-06-23: Clarify that every overflow will throw TimeException.
		+	* 2026-06-23: Add ->absolute().
		+	* 2026-06-23: Rename ->fromIso8601String() to ->fromIso8601DurationString().
		+	* 2026-06-23: Limit seconds to 9_223_372_035 to enable possible future scope.
		+	* 2026-06-23: Add TimeException.
		+	* 2026-06-22: Clarify that the target API will be responsible for rounding if it cannot deal with nanosecond precision.
		+	* 2026-06-22: Clarify that non-comparison operators will not be overloaded.
		+	* 2026-06-18: Initial version.

bcrypt_max_password_length

sjoerd (sjoerd@undisclosed.example.com) — 2026-09-27T15:55:47+00:00

2026/09/27 15:55		current
Line 1:		Line 1:
	====== PHP RFC: Deprecate and remove support for passwords longer than 72 bytes in password_hash() with bcrypt ======		====== PHP RFC: Deprecate and remove support for passwords longer than 72 bytes in password_hash() with bcrypt ======
-	* Version: 0.1	+
-	* Date: 2026-09-27	+	* Version: 0.1
-	* Author: Sjoerd Langkemper <sjoerd-php@linuxonly.nl>	+	* Date: 2026-09-27
-	* Status: Draft	+	* Author: Sjoerd Langkemper <sjoerd-php@linuxonly.nl>
-	* First Opened: 2026-09-27	+	* Status: Draft
-	* Implementation: tbd	+	* First Opened: 2026-09-27
-	* Discussion thread: tbd	+	* Implementation: tbd
-	* Voting thread: tbd	+	* Discussion thread: tbd
		+	* Voting thread: tbd

	===== Introduction =====		===== Introduction =====

time_instant_class - Clarify the behavior of the ISO-8601 getter for fractional seconds.

timwolla (timwolla@undisclosed.example.com) — 2026-09-24T11:53:30+00:00

2026/09/23 17:08		current
Line 159:		Line 159:
	* Years outside 0000 to 9999 use the expanded representation with a		* Years outside 0000 to 9999 use the expanded representation with a
	* mandatory sign.		* mandatory sign.
		+	*
		+	* If getNanoseconds() is non-zero the returned string will include a
		+	* fractional part with full nanosecond precision. Trailing zeros will
		+	* be omitted.
	*/		*/
	public function toIso8601DateTimeString(): string {}		public function toIso8601DateTimeString(): string {}
Line 385:		Line 389:
	===== Changelog =====		===== Changelog =====

		+	* 2026-09-24: Clarify the behavior of the ISO-8601 getter for fractional seconds.
	* 2026-09-23: Clarify that serialization will be portable.		* 2026-09-23: Clarify that serialization will be portable.
	* 2026-09-21: Initial version.		* 2026-09-21: Initial version.

php86 - Link to "RC1 skipped" explanation

mbeccati (mbeccati@undisclosed.example.com) — 2026-09-24T09:26:12+00:00

2026/09/23 08:53		current
Line 22:		Line 22:
	\| Sep 10 2026 \| Beta 3 [[https://www.php.net/archive/2026.php#2026-09-10-1\|Announce]] [[https://downloads.php.net/~svpernova09/\|Files]] \|		\| Sep 10 2026 \| Beta 3 [[https://www.php.net/archive/2026.php#2026-09-10-1\|Announce]] [[https://downloads.php.net/~svpernova09/\|Files]] \|
	\| Sep 22 2026 \| Hard feature freeze: features, whether requiring an RFC or not, must be merged only with approval from the RMs. \|		\| Sep 22 2026 \| Hard feature freeze: features, whether requiring an RFC or not, must be merged only with approval from the RMs. \|
-	\| Sep 24 2026 \| <del>RC1</del> (skipped, explanation will follow) \|	+	\| Sep 24 2026 \| <del>RC1</del> (skipped, [[https://scherzer.dev/Blog/20260923-no-php86-rc-1\|explanation]]) \|
	\| Sep 24 2026 \| RC2 \|		\| Sep 24 2026 \| RC2 \|
	\| Oct 08 2026 \| RC3 \|		\| Oct 08 2026 \| RC3 \|

reldateformatter - add example

weilindu (weilindu@undisclosed.example.com) — 2026-09-21T17:26:03+00:00

2026/09/21 17:26		current
Line 428:		Line 428:
	Primary vote requiring a 2/3 majority to accept the RFC:		Primary vote requiring a 2/3 majority to accept the RFC:

-	<doodle title="Add IntlRelativeDateTimeFormatter to ext/intl?" voteType="single" closed="true">	+	<doodle title="Implement IntlRelativeDateTimeFormatter as described to ext/intl?" voteType="single" closed="true">
	* Yes		* Yes
	* No		* No

surface3d.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-19T13:48:10+00:00

	current

scaled_on_load_rotate.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-17T06:47:24+00:00

	current

watermarked.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-17T03:57:25+00:00

	current

scale_entropy_visual_check.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-14T03:12:03+00:00

	current

textcurve.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-10T14:08:53+00:00

1783692513	current

gradient_art.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-06T06:32:24+00:00

	current

tiger.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-06T06:32:03+00:00

	current

gradient_operators.png - created

pajoye (pajoye@undisclosed.example.com) — 2026-07-06T06:31:36+00:00

	current

coroutine-lifecycle.svg - created

edmond (edmond@undisclosed.example.com) — 2025-04-16T07:24:46+00:00

	current

supervisor.svg - created

edmond (edmond@undisclosed.example.com) — 2025-03-16T08:38:59+00:00

	current

exception_flow.svg - created

edmond (edmond@undisclosed.example.com) — 2025-03-16T08:38:59+00:00

	current

resume_and_notifier.svg - created

edmond (edmond@undisclosed.example.com) — 2025-02-16T08:40:05+00:00

	current

2026/09/23 08:53		current
Line 22:		Line 22:
	\| Sep 10 2026 \| Beta 3 [[https://www.php.net/archive/2026.php#2026-09-10-1\|Announce]] [[https://downloads.php.net/~svpernova09/\|Files]] \|		\| Sep 10 2026 \| Beta 3 [[https://www.php.net/archive/2026.php#2026-09-10-1\|Announce]] [[https://downloads.php.net/~svpernova09/\|Files]] \|
	\| Sep 22 2026 \| Hard feature freeze: features, whether requiring an RFC or not, must be merged only with approval from the RMs. \|		\| Sep 22 2026 \| Hard feature freeze: features, whether requiring an RFC or not, must be merged only with approval from the RMs. \|
-	\| Sep 24 2026 \| <del>RC1</del> (skipped, explanation will follow) \|	+	\| Sep 24 2026 \| <del>RC1</del> (skipped, [[https://scherzer.dev/Blog/20260923-no-php86-rc-1\|explanation]]) \|
	\| Sep 24 2026 \| RC2 \|		\| Sep 24 2026 \| RC2 \|
	\| Oct 08 2026 \| RC3 \|		\| Oct 08 2026 \| RC3 \|