Skip to content

Commit 0e6be3d

Browse files
kylekatarnlskylekatarnls
committed
Update CarbonInterface
1 parent 843cda1 commit 0e6be3d

File tree

8 files changed

+48
-65
lines changed

8 files changed

+48
-65
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
@@ -365,7 +365,7 @@
365365
* @method CarbonInterface microseconds(int $value) Set current instance microsecond to the given value.
366366
* @method CarbonInterface microsecond(int $value) Set current instance microsecond to the given value.
367367
* @method CarbonInterface setMicroseconds(int $value) Set current instance microsecond to the given value.
368-
* @method CarbonInterface setMicrosecond(int $value) Set current instance microsecond to the given value.
368+
* @method self setMicrosecond(int $value) Set current instance microsecond to the given value.
369369
* @method CarbonInterface addYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using date interval).
370370
* @method CarbonInterface addYear() Add one year to the instance (using date interval).
371371
* @method CarbonInterface subYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using date interval).
@@ -939,15 +939,6 @@ public function __set($name, $value);
939939
#[ReturnTypeWillChange]
940940
public static function __set_state($dump): static;
941941

942-
/**
943-
* Returns the list of properties to dump on serialize() called on.
944-
*
945-
* Only used by PHP < 7.4.
946-
*
947-
* @return array
948-
*/
949-
public function __sleep();
950-
951942
/**
952943
* Format the instance as a string using the set format
953944
*
@@ -1243,7 +1234,7 @@ public function copy();
12431234
*
12441235
* @return static|null
12451236
*/
1246-
public static function create($year = 0, $month = 1, $day = 1, $hour = 0, $minute = 0, $second = 0, $timezone = null);
1237+
public static function create($year = 0, $month = 1, $day = 1, $hour = 0, $minute = 0, $second = 0, $timezone = null): ?static;
12471238

12481239
/**
12491240
* Create a Carbon instance from just a date. The time portion is set to now.
@@ -1271,7 +1262,7 @@ public static function createFromDate($year = null, $month = null, $day = null,
12711262
* @return static|null
12721263
*/
12731264
#[ReturnTypeWillChange]
1274-
public static function createFromFormat($format, $time, $timezone = null);
1265+
public static function createFromFormat($format, $time, $timezone = null): ?static;
12751266

12761267
/**
12771268
* Create a Carbon instance from a specific ISO format (same replacements as ->isoFormat()).
@@ -1286,7 +1277,7 @@ public static function createFromFormat($format, $time, $timezone = null);
12861277
*
12871278
* @return static|null
12881279
*/
1289-
public static function createFromIsoFormat(string $format, string $time, $timezone = null, ?string $locale = 'en', ?TranslatorInterface $translator = null);
1280+
public static function createFromIsoFormat(string $format, string $time, $timezone = null, ?string $locale = 'en', ?TranslatorInterface $translator = null): ?static;
12901281

12911282
/**
12921283
* Create a Carbon instance from a specific format and a string in a given language.
@@ -1300,7 +1291,7 @@ public static function createFromIsoFormat(string $format, string $time, $timezo
13001291
*
13011292
* @return static|null
13021293
*/
1303-
public static function createFromLocaleFormat(string $format, string $locale, string $time, $timezone = null);
1294+
public static function createFromLocaleFormat(string $format, string $locale, string $time, $timezone = null): ?static;
13041295

13051296
/**
13061297
* Create a Carbon instance from a specific ISO format and a string in a given language.
@@ -1314,7 +1305,7 @@ public static function createFromLocaleFormat(string $format, string $locale, st
13141305
*
13151306
* @return static|null
13161307
*/
1317-
public static function createFromLocaleIsoFormat(string $format, string $locale, string $time, $timezone = null);
1308+
public static function createFromLocaleIsoFormat(string $format, string $locale, string $time, $timezone = null): ?static;
13181309

13191310
/**
13201311
* Create a Carbon instance from just a time. The date portion is set to today.
@@ -1342,6 +1333,7 @@ public static function createFromTimeString(string $time, DateTimeZone|string|in
13421333
*
13431334
* Timestamp input can be given as int, float or a string containing one or more numbers.
13441335
*/
1336+
#[ReturnTypeWillChange]
13451337
public static function createFromTimestamp(string|int|float $timestamp, DateTimeZone|string|int|null $timezone = null): static;
13461338

13471339
/**
@@ -1410,7 +1402,7 @@ public static function createMidnightDate($year = null, $month = null, $day = nu
14101402
*
14111403
* @return static|null
14121404
*/
1413-
public static function createSafe($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $timezone = null);
1405+
public static function createSafe($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $timezone = null): ?static;
14141406

14151407
/**
14161408
* Create a new Carbon instance from a specific date and time using strict validation.
@@ -2032,13 +2024,22 @@ public function fromNow($syntax = null, $short = false, $parts = 1, $options = n
20322024
/**
20332025
* Create an instance from a serialized string.
20342026
*
2035-
* @param string $value
2027+
* If $value is not from a trusted source, consider using the allowed_classes option to limit
2028+
* the types of objects that can be built, for instance:
2029+
*
2030+
* @example
2031+
* ```php
2032+
* $object = Carbon::fromSerialized($value, ['allowed_classes' => [Carbon::class, CarbonImmutable::class]]);
2033+
* ```
2034+
*
2035+
* @param \Stringable|string $value
2036+
* @param array $options example: ['allowed_classes' => [CarbonImmutable::class]]
20362037
*
20372038
* @throws InvalidFormatException
20382039
*
20392040
* @return static
20402041
*/
2041-
public static function fromSerialized($value): static;
2042+
public static function fromSerialized($value, array $options = []): static;
20422043

20432044
/**
20442045
* Register a custom macro.
@@ -3261,7 +3262,7 @@ public function lte(DateTimeInterface|string $date): bool;
32613262
* echo Carbon::yesterday()->hours(11)->userFormat();
32623263
* ```
32633264
*
3264-
* @param-closure-this static $macro
3265+
* @param-closure-this static $macro
32653266
*/
32663267
public static function macro(string $name, ?callable $macro): void;
32673268

@@ -3277,7 +3278,7 @@ public static function macro(string $name, ?callable $macro): void;
32773278
*
32783279
* @return static|null
32793280
*/
3280-
public static function make($var, DateTimeZone|string|null $timezone = null);
3281+
public static function make($var, DateTimeZone|string|null $timezone = null): ?static;
32813282

32823283
/**
32833284
* Get the maximum instance between a given instance (default now) and the current instance.
@@ -3563,7 +3564,7 @@ public function rawAdd(DateInterval $interval): static;
35633564
*
35643565
* @return static|null
35653566
*/
3566-
public static function rawCreateFromFormat(string $format, string $time, $timezone = null);
3567+
public static function rawCreateFromFormat(string $format, string $time, $timezone = null): ?static;
35673568

35683569
/**
35693570
* @see https://php.net/manual/en/datetime.format.php
@@ -4640,7 +4641,7 @@ public function translateNumber(int $number): string;
46404641
public static function translateTimeString(string $timeString, ?string $from = null, ?string $to = null, int $mode = self::TRANSLATE_ALL): string;
46414642

46424643
/**
4643-
* Translate a time string from the current locale (`$date->locale()`) to an other.
4644+
* Translate a time string from the current locale (`$date->locale()`) to another one.
46444645
*
46454646
* @param string $timeString time string to translate
46464647
* @param string|null $to output locale of the result returned ("en" by default)
@@ -4669,6 +4670,8 @@ public function translatedFormat(string $format): string;
46694670

46704671
/**
46714672
* Set the timezone or returns the timezone name if no arguments passed.
4673+
*
4674+
* @return ($value is null ? string : static)
46724675
*/
46734676
public function tz(DateTimeZone|string|int|null $value = null): static|string;
46744677

‎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 & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -161,24 +161,6 @@ public function testMsgPackExtension(): void
161161
$this->assertSame($string, $copy->format('Y-m-d H:i:s.u e'));
162162
}
163163

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

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

0 commit comments

Comments
 (0)