Skip to content

Commit 586ab41

Browse files
kylekatarnlskylekatarnls
committed
Update CarbonInterface
1 parent 5ad58c3 commit 586ab41

File tree

8 files changed

+48
-64
lines changed

8 files changed

+48
-64
lines changed

‎phpdoc.php‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@
3434
'getOffset' => 'int',
3535
'getTimestamp' => 'int',
3636
];
37+
$noInterface = [
38+
'setMicrosecond',
39+
];
3740
$modes = [];
3841
$autoDocLines = [];
3942
$carbon = __DIR__.'/src/Carbon/Carbon.php';
@@ -651,6 +654,8 @@ function dumpParameter(string $method, ReflectionParameter $parameter): string
651654

652655
function compileDoc($autoDocLines, $file)
653656
{
657+
global $noInterface;
658+
654659
$class = 'CarbonInterface';
655660

656661
if (preg_match('`[\\\\/](Carbon\w*)\.php$`', $file, $match)) {
@@ -662,6 +667,12 @@ function compileDoc($autoDocLines, $file)
662667

663668
foreach ($autoDocLines as &$editableLine) {
664669
if (\is_array($editableLine)) {
670+
[$method] = explode('(', $editableLine[2] ?? '');
671+
672+
if (\in_array($method, $noInterface)) {
673+
continue;
674+
}
675+
665676
if (($editableLine[1] ?? '') === 'self') {
666677
$editableLine[1] = $class === 'Carbon' ? '$this' : $class;
667678
}
@@ -814,7 +825,9 @@ function getMethodReturnType(ReflectionMethod $method): string
814825
}
815826
}
816827

817-
$methods .= "\n$methodDocBlock\n public$static function $method($parameters)$return;";
828+
if (!\in_array($method, $noInterface)) {
829+
$methods .= "\n$methodDocBlock\n public$static function $method($parameters)$return;";
830+
}
818831
}
819832

820833
$files->$interface = strtr(preg_replace_callback(

‎src/Carbon/Carbon.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@
345345
* @method $this microseconds(int $value) Set current instance microsecond to the given value.
346346
* @method $this microsecond(int $value) Set current instance microsecond to the given value.
347347
* @method $this setMicroseconds(int $value) Set current instance microsecond to the given value.
348-
* @method $this setMicrosecond(int $value) Set current instance microsecond to the given value.
348+
* @method self setMicrosecond(int $value) Set current instance microsecond to the given value.
349349
* @method $this addYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using date interval).
350350
* @method $this addYear() Add one year to the instance (using date interval).
351351
* @method $this subYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using date interval).

‎src/Carbon/CarbonImmutable.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@
345345
* @method CarbonImmutable microseconds(int $value) Set current instance microsecond to the given value.
346346
* @method CarbonImmutable microsecond(int $value) Set current instance microsecond to the given value.
347347
* @method CarbonImmutable setMicroseconds(int $value) Set current instance microsecond to the given value.
348-
* @method CarbonImmutable setMicrosecond(int $value) Set current instance microsecond to the given value.
348+
* @method self setMicrosecond(int $value) Set current instance microsecond to the given value.
349349
* @method CarbonImmutable addYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using date interval).
350350
* @method CarbonImmutable addYear() Add one year to the instance (using date interval).
351351
* @method CarbonImmutable subYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using date interval).

‎src/Carbon/CarbonInterface.php‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@
361361
* @method CarbonInterface microseconds(int $value) Set current instance microsecond to the given value.
362362
* @method CarbonInterface microsecond(int $value) Set current instance microsecond to the given value.
363363
* @method CarbonInterface setMicroseconds(int $value) Set current instance microsecond to the given value.
364-
* @method CarbonInterface setMicrosecond(int $value) Set current instance microsecond to the given value.
364+
* @method self setMicrosecond(int $value) Set current instance microsecond to the given value.
365365
* @method CarbonInterface addYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using date interval).
366366
* @method CarbonInterface addYear() Add one year to the instance (using date interval).
367367
* @method CarbonInterface subYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using date interval).
@@ -1054,15 +1054,6 @@ public function __set($name, $value);
10541054
#[ReturnTypeWillChange]
10551055
public static function __set_state($dump): static;
10561056

1057-
/**
1058-
* Returns the list of properties to dump on serialize() called on.
1059-
*
1060-
* Only used by PHP < 7.4.
1061-
*
1062-
* @return array
1063-
*/
1064-
public function __sleep();
1065-
10661057
/**
10671058
* Format the instance as a string using the set format
10681059
*
@@ -1358,7 +1349,7 @@ public function copy();
13581349
*
13591350
* @return static|null
13601351
*/
1361-
public static function create($year = 0, $month = 1, $day = 1, $hour = 0, $minute = 0, $second = 0, $timezone = null);
1352+
public static function create($year = 0, $month = 1, $day = 1, $hour = 0, $minute = 0, $second = 0, $timezone = null): ?static;
13621353

13631354
/**
13641355
* Create a Carbon instance from just a date. The time portion is set to now.
@@ -1386,7 +1377,7 @@ public static function createFromDate($year = null, $month = null, $day = null,
13861377
* @return static|null
13871378
*/
13881379
#[ReturnTypeWillChange]
1389-
public static function createFromFormat($format, $time, $timezone = null);
1380+
public static function createFromFormat($format, $time, $timezone = null): ?static;
13901381

13911382
/**
13921383
* Create a Carbon instance from a specific ISO format (same replacements as ->isoFormat()).
@@ -1401,7 +1392,7 @@ public static function createFromFormat($format, $time, $timezone = null);
14011392
*
14021393
* @return static|null
14031394
*/
1404-
public static function createFromIsoFormat(string $format, string $time, $timezone = null, ?string $locale = 'en', ?TranslatorInterface $translator = null);
1395+
public static function createFromIsoFormat(string $format, string $time, $timezone = null, ?string $locale = 'en', ?TranslatorInterface $translator = null): ?static;
14051396

14061397
/**
14071398
* Create a Carbon instance from a specific format and a string in a given language.
@@ -1415,7 +1406,7 @@ public static function createFromIsoFormat(string $format, string $time, $timezo
14151406
*
14161407
* @return static|null
14171408
*/
1418-
public static function createFromLocaleFormat(string $format, string $locale, string $time, $timezone = null);
1409+
public static function createFromLocaleFormat(string $format, string $locale, string $time, $timezone = null): ?static;
14191410

14201411
/**
14211412
* Create a Carbon instance from a specific ISO format and a string in a given language.
@@ -1429,7 +1420,7 @@ public static function createFromLocaleFormat(string $format, string $locale, st
14291420
*
14301421
* @return static|null
14311422
*/
1432-
public static function createFromLocaleIsoFormat(string $format, string $locale, string $time, $timezone = null);
1423+
public static function createFromLocaleIsoFormat(string $format, string $locale, string $time, $timezone = null): ?static;
14331424

14341425
/**
14351426
* Create a Carbon instance from just a time. The date portion is set to today.
@@ -1457,6 +1448,7 @@ public static function createFromTimeString(string $time, DateTimeZone|string|in
14571448
*
14581449
* Timestamp input can be given as int, float or a string containing one or more numbers.
14591450
*/
1451+
#[ReturnTypeWillChange]
14601452
public static function createFromTimestamp(string|int|float $timestamp, DateTimeZone|string|int|null $timezone = null): static;
14611453

14621454
/**
@@ -1525,7 +1517,7 @@ public static function createMidnightDate($year = null, $month = null, $day = nu
15251517
*
15261518
* @return static|null
15271519
*/
1528-
public static function createSafe($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $timezone = null);
1520+
public static function createSafe($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $timezone = null): ?static;
15291521

15301522
/**
15311523
* Create a new Carbon instance from a specific date and time using strict validation.
@@ -2147,13 +2139,22 @@ public function fromNow($syntax = null, $short = false, $parts = 1, $options = n
21472139
/**
21482140
* Create an instance from a serialized string.
21492141
*
2150-
* @param string $value
2142+
* If $value is not from a trusted source, consider using the allowed_classes option to limit
2143+
* the types of objects that can be built, for instance:
2144+
*
2145+
* @example
2146+
* ```php
2147+
* $object = Carbon::fromSerialized($value, ['allowed_classes' => [Carbon::class, CarbonImmutable::class]]);
2148+
* ```
2149+
*
2150+
* @param \Stringable|string $value
2151+
* @param array $options example: ['allowed_classes' => [CarbonImmutable::class]]
21512152
*
21522153
* @throws InvalidFormatException
21532154
*
21542155
* @return static
21552156
*/
2156-
public static function fromSerialized($value): static;
2157+
public static function fromSerialized($value, array $options = []): static;
21572158

21582159
/**
21592160
* Register a custom macro.
@@ -3376,7 +3377,7 @@ public function lte(DateTimeInterface|string $date): bool;
33763377
* echo Carbon::yesterday()->hours(11)->userFormat();
33773378
* ```
33783379
*
3379-
* @param-closure-this static $macro
3380+
* @param-closure-this static $macro
33803381
*/
33813382
public static function macro(string $name, ?callable $macro): void;
33823383

@@ -3392,7 +3393,7 @@ public static function macro(string $name, ?callable $macro): void;
33923393
*
33933394
* @return static|null
33943395
*/
3395-
public static function make($var, DateTimeZone|string|null $timezone = null);
3396+
public static function make($var, DateTimeZone|string|null $timezone = null): ?static;
33963397

33973398
/**
33983399
* Get the maximum instance between a given instance (default now) and the current instance.
@@ -3678,7 +3679,7 @@ public function rawAdd(DateInterval $interval): static;
36783679
*
36793680
* @return static|null
36803681
*/
3681-
public static function rawCreateFromFormat(string $format, string $time, $timezone = null);
3682+
public static function rawCreateFromFormat(string $format, string $time, $timezone = null): ?static;
36823683

36833684
/**
36843685
* @see https://php.net/manual/en/datetime.format.php
@@ -4755,7 +4756,7 @@ public function translateNumber(int $number): string;
47554756
public static function translateTimeString(string $timeString, ?string $from = null, ?string $to = null, int $mode = self::TRANSLATE_ALL): string;
47564757

47574758
/**
4758-
* Translate a time string from the current locale (`$date->locale()`) to an other.
4759+
* Translate a time string from the current locale (`$date->locale()`) to another one.
47594760
*
47604761
* @param string $timeString time string to translate
47614762
* @param string|null $to output locale of the result returned ("en" by default)
@@ -4784,6 +4785,8 @@ public function translatedFormat(string $format): string;
47844785

47854786
/**
47864787
* Set the timezone or returns the timezone name if no arguments passed.
4788+
*
4789+
* @return ($value is null ? string : static)
47874790
*/
47884791
public function tz(DateTimeZone|string|int|null $value = null): static|string;
47894792

‎src/Carbon/Factory.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,9 @@
6565
* @method Carbon createStrict(?int $year = 0, ?int $month = 1, ?int $day = 1, ?int $hour = 0, ?int $minute = 0, ?int $second = 0, $timezone = null) Create a new Carbon instance from a specific date and time using strict validation.
6666
* @method mixed executeWithLocale(string $locale, callable $func) Set the current locale to the given, execute the passed function, reset the locale to previous one,
6767
* then return the result of the closure (or null if the closure was void).
68-
* @method Carbon fromSerialized($value) Create an instance from a serialized string.
68+
* @method Carbon fromSerialized($value, array $options = []) Create an instance from a serialized string.
69+
* If $value is not from a trusted source, consider using the allowed_classes option to limit
70+
* the types of objects that can be built, for instance:
6971
* @method array getAvailableLocales() Returns the list of internally available locales and already loaded custom locales.
7072
* (It will ignore custom translator dynamic loading.)
7173
* @method Language[] getAvailableLocalesInfo() Returns list of Language object for each available locale. This object allow you to get the ISO name, native

‎src/Carbon/FactoryImmutable.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@
6262
* @method CarbonImmutable createStrict(?int $year = 0, ?int $month = 1, ?int $day = 1, ?int $hour = 0, ?int $minute = 0, ?int $second = 0, $timezone = null) Create a new Carbon instance from a specific date and time using strict validation.
6363
* @method mixed executeWithLocale(string $locale, callable $func) Set the current locale to the given, execute the passed function, reset the locale to previous one,
6464
* then return the result of the closure (or null if the closure was void).
65-
* @method CarbonImmutable fromSerialized($value) Create an instance from a serialized string.
65+
* @method CarbonImmutable fromSerialized($value, array $options = []) Create an instance from a serialized string.
66+
* If $value is not from a trusted source, consider using the allowed_classes option to limit
67+
* the types of objects that can be built, for instance:
6668
* @method array getAvailableLocales() Returns the list of internally available locales and already loaded custom locales.
6769
* (It will ignore custom translator dynamic loading.)
6870
* @method Language[] getAvailableLocalesInfo() Returns list of Language object for each available locale. This object allow you to get the ISO name, native

‎src/Carbon/Traits/Date.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -372,7 +372,7 @@
372372
* @method CarbonInterface microseconds(int $value) Set current instance microsecond to the given value.
373373
* @method CarbonInterface microsecond(int $value) Set current instance microsecond to the given value.
374374
* @method CarbonInterface setMicroseconds(int $value) Set current instance microsecond to the given value.
375-
* @method CarbonInterface setMicrosecond(int $value) Set current instance microsecond to the given value.
375+
* @method self setMicrosecond(int $value) Set current instance microsecond to the given value.
376376
* @method CarbonInterface addYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using date interval).
377377
* @method CarbonInterface addYear() Add one year to the instance (using date interval).
378378
* @method CarbonInterface subYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using date interval).

‎tests/CarbonImmutable/SerializationTest.php‎

Lines changed: 0 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -160,24 +160,6 @@ public function testMsgPackExtension(): void
160160
$this->assertSame($string, $copy->format('Y-m-d H:i:s.u e'));
161161
}
162162

163-
public function testSleepRawMethod(): void
164-
{
165-
$date = Carbon::parse('2018-06-01 21:25:13.321654 Europe/Vilnius');
166-
167-
$expected = ['date', 'timezone_type', 'timezone'];
168-
169-
if (\extension_loaded('msgpack')) {
170-
$expected[] = 'dumpDateProperties';
171-
}
172-
173-
$this->assertSame($expected, $date->__sleep());
174-
175-
$date->locale('fr_FR');
176-
$expected[] = 'dumpLocale';
177-
178-
$this->assertSame($expected, $date->__sleep());
179-
}
180-
181163
public function testSerializeRawMethod(): void
182164
{
183165
$date = Carbon::parse('2018-06-01 21:25:13.321654 Europe/Vilnius');
@@ -203,24 +185,6 @@ public function testSerializeRawMethod(): void
203185
$this->assertSame($expected, $date->__serialize());
204186
}
205187

206-
public function testWakeupRawMethod(): void
207-
{
208-
$tz = $this->firstValidTimezoneAmong(['America/Los_Angeles', 'US/Pacific'])->getName();
209-
210-
/** @var Carbon $date */
211-
$date = (new ReflectionClass(Carbon::class))->newInstanceWithoutConstructor();
212-
213-
@$date->date = '1990-01-17 10:28:07';
214-
@$date->timezone_type = 3;
215-
@$date->timezone = $tz;
216-
@$date->dumpLocale = 'es';
217-
218-
$date->__wakeup();
219-
220-
$this->assertSame('1990-01-17 10:28:07 '.$tz, $date->format('Y-m-d H:i:s e'));
221-
$this->assertSame('es', $date->locale);
222-
}
223-
224188
public function testUnserializeRawMethod(): void
225189
{
226190
/** @var Carbon $date */

0 commit comments

Comments
 (0)