From a22de1fcae7a4911574a4a7294f0f0007aaff057 Mon Sep 17 00:00:00 2001 From: KyleKatarn Date: Tue, 15 Oct 2019 18:55:37 +0200 Subject: [PATCH 1/4] #356 Add toDateTimeLocalString precision parameter --- src/Carbon/CarbonInterface.php | 6 +++++- src/Carbon/Factory.php | 1 + src/Carbon/FactoryImmutable.php | 1 + src/Carbon/Traits/Converter.php | 25 +++++++++++++++++++++++-- src/Carbon/Traits/Date.php | 2 +- tests/Carbon/StringsTest.php | 17 ++++++++++++++++- 6 files changed, 47 insertions(+), 5 deletions(-) diff --git a/src/Carbon/CarbonInterface.php b/src/Carbon/CarbonInterface.php index 4072bb67a9..6a6486f410 100644 --- a/src/Carbon/CarbonInterface.php +++ b/src/Carbon/CarbonInterface.php @@ -2055,6 +2055,8 @@ public function getSettings(); */ public static function getTestNow(); + public static function getTimeFormatByPrecision($unitPrecision); + /** * Get the translation of the current week day name (with context for languages with multiple forms). * @@ -4161,11 +4163,13 @@ public function toDateTimeImmutable(); * @example * ``` * echo Carbon::now()->toDateTimeLocalString(); + * echo "\n"; + * echo Carbon::now()->toDateTimeLocalString('minute'); // You can specify precision among: minute, second, millisecond and microsecond * ``` * * @return string */ - public function toDateTimeLocalString(); + public function toDateTimeLocalString($unitPrecision = 'second'); /** * Format the instance as date and time diff --git a/src/Carbon/Factory.php b/src/Carbon/Factory.php index 8c428067c4..0ee9a3b6d4 100644 --- a/src/Carbon/Factory.php +++ b/src/Carbon/Factory.php @@ -66,6 +66,7 @@ * @method int getMidDayAt() get midday/noon hour * @method Closure|Carbon getTestNow() Get the Carbon instance (real or mock) to be returned when a "now" * instance is created. + * @method Carbon getTimeFormatByPrecision($unitPrecision) * @method string getTranslationMessageWith($translator, string $key, string $locale = null, string $default = null) Returns raw translation message for a given key. * @method \Symfony\Component\Translation\TranslatorInterface getTranslator() Get the default translator instance in use. * @method int getWeekEndsAt() Get the last day of week diff --git a/src/Carbon/FactoryImmutable.php b/src/Carbon/FactoryImmutable.php index 27b4b9039b..122c4bff3c 100644 --- a/src/Carbon/FactoryImmutable.php +++ b/src/Carbon/FactoryImmutable.php @@ -66,6 +66,7 @@ * @method int getMidDayAt() get midday/noon hour * @method Closure|CarbonImmutable getTestNow() Get the Carbon instance (real or mock) to be returned when a "now" * instance is created. + * @method CarbonImmutable getTimeFormatByPrecision($unitPrecision) * @method string getTranslationMessageWith($translator, string $key, string $locale = null, string $default = null) Returns raw translation message for a given key. * @method \Symfony\Component\Translation\TranslatorInterface getTranslator() Get the default translator instance in use. * @method int getWeekEndsAt() Get the last day of week diff --git a/src/Carbon/Traits/Converter.php b/src/Carbon/Traits/Converter.php index 8ad6373a25..024a9aa024 100644 --- a/src/Carbon/Traits/Converter.php +++ b/src/Carbon/Traits/Converter.php @@ -18,6 +18,7 @@ use Closure; use DateTime; use DateTimeImmutable; +use InvalidArgumentException; /** * Trait Converter. @@ -184,19 +185,39 @@ public function toDateTimeString() return $this->rawFormat('Y-m-d H:i:s'); } + public static function getTimeFormatByPrecision($unitPrecision) + { + switch (static::singularUnit($unitPrecision)) { + case 'minute': + return 'H:i'; + case 'second': + return 'H:i:s'; + case 'm': + case 'millisecond': + return 'H:i:s.v'; + case 'µ': + case 'microsecond': + return 'H:i:s.u'; + } + + throw new InvalidArgumentException('Precision unit expected among: minute, second, millisecond and microsecond.'); + } + /** * Format the instance as date and time T-separated with no timezone * * @example * ``` * echo Carbon::now()->toDateTimeLocalString(); + * echo "\n"; + * echo Carbon::now()->toDateTimeLocalString('minute'); // You can specify precision among: minute, second, millisecond and microsecond * ``` * * @return string */ - public function toDateTimeLocalString() + public function toDateTimeLocalString($unitPrecision = 'second') { - return $this->rawFormat('Y-m-d\TH:i:s'); + return $this->rawFormat('Y-m-d\T'.static::getTimeFormatByPrecision($unitPrecision)); } /** diff --git a/src/Carbon/Traits/Date.php b/src/Carbon/Traits/Date.php index d695da0b1e..5fc99de31e 100644 --- a/src/Carbon/Traits/Date.php +++ b/src/Carbon/Traits/Date.php @@ -2368,7 +2368,7 @@ public function setUnit($unit, $value = null) */ public static function singularUnit(string $unit): string { - $unit = rtrim(strtolower($unit), 's'); + $unit = rtrim(mb_strtolower($unit), 's'); if ($unit === 'centurie') { return 'century'; diff --git a/tests/Carbon/StringsTest.php b/tests/Carbon/StringsTest.php index b533d2eb8e..51cd620606 100644 --- a/tests/Carbon/StringsTest.php +++ b/tests/Carbon/StringsTest.php @@ -15,6 +15,7 @@ use Carbon\CarbonInterface; use Carbon\Factory; use DateTime; +use InvalidArgumentException; use Tests\AbstractTestCase; use Tests\Carbon\Fixtures\BadIsoCarbon; use Tests\Carbon\Fixtures\MyCarbon; @@ -115,8 +116,22 @@ public function testToDateString() public function testToDateTimeLocalString() { - $d = Carbon::create(1975, 12, 25, 14, 15, 16); + $d = Carbon::create(1975, 12, 25, 14, 15, 16.615342); $this->assertSame('1975-12-25T14:15:16', $d->toDateTimeLocalString()); + $this->assertSame('1975-12-25T14:15', $d->toDateTimeLocalString('minute')); + $this->assertSame('1975-12-25T14:15:16', $d->toDateTimeLocalString('second')); + $this->assertSame('1975-12-25T14:15:16.615', $d->toDateTimeLocalString('millisecond')); + $this->assertSame('1975-12-25T14:15:16.615342', $d->toDateTimeLocalString('µs')); + + $message = null; + + try { + $d->toDateTimeLocalString('hour'); + } catch (InvalidArgumentException $exception) { + $message = $exception->getMessage(); + } + + $this->assertSame('Precision unit expected among: minute, second, millisecond and microsecond.', $message); } public function testToFormattedDateString() From 60a07933e0c6237db56a643316238e5d79cb315c Mon Sep 17 00:00:00 2001 From: KyleKatarn Date: Wed, 16 Oct 2019 09:04:32 +0200 Subject: [PATCH 2/4] Add documentation for getTimeFormatByPrecision --- src/Carbon/Traits/Converter.php | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/Carbon/Traits/Converter.php b/src/Carbon/Traits/Converter.php index 024a9aa024..17329b69c2 100644 --- a/src/Carbon/Traits/Converter.php +++ b/src/Carbon/Traits/Converter.php @@ -185,6 +185,13 @@ public function toDateTimeString() return $this->rawFormat('Y-m-d H:i:s'); } + /** + * Return a format from H:i to H:i:s.u according to given unit precision. + * + * @param string $unitPrecision "minute", "second", "millisecond" or "microsecond" + * + * @return string + */ public static function getTimeFormatByPrecision($unitPrecision) { switch (static::singularUnit($unitPrecision)) { From c7958bfa8c6839ba476ccc2de30c6db8a9dd977e Mon Sep 17 00:00:00 2001 From: KyleKatarn Date: Wed, 16 Oct 2019 09:09:25 +0200 Subject: [PATCH 3/4] Add $unitPrecision parameters to relevant methods Add $unitPrecision parameters to: - toTimeString - toDateTimeString - toIso8601ZuluString --- src/Carbon/Traits/Converter.php | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/src/Carbon/Traits/Converter.php b/src/Carbon/Traits/Converter.php index 17329b69c2..ea0d43c173 100644 --- a/src/Carbon/Traits/Converter.php +++ b/src/Carbon/Traits/Converter.php @@ -163,11 +163,13 @@ public function toFormattedDateString() * echo Carbon::now()->toTimeString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toTimeString() + public function toTimeString($unitPrecision = 'second') { - return $this->rawFormat('H:i:s'); + return $this->rawFormat(static::getTimeFormatByPrecision($unitPrecision)); } /** @@ -178,11 +180,13 @@ public function toTimeString() * echo Carbon::now()->toDateTimeString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toDateTimeString() + public function toDateTimeString($unitPrecision = 'second') { - return $this->rawFormat('Y-m-d H:i:s'); + return $this->rawFormat('Y-m-d '.static::getTimeFormatByPrecision($unitPrecision)); } /** @@ -220,6 +224,8 @@ public static function getTimeFormatByPrecision($unitPrecision) * echo Carbon::now()->toDateTimeLocalString('minute'); // You can specify precision among: minute, second, millisecond and microsecond * ``` * + * @param string $unitPrecision + * * @return string */ public function toDateTimeLocalString($unitPrecision = 'second') @@ -310,11 +316,13 @@ public function toRfc822String() * echo Carbon::now()->toIso8601ZuluString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toIso8601ZuluString() + public function toIso8601ZuluString($unitPrecision = 'second') { - return $this->copy()->utc()->rawFormat('Y-m-d\TH:i:s\Z'); + return $this->copy()->utc()->rawFormat('Y-m-d\T'.static::getTimeFormatByPrecision($unitPrecision).'\Z'); } /** From 697e5c396b54b34daecef1a986c336917303687d Mon Sep 17 00:00:00 2001 From: KyleKatarn Date: Wed, 16 Oct 2019 09:13:04 +0200 Subject: [PATCH 4/4] Update PHPDoc --- src/Carbon/CarbonInterface.php | 21 ++++++++++++++++++--- src/Carbon/Factory.php | 2 +- src/Carbon/FactoryImmutable.php | 2 +- 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/src/Carbon/CarbonInterface.php b/src/Carbon/CarbonInterface.php index 6a6486f410..96691b79ee 100644 --- a/src/Carbon/CarbonInterface.php +++ b/src/Carbon/CarbonInterface.php @@ -2055,6 +2055,13 @@ public function getSettings(); */ public static function getTestNow(); + /** + * Return a format from H:i to H:i:s.u according to given unit precision. + * + * @param string $unitPrecision "minute", "second", "millisecond" or "microsecond" + * + * @return string + */ public static function getTimeFormatByPrecision($unitPrecision); /** @@ -4167,6 +4174,8 @@ public function toDateTimeImmutable(); * echo Carbon::now()->toDateTimeLocalString('minute'); // You can specify precision among: minute, second, millisecond and microsecond * ``` * + * @param string $unitPrecision + * * @return string */ public function toDateTimeLocalString($unitPrecision = 'second'); @@ -4179,9 +4188,11 @@ public function toDateTimeLocalString($unitPrecision = 'second'); * echo Carbon::now()->toDateTimeString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toDateTimeString(); + public function toDateTimeString($unitPrecision = 'second'); /** * Format the instance with day, date and time @@ -4250,9 +4261,11 @@ public function toIso8601String(); * echo Carbon::now()->toIso8601ZuluString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toIso8601ZuluString(); + public function toIso8601ZuluString($unitPrecision = 'second'); /** * Return the ISO-8601 string (ex: 1977-04-22T06:00:00Z) with UTC timezone. @@ -4442,9 +4455,11 @@ public function toString(); * echo Carbon::now()->toTimeString(); * ``` * + * @param string $unitPrecision + * * @return string */ - public function toTimeString(); + public function toTimeString($unitPrecision = 'second'); /** * Format the instance as W3C diff --git a/src/Carbon/Factory.php b/src/Carbon/Factory.php index 0ee9a3b6d4..e80d67a873 100644 --- a/src/Carbon/Factory.php +++ b/src/Carbon/Factory.php @@ -66,7 +66,7 @@ * @method int getMidDayAt() get midday/noon hour * @method Closure|Carbon getTestNow() Get the Carbon instance (real or mock) to be returned when a "now" * instance is created. - * @method Carbon getTimeFormatByPrecision($unitPrecision) + * @method string getTimeFormatByPrecision($unitPrecision) Return a format from H:i to H:i:s.u according to given unit precision. * @method string getTranslationMessageWith($translator, string $key, string $locale = null, string $default = null) Returns raw translation message for a given key. * @method \Symfony\Component\Translation\TranslatorInterface getTranslator() Get the default translator instance in use. * @method int getWeekEndsAt() Get the last day of week diff --git a/src/Carbon/FactoryImmutable.php b/src/Carbon/FactoryImmutable.php index 122c4bff3c..a910e99780 100644 --- a/src/Carbon/FactoryImmutable.php +++ b/src/Carbon/FactoryImmutable.php @@ -66,7 +66,7 @@ * @method int getMidDayAt() get midday/noon hour * @method Closure|CarbonImmutable getTestNow() Get the Carbon instance (real or mock) to be returned when a "now" * instance is created. - * @method CarbonImmutable getTimeFormatByPrecision($unitPrecision) + * @method string getTimeFormatByPrecision($unitPrecision) Return a format from H:i to H:i:s.u according to given unit precision. * @method string getTranslationMessageWith($translator, string $key, string $locale = null, string $default = null) Returns raw translation message for a given key. * @method \Symfony\Component\Translation\TranslatorInterface getTranslator() Get the default translator instance in use. * @method int getWeekEndsAt() Get the last day of week