1
<?php
2

3
/**
4
 * This file is part of the Carbon package.
5
 *
6
 * (c) Brian Nesbitt <brian@nesbot.com>
7
 *
8
 * For the full copyright and license information, please view the LICENSE
9
 * file that was distributed with this source code.
10
 */
11
namespace Carbon\Traits;
12

13
use Carbon\CarbonInterface;
14
use DateTimeInterface;
15
use Throwable;
16

17
/**
18
 * Trait Options.
19
 *
20
 * Embed base methods to change settings of Carbon classes.
21
 *
22
 * Depends on the following methods:
23
 *
24
 * @method \Carbon\Carbon|\Carbon\CarbonImmutable shiftTimezone($timezone) Set the timezone
25
 */
26
trait Options
27
{
28
    use Localization;
29

30
    /**
31
     * Customizable PHP_INT_SIZE override.
32
     *
33
     * @var int
34
     */
35
    public static $PHPIntSize = PHP_INT_SIZE;
36

37
    /**
38
     * First day of week.
39
     *
40
     * @var int|string
41
     */
42
    protected static $weekStartsAt = CarbonInterface::MONDAY;
43

44
    /**
45
     * Last day of week.
46
     *
47
     * @var int|string
48
     */
49
    protected static $weekEndsAt = CarbonInterface::SUNDAY;
50

51
    /**
52
     * Days of weekend.
53
     *
54
     * @var array
55
     */
56
    protected static $weekendDays = [
57
        CarbonInterface::SATURDAY,
58
        CarbonInterface::SUNDAY,
59
    ];
60

61
    /**
62
     * Format regex patterns.
63
     *
64
     * @var array
65
     */
66
    protected static $regexFormats = [
67
        'd' => '(3[01]|[12][0-9]|0[1-9])',
68
        'D' => '(Sun|Mon|Tue|Wed|Thu|Fri|Sat)',
69
        'j' => '([123][0-9]|[1-9])',
70
        'l' => '([a-zA-Z]{2,})',
71
        'N' => '([1-7])',
72
        'S' => '(st|nd|rd|th)',
73
        'w' => '([0-6])',
74
        'z' => '(36[0-5]|3[0-5][0-9]|[12][0-9]{2}|[1-9]?[0-9])',
75
        'W' => '(5[012]|[1-4][0-9]|[1-9])',
76
        'F' => '([a-zA-Z]{2,})',
77
        'm' => '(1[012]|0[1-9])',
78
        'M' => '([a-zA-Z]{3})',
79
        'n' => '(1[012]|[1-9])',
80
        't' => '(2[89]|3[01])',
81
        'L' => '(0|1)',
82
        'o' => '([1-9][0-9]{0,4})',
83
        'Y' => '([1-9]?[0-9]{4})',
84
        'y' => '([0-9]{2})',
85
        'a' => '(am|pm)',
86
        'A' => '(AM|PM)',
87
        'B' => '([0-9]{3})',
88
        'g' => '(1[012]|[1-9])',
89
        'G' => '(2[0-3]|1?[0-9])',
90
        'h' => '(1[012]|0[1-9])',
91
        'H' => '(2[0-3]|[01][0-9])',
92
        'i' => '([0-5][0-9])',
93
        's' => '([0-5][0-9])',
94
        'u' => '([0-9]{1,6})',
95
        'v' => '([0-9]{1,3})',
96
        'e' => '([a-zA-Z]{1,5})|([a-zA-Z]*\\/[a-zA-Z]*)',
97
        'I' => '(0|1)',
98
        'O' => '([+-](1[012]|0[0-9])[0134][05])',
99
        'P' => '([+-](1[012]|0[0-9]):[0134][05])',
100
        'T' => '([a-zA-Z]{1,5})',
101
        'Z' => '(-?[1-5]?[0-9]{1,4})',
102
        'U' => '([0-9]*)',
103

104
        // The formats below are combinations of the above formats.
105
        'c' => '(([1-9]?[0-9]{4})-(1[012]|0[1-9])-(3[01]|[12][0-9]|0[1-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])[+-](1[012]|0[0-9]):([0134][05]))', // Y-m-dTH:i:sP
106
        'r' => '(([a-zA-Z]{3}), ([123][0-9]|0[1-9]) ([a-zA-Z]{3}) ([1-9]?[0-9]{4}) (2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9]) [+-](1[012]|0[0-9])([0134][05]))', // D, d M Y H:i:s O
107
    ];
108

109
    /**
110
     * Format modifiers (such as available in createFromFormat) regex patterns.
111
     *
112
     * @var array
113
     */
114
    protected static $regexFormatModifiers = [
115
        '*' => '.+',
116
        ' ' => '[   ]',
117
        '#' => '[;:\\/.,()-]',
118
        '?' => '([^a]|[a])',
119
        '!' => '',
120
        '|' => '',
121
        '+' => '',
122
    ];
123

124
    /**
125
     * Indicates if months should be calculated with overflow.
126
     * Global setting.
127
     *
128
     * @var bool
129
     */
130
    protected static $monthsOverflow = true;
131

132
    /**
133
     * Indicates if years should be calculated with overflow.
134
     * Global setting.
135
     *
136
     * @var bool
137
     */
138
    protected static $yearsOverflow = true;
139

140
    /**
141
     * Indicates if the strict mode is in use.
142
     * Global setting.
143
     *
144
     * @var bool
145
     */
146
    protected static $strictModeEnabled = true;
147

148
    /**
149
     * Function to call instead of format.
150
     *
151
     * @var string|callable|null
152
     */
153
    protected static $formatFunction = null;
154

155
    /**
156
     * Function to call instead of createFromFormat.
157
     *
158
     * @var string|callable|null
159
     */
160
    protected static $createFromFormatFunction = null;
161

162
    /**
163
     * Function to call instead of parse.
164
     *
165
     * @var string|callable|null
166
     */
167
    protected static $parseFunction = null;
168

169
    /**
170
     * Indicates if months should be calculated with overflow.
171
     * Specific setting.
172
     *
173
     * @var bool|null
174
     */
175
    protected $localMonthsOverflow = null;
176

177
    /**
178
     * Indicates if years should be calculated with overflow.
179
     * Specific setting.
180
     *
181
     * @var bool|null
182
     */
183
    protected $localYearsOverflow = null;
184

185
    /**
186
     * Indicates if the strict mode is in use.
187
     * Specific setting.
188
     *
189
     * @var bool|null
190
     */
191
    protected $localStrictModeEnabled = null;
192

193
    /**
194
     * Options for diffForHumans and forHumans methods.
195
     *
196
     * @var bool|null
197
     */
198
    protected $localHumanDiffOptions = null;
199

200
    /**
201
     * Format to use on string cast.
202
     *
203
     * @var string|null
204
     */
205
    protected $localToStringFormat = null;
206

207
    /**
208
     * Format to use on JSON serialization.
209
     *
210
     * @var string|null
211
     */
212
    protected $localSerializer = null;
213

214
    /**
215
     * Instance-specific macros.
216
     *
217
     * @var array|null
218
     */
219
    protected $localMacros = null;
220

221
    /**
222
     * Instance-specific generic macros.
223
     *
224
     * @var array|null
225
     */
226
    protected $localGenericMacros = null;
227

228
    /**
229
     * Function to call instead of format.
230
     *
231
     * @var string|callable|null
232
     */
233
    protected $localFormatFunction = null;
234

235
    /**
236
     * @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
237
     *             You should rather use the ->settings() method.
238
     * @see settings
239
     *
240
     * Enable the strict mode (or disable with passing false).
241
     *
242
     * @param bool $strictModeEnabled
243
     */
244 1
    public static function useStrictMode($strictModeEnabled = true)
245
    {
246 1
        static::$strictModeEnabled = $strictModeEnabled;
247
    }
248

249
    /**
250
     * Returns true if the strict mode is globally in use, false else.
251
     * (It can be overridden in specific instances.)
252
     *
253
     * @return bool
254
     */
255 1
    public static function isStrictModeEnabled()
256
    {
257 1
        return static::$strictModeEnabled;
258
    }
259

260
    /**
261
     * @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
262
     *             You should rather use the ->settings() method.
263
     *             Or you can use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants
264
     *             are available for quarters, years, decade, centuries, millennia (singular and plural forms).
265
     * @see settings
266
     *
267
     * Indicates if months should be calculated with overflow.
268
     *
269
     * @param bool $monthsOverflow
270
     *
271
     * @return void
272
     */
273 1
    public static function useMonthsOverflow($monthsOverflow = true)
274
    {
275 1
        static::$monthsOverflow = $monthsOverflow;
276
    }
277

278
    /**
279
     * @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
280
     *             You should rather use the ->settings() method.
281
     *             Or you can use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants
282
     *             are available for quarters, years, decade, centuries, millennia (singular and plural forms).
283
     * @see settings
284
     *
285
     * Reset the month overflow behavior.
286
     *
287
     * @return void
288
     */
289 1
    public static function resetMonthsOverflow()
290
    {
291 1
        static::$monthsOverflow = true;
292
    }
293

294
    /**
295
     * Get the month overflow global behavior (can be overridden in specific instances).
296
     *
297
     * @return bool
298
     */
299 1
    public static function shouldOverflowMonths()
300
    {
301 1
        return static::$monthsOverflow;
302
    }
303

304
    /**
305
     * @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
306
     *             You should rather use the ->settings() method.
307
     *             Or you can use method variants: addYearsWithOverflow/addYearsNoOverflow, same variants
308
     *             are available for quarters, years, decade, centuries, millennia (singular and plural forms).
309
     * @see settings
310
     *
311
     * Indicates if years should be calculated with overflow.
312
     *
313
     * @param bool $yearsOverflow
314
     *
315
     * @return void
316
     */
317 1
    public static function useYearsOverflow($yearsOverflow = true)
318
    {
319 1
        static::$yearsOverflow = $yearsOverflow;
320
    }
321

322
    /**
323
     * @deprecated To avoid conflict between different third-party libraries, static setters should not be used.
324
     *             You should rather use the ->settings() method.
325
     *             Or you can use method variants: addYearsWithOverflow/addYearsNoOverflow, same variants
326
     *             are available for quarters, years, decade, centuries, millennia (singular and plural forms).
327
     * @see settings
328
     *
329
     * Reset the month overflow behavior.
330
     *
331
     * @return void
332
     */
333 1
    public static function resetYearsOverflow()
334
    {
335 1
        static::$yearsOverflow = true;
336
    }
337

338
    /**
339
     * Get the month overflow global behavior (can be overridden in specific instances).
340
     *
341
     * @return bool
342
     */
343 1
    public static function shouldOverflowYears()
344
    {
345 1
        return static::$yearsOverflow;
346
    }
347

348
    /**
349
     * Set specific options.
350
     *  - strictMode: true|false|null
351
     *  - monthOverflow: true|false|null
352
     *  - yearOverflow: true|false|null
353
     *  - humanDiffOptions: int|null
354
     *  - toStringFormat: string|Closure|null
355
     *  - toJsonFormat: string|Closure|null
356
     *  - locale: string|null
357
     *  - timezone: \DateTimeZone|string|int|null
358
     *  - macros: array|null
359
     *  - genericMacros: array|null
360
     *
361
     * @param array $settings
362
     *
363
     * @return $this|static
364
     */
365 1
    public function settings(array $settings)
366
    {
367 1
        $this->localStrictModeEnabled = $settings['strictMode'] ?? null;
368 1
        $this->localMonthsOverflow = $settings['monthOverflow'] ?? null;
369 1
        $this->localYearsOverflow = $settings['yearOverflow'] ?? null;
370 1
        $this->localHumanDiffOptions = $settings['humanDiffOptions'] ?? null;
371 1
        $this->localToStringFormat = $settings['toStringFormat'] ?? null;
372 1
        $this->localSerializer = $settings['toJsonFormat'] ?? null;
373 1
        $this->localMacros = $settings['macros'] ?? null;
374 1
        $this->localGenericMacros = $settings['genericMacros'] ?? null;
375 1
        $this->localFormatFunction = $settings['formatFunction'] ?? null;
376

377 1
        if (isset($settings['locale'])) {
378 1
            $locales = $settings['locale'];
379

380 1
            if (!\is_array($locales)) {
381 1
                $locales = [$locales];
382
            }
383

384 1
            $this->locale(...$locales);
385
        }
386

387 1
        if (isset($settings['timezone'])) {
388 1
            return $this->shiftTimezone($settings['timezone']);
389
        }
390

391 1
        return $this;
392
    }
393

394
    /**
395
     * Returns current local settings.
396
     *
397
     * @return array
398
     */
399 1
    public function getSettings()
400
    {
401 1
        $settings = [];
402
        $map = [
403 1
            'localStrictModeEnabled' => 'strictMode',
404
            'localMonthsOverflow' => 'monthOverflow',
405
            'localYearsOverflow' => 'yearOverflow',
406
            'localHumanDiffOptions' => 'humanDiffOptions',
407
            'localToStringFormat' => 'toStringFormat',
408
            'localSerializer' => 'toJsonFormat',
409
            'localMacros' => 'macros',
410
            'localGenericMacros' => 'genericMacros',
411
            'locale' => 'locale',
412
            'tzName' => 'timezone',
413
            'localFormatFunction' => 'formatFunction',
414
        ];
415 1
        foreach ($map as $property => $key) {
416 1
            $value = $this->$property ?? null;
417 1
            if ($value !== null) {
418 1
                $settings[$key] = $value;
419
            }
420
        }
421

422 1
        return $settings;
423
    }
424

425
    /**
426
     * Show truthy properties on var_dump().
427
     *
428
     * @return array
429
     */
430 1
    public function __debugInfo()
431
    {
432
        $infos = array_filter(get_object_vars($this), function ($var) {
433 1
            return $var;
434 1
        });
435

436 1
        foreach (['dumpProperties', 'constructedObjectId'] as $property) {
437 1
            if (isset($infos[$property])) {
438 1
                unset($infos[$property]);
439
            }
440
        }
441

442 1
        $this->addExtraDebugInfos($infos);
443

444 1
        return $infos;
445
    }
446

447 1
    protected function addExtraDebugInfos(&$infos): void
448
    {
449 1
        if ($this instanceof CarbonInterface || $this instanceof DateTimeInterface) {
450
            try {
451 1
                if (!isset($infos['date'])) {
452 1
                    $infos['date'] = $this->format(CarbonInterface::MOCK_DATETIME_FORMAT);
453
                }
454

455 1
                if (!isset($infos['timezone'])) {
456 1
                    $infos['timezone'] = $this->tzName;
457
                }
458 1
            } catch (Throwable $exception) {
459
                // noop
460
            }
461
        }
462
    }
463
}

Read our documentation on viewing source code .

Loading