vendor/nesbot/carbon/src/Carbon/CarbonPeriod.php

   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
  12 namespace Carbon;
  13
  14 use BadMethodCallException;
  15 use Closure;
  16 use Countable;
  17 use DateInterval;
  18 use DateTime;
  19 use DateTimeInterface;
  20 use InvalidArgumentException;
  21 use Iterator;
  22 use ReflectionClass;
  23 use ReflectionFunction;
  24 use ReflectionMethod;
  25 use RuntimeException;
  26
  27 /**
  28  * Substitution of DatePeriod with some modifications and many more features.
  29  * Fully compatible with PHP 5.3+!
  30  *
  31  * @method static CarbonPeriod start($date, $inclusive = null) Create instance specifying start date.
  32  * @method static CarbonPeriod since($date, $inclusive = null) Alias for start().
  33  * @method static CarbonPeriod sinceNow($inclusive = null) Create instance with start date set to now.
  34  * @method static CarbonPeriod end($date = null, $inclusive = null) Create instance specifying end date.
  35  * @method static CarbonPeriod until($date = null, $inclusive = null) Alias for end().
  36  * @method static CarbonPeriod untilNow($inclusive = null) Create instance with end date set to now.
  37  * @method static CarbonPeriod dates($start, $end = null) Create instance with start and end date.
  38  * @method static CarbonPeriod between($start, $end = null) Create instance with start and end date.
  39  * @method static CarbonPeriod recurrences($recurrences = null) Create instance with maximum number of recurrences.
  40  * @method static CarbonPeriod times($recurrences = null) Alias for recurrences().
  41  * @method static CarbonPeriod options($options = null) Create instance with options.
  42  * @method static CarbonPeriod toggle($options, $state = null) Create instance with options toggled on or off.
  43  * @method static CarbonPeriod filter($callback, $name = null) Create instance with filter added to the stack.
  44  * @method static CarbonPeriod push($callback, $name = null) Alias for filter().
  45  * @method static CarbonPeriod prepend($callback, $name = null) Create instance with filter prepened to the stack.
  46  * @method static CarbonPeriod filters(array $filters) Create instance with filters stack.
  47  * @method static CarbonPeriod interval($interval) Create instance with given date interval.
  48  * @method static CarbonPeriod each($interval) Create instance with given date interval.
  49  * @method static CarbonPeriod every($interval) Create instance with given date interval.
  50  * @method static CarbonPeriod step($interval) Create instance with given date interval.
  51  * @method static CarbonPeriod stepBy($interval) Create instance with given date interval.
  52  * @method static CarbonPeriod invert() Create instance with inverted date interval.
  53  * @method static CarbonPeriod years($years = 1) Create instance specifying a number of years for date interval.
  54  * @method static CarbonPeriod year($years = 1) Alias for years().
  55  * @method static CarbonPeriod months($months = 1) Create instance specifying a number of months for date interval.
  56  * @method static CarbonPeriod month($months = 1) Alias for months().
  57  * @method static CarbonPeriod weeks($weeks = 1) Create instance specifying a number of weeks for date interval.
  58  * @method static CarbonPeriod week($weeks = 1) Alias for weeks().
  59  * @method static CarbonPeriod days($days = 1) Create instance specifying a number of days for date interval.
  60  * @method static CarbonPeriod dayz($days = 1) Alias for days().
  61  * @method static CarbonPeriod day($days = 1) Alias for days().
  62  * @method static CarbonPeriod hours($hours = 1) Create instance specifying a number of hours for date interval.
  63  * @method static CarbonPeriod hour($hours = 1) Alias for hours().
  64  * @method static CarbonPeriod minutes($minutes = 1) Create instance specifying a number of minutes for date interval.
  65  * @method static CarbonPeriod minute($minutes = 1) Alias for minutes().
  66  * @method static CarbonPeriod seconds($seconds = 1) Create instance specifying a number of seconds for date interval.
  67  * @method static CarbonPeriod second($seconds = 1) Alias for seconds().
  68  * @method CarbonPeriod start($date, $inclusive = null) Change the period start date.
  69  * @method CarbonPeriod since($date, $inclusive = null) Alias for start().
  70  * @method CarbonPeriod sinceNow($inclusive = null) Change the period start date to now.
  71  * @method CarbonPeriod end($date = null, $inclusive = null) Change the period end date.
  72  * @method CarbonPeriod until($date = null, $inclusive = null) Alias for end().
  73  * @method CarbonPeriod untilNow($inclusive = null) Change the period end date to now.
  74  * @method CarbonPeriod dates($start, $end = null) Change the period start and end date.
  75  * @method CarbonPeriod recurrences($recurrences = null) Change the maximum number of recurrences.
  76  * @method CarbonPeriod times($recurrences = null) Alias for recurrences().
  77  * @method CarbonPeriod options($options = null) Change the period options.
  78  * @method CarbonPeriod toggle($options, $state = null) Toggle given options on or off.
  79  * @method CarbonPeriod filter($callback, $name = null) Add a filter to the stack.
  80  * @method CarbonPeriod push($callback, $name = null) Alias for filter().
  81  * @method CarbonPeriod prepend($callback, $name = null) Prepend a filter to the stack.
  82  * @method CarbonPeriod filters(array $filters = array()) Set filters stack.
  83  * @method CarbonPeriod interval($interval) Change the period date interval.
  84  * @method CarbonPeriod invert() Invert the period date interval.
  85  * @method CarbonPeriod years($years = 1) Set the years portion of the date interval.
  86  * @method CarbonPeriod year($years = 1) Alias for years().
  87  * @method CarbonPeriod months($months = 1) Set the months portion of the date interval.
  88  * @method CarbonPeriod month($months = 1) Alias for months().
  89  * @method CarbonPeriod weeks($weeks = 1) Set the weeks portion of the date interval.
  90  * @method CarbonPeriod week($weeks = 1) Alias for weeks().
  91  * @method CarbonPeriod days($days = 1) Set the days portion of the date interval.
  92  * @method CarbonPeriod dayz($days = 1) Alias for days().
  93  * @method CarbonPeriod day($days = 1) Alias for days().
  94  * @method CarbonPeriod hours($hours = 1) Set the hours portion of the date interval.
  95  * @method CarbonPeriod hour($hours = 1) Alias for hours().
  96  * @method CarbonPeriod minutes($minutes = 1) Set the minutes portion of the date interval.
  97  * @method CarbonPeriod minute($minutes = 1) Alias for minutes().
  98  * @method CarbonPeriod seconds($seconds = 1) Set the seconds portion of the date interval.
  99  * @method CarbonPeriod second($seconds = 1) Alias for seconds().
 100  */
 101 class CarbonPeriod implements Iterator, Countable
 102 {
 103     /**
 104      * Built-in filters.
 105      *
 106      * @var string
 107      */
 108     const RECURRENCES_FILTER = 'Carbon\CarbonPeriod::filterRecurrences';
 109     const END_DATE_FILTER = 'Carbon\CarbonPeriod::filterEndDate';
 110
 111     /**
 112      * Special value which can be returned by filters to end iteration. Also a filter.
 113      *
 114      * @var string
 115      */
 116     const END_ITERATION = 'Carbon\CarbonPeriod::endIteration';
 117
 118     /**
 119      * Available options.
 120      *
 121      * @var int
 122      */
 123     const EXCLUDE_START_DATE = 1;
 124     const EXCLUDE_END_DATE = 2;
 125
 126     /**
 127      * Number of maximum attempts before giving up on finding next valid date.
 128      *
 129      * @var int
 130      */
 131     const NEXT_MAX_ATTEMPTS = 1000;
 132
 133     /**
 134      * The registered macros.
 135      *
 136      * @var array
 137      */
 138     protected static $macros = array();
 139
 140     /**
 141      * Underlying date interval instance. Always present, one day by default.
 142      *
 143      * @var CarbonInterval
 144      */
 145     protected $dateInterval;
 146
 147     /**
 148      * Whether current date interval was set by default.
 149      *
 150      * @var bool
 151      */
 152     protected $isDefaultInterval;
 153
 154     /**
 155      * The filters stack.
 156      *
 157      * @var array
 158      */
 159     protected $filters = array();
 160
 161     /**
 162      * Period start date. Applied on rewind. Always present, now by default.
 163      *
 164      * @var Carbon
 165      */
 166     protected $startDate;
 167
 168     /**
 169      * Period end date. For inverted interval should be before the start date. Applied via a filter.
 170      *
 171      * @var Carbon|null
 172      */
 173     protected $endDate;
 174
 175     /**
 176      * Limit for number of recurrences. Applied via a filter.
 177      *
 178      * @var int|null
 179      */
 180     protected $recurrences;
 181
 182     /**
 183      * Iteration options.
 184      *
 185      * @var int
 186      */
 187     protected $options;
 188
 189     /**
 190      * Index of current date. Always sequential, even if some dates are skipped by filters.
 191      * Equal to null only before the first iteration.
 192      *
 193      * @var int
 194      */
 195     protected $key;
 196
 197     /**
 198      * Current date. May temporarily hold unaccepted value when looking for a next valid date.
 199      * Equal to null only before the first iteration.
 200      *
 201      * @var Carbon
 202      */
 203     protected $current;
 204
 205     /**
 206      * Timezone of current date. Taken from the start date.
 207      *
 208      * @var \DateTimeZone|null
 209      */
 210     protected $timezone;
 211
 212     /**
 213      * The cached validation result for current date.
 214      *
 215      * @var bool|string|null
 216      */
 217     protected $validationResult;
 218
 219     /**
 220      * Create a new instance.
 221      *
 222      * @return static
 223      */
 224     public static function create()
 225     {
 226         return static::createFromArray(func_get_args());
 227     }
 228
 229     /**
 230      * Create a new instance from an array of parameters.
 231      *
 232      * @param array $params
 233      *
 234      * @return static
 235      */
 236     public static function createFromArray(array $params)
 237     {
 238         // PHP 5.3 equivalent of new static(...$params).
 239         $reflection = new ReflectionClass(get_class());
 240         /** @var static $instance */
 241         $instance = $reflection->newInstanceArgs($params);
 242
 243         return $instance;
 244     }
 245
 246     /**
 247      * Create CarbonPeriod from ISO 8601 string.
 248      *
 249      * @param string   $iso
 250      * @param int|null $options
 251      *
 252      * @return static
 253      */
 254     public static function createFromIso($iso, $options = null)
 255     {
 256         $params = static::parseIso8601($iso);
 257
 258         $instance = static::createFromArray($params);
 259
 260         if ($options !== null) {
 261             $instance->setOptions($options);
 262         }
 263
 264         return $instance;
 265     }
 266
 267     /**
 268      * Return whether given interval contains non zero value of any time unit.
 269      *
 270      * @param \DateInterval $interval
 271      *
 272      * @return bool
 273      */
 274     protected static function intervalHasTime(DateInterval $interval)
 275     {
 276         // The array_key_exists and get_object_vars are used as a workaround to check microsecond support.
 277         // Both isset and property_exists will fail on PHP 7.0.14 - 7.0.21 due to the following bug:
 278         // https://bugs.php.net/bug.php?id=74852
 279         return $interval->h || $interval->i || $interval->s || array_key_exists('f', get_object_vars($interval)) && $interval->f;
 280     }
 281
 282     /**
 283      * Return whether given callable is a string pointing to one of Carbon's is* methods
 284      * and should be automatically converted to a filter callback.
 285      *
 286      * @param callable $callable
 287      *
 288      * @return bool
 289      */
 290     protected static function isCarbonPredicateMethod($callable)
 291     {
 292         return is_string($callable) && substr($callable, 0, 2) === 'is' && (method_exists('Carbon\Carbon', $callable) || Carbon::hasMacro($callable));
 293     }
 294
 295     /**
 296      * Return whether given variable is an ISO 8601 specification.
 297      *
 298      * Note: Check is very basic, as actual validation will be done later when parsing.
 299      * We just want to ensure that variable is not any other type of a valid parameter.
 300      *
 301      * @param mixed $var
 302      *
 303      * @return bool
 304      */
 305     protected static function isIso8601($var)
 306     {
 307         if (!is_string($var)) {
 308             return false;
 309         }
 310
 311         // Match slash but not within a timezone name.
 312         $part = '[a-z]+(?:[_-][a-z]+)*';
 313
 314         preg_match("#\b$part/$part\b|(/)#i", $var, $match);
 315
 316         return isset($match[1]);
 317     }
 318
 319     /**
 320      * Parse given ISO 8601 string into an array of arguments.
 321      *
 322      * @param string $iso
 323      *
 324      * @return array
 325      */
 326     protected static function parseIso8601($iso)
 327     {
 328         $result = array();
 329
 330         $interval = null;
 331         $start = null;
 332         $end = null;
 333
 334         foreach (explode('/', $iso) as $key => $part) {
 335             if ($key === 0 && preg_match('/^R([0-9]*)$/', $part, $match)) {
 336                 $parsed = strlen($match[1]) ? (int) $match[1] : null;
 337             } elseif ($interval === null && $parsed = CarbonInterval::make($part)) {
 338                 $interval = $part;
 339             } elseif ($start === null && $parsed = Carbon::make($part)) {
 340                 $start = $part;
 341             } elseif ($end === null && $parsed = Carbon::make(static::addMissingParts($start, $part))) {
 342                 $end = $part;
 343             } else {
 344                 throw new InvalidArgumentException("Invalid ISO 8601 specification: $iso.");
 345             }
 346
 347             $result[] = $parsed;
 348         }
 349
 350         return $result;
 351     }
 352
 353     /**
 354      * Add missing parts of the target date from the soure date.
 355      *
 356      * @param string $source
 357      * @param string $target
 358      *
 359      * @return string
 360      */
 361     protected static function addMissingParts($source, $target)
 362     {
 363         $pattern = '/'.preg_replace('/[0-9]+/', '[0-9]+', preg_quote($target, '/')).'$/';
 364
 365         $result = preg_replace($pattern, $target, $source, 1, $count);
 366
 367         return $count ? $result : $target;
 368     }
 369
 370     /**
 371      * Register a custom macro.
 372      *
 373      * @param string          $name
 374      * @param object|callable $macro
 375      *
 376      * @return void
 377      */
 378     public static function macro($name, $macro)
 379     {
 380         static::$macros[$name] = $macro;
 381     }
 382
 383     /**
 384      * Register macros from a mixin object.
 385      *
 386      * @param object $mixin
 387      *
 388      * @throws \ReflectionException
 389      *
 390      * @return void
 391      */
 392     public static function mixin($mixin)
 393     {
 394         $reflection = new ReflectionClass($mixin);
 395
 396         $methods = $reflection->getMethods(
 397             ReflectionMethod::IS_PUBLIC | ReflectionMethod::IS_PROTECTED
 398         );
 399
 400         foreach ($methods as $method) {
 401             $method->setAccessible(true);
 402
 403             static::macro($method->name, $method->invoke($mixin));
 404         }
 405     }
 406
 407     /**
 408      * Check if macro is registered.
 409      *
 410      * @param string $name
 411      *
 412      * @return bool
 413      */
 414     public static function hasMacro($name)
 415     {
 416         return isset(static::$macros[$name]);
 417     }
 418
 419     /**
 420      * Provide static proxy for instance aliases.
 421      *
 422      * @param string $method
 423      * @param array  $parameters
 424      *
 425      * @return mixed
 426      */
 427     public static function __callStatic($method, $parameters)
 428     {
 429         return call_user_func_array(
 430             array(new static, $method), $parameters
 431         );
 432     }
 433
 434     /**
 435      * CarbonPeriod constructor.
 436      *
 437      * @throws InvalidArgumentException
 438      */
 439     public function __construct()
 440     {
 441         // Parse and assign arguments one by one. First argument may be an ISO 8601 spec,
 442         // which will be first parsed into parts and then processed the same way.
 443         $arguments = func_get_args();
 444
 445         if (count($arguments) && static::isIso8601($iso = $arguments[0])) {
 446             array_splice($arguments, 0, 1, static::parseIso8601($iso));
 447         }
 448
 449         foreach ($arguments as $argument) {
 450             if ($this->dateInterval === null && $parsed = CarbonInterval::make($argument)) {
 451                 $this->setDateInterval($parsed);
 452             } elseif ($this->startDate === null && $parsed = Carbon::make($argument)) {
 453                 $this->setStartDate($parsed);
 454             } elseif ($this->endDate === null && $parsed = Carbon::make($argument)) {
 455                 $this->setEndDate($parsed);
 456             } elseif ($this->recurrences === null && $this->endDate === null && is_numeric($argument)) {
 457                 $this->setRecurrences($argument);
 458             } elseif ($this->options === null && (is_int($argument) || $argument === null)) {
 459                 $this->setOptions($argument);
 460             } else {
 461                 throw new InvalidArgumentException('Invalid constructor parameters.');
 462             }
 463         }
 464
 465         if ($this->startDate === null) {
 466             $this->setStartDate(Carbon::now());
 467         }
 468
 469         if ($this->dateInterval === null) {
 470             $this->setDateInterval(CarbonInterval::day());
 471
 472             $this->isDefaultInterval = true;
 473         }
 474
 475         if ($this->options === null) {
 476             $this->setOptions(0);
 477         }
 478     }
 479
 480     /**
 481      * Change the period date interval.
 482      *
 483      * @param DateInterval|string $interval
 484      *
 485      * @throws \InvalidArgumentException
 486      *
 487      * @return $this
 488      */
 489     public function setDateInterval($interval)
 490     {
 491         if (!$interval = CarbonInterval::make($interval)) {
 492             throw new InvalidArgumentException('Invalid interval.');
 493         }
 494
 495         if ($interval->spec() === 'PT0S') {
 496             throw new InvalidArgumentException('Empty interval is not accepted.');
 497         }
 498
 499         $this->dateInterval = $interval;
 500
 501         $this->isDefaultInterval = false;
 502
 503         $this->handleChangedParameters();
 504
 505         return $this;
 506     }
 507
 508     /**
 509      * Invert the period date interval.
 510      *
 511      * @return $this
 512      */
 513     public function invertDateInterval()
 514     {
 515         $interval = $this->dateInterval->invert();
 516
 517         return $this->setDateInterval($interval);
 518     }
 519
 520     /**
 521      * Set start and end date.
 522      *
 523      * @param DateTime|DateTimeInterface|string      $start
 524      * @param DateTime|DateTimeInterface|string|null $end
 525      *
 526      * @return $this
 527      */
 528     public function setDates($start, $end)
 529     {
 530         $this->setStartDate($start);
 531         $this->setEndDate($end);
 532
 533         return $this;
 534     }
 535
 536     /**
 537      * Change the period options.
 538      *
 539      * @param int|null $options
 540      *
 541      * @throws \InvalidArgumentException
 542      *
 543      * @return $this
 544      */
 545     public function setOptions($options)
 546     {
 547         if (!is_int($options) && !is_null($options)) {
 548             throw new InvalidArgumentException('Invalid options.');
 549         }
 550
 551         $this->options = $options ?: 0;
 552
 553         $this->handleChangedParameters();
 554
 555         return $this;
 556     }
 557
 558     /**
 559      * Get the period options.
 560      *
 561      * @return int
 562      */
 563     public function getOptions()
 564     {
 565         return $this->options;
 566     }
 567
 568     /**
 569      * Toggle given options on or off.
 570      *
 571      * @param int       $options
 572      * @param bool|null $state
 573      *
 574      * @throws \InvalidArgumentException
 575      *
 576      * @return $this
 577      */
 578     public function toggleOptions($options, $state = null)
 579     {
 580         if ($state === null) {
 581             $state = ($this->options & $options) !== $options;
 582         }
 583
 584         return $this->setOptions($state ?
 585             $this->options | $options :
 586             $this->options & ~$options
 587         );
 588     }
 589
 590     /**
 591      * Toggle EXCLUDE_START_DATE option.
 592      *
 593      * @param bool $state
 594      *
 595      * @return $this
 596      */
 597     public function excludeStartDate($state = true)
 598     {
 599         return $this->toggleOptions(static::EXCLUDE_START_DATE, $state);
 600     }
 601
 602     /**
 603      * Toggle EXCLUDE_END_DATE option.
 604      *
 605      * @param bool $state
 606      *
 607      * @return $this
 608      */
 609     public function excludeEndDate($state = true)
 610     {
 611         return $this->toggleOptions(static::EXCLUDE_END_DATE, $state);
 612     }
 613
 614     /**
 615      * Get the underlying date interval.
 616      *
 617      * @return CarbonInterval
 618      */
 619     public function getDateInterval()
 620     {
 621         return $this->dateInterval->copy();
 622     }
 623
 624     /**
 625      * Get start date of the period.
 626      *
 627      * @return Carbon
 628      */
 629     public function getStartDate()
 630     {
 631         return $this->startDate->copy();
 632     }
 633
 634     /**
 635      * Get end date of the period.
 636      *
 637      * @return Carbon|null
 638      */
 639     public function getEndDate()
 640     {
 641         if ($this->endDate) {
 642             return $this->endDate->copy();
 643         }
 644     }
 645
 646     /**
 647      * Get number of recurrences.
 648      *
 649      * @return int|null
 650      */
 651     public function getRecurrences()
 652     {
 653         return $this->recurrences;
 654     }
 655
 656     /**
 657      * Returns true if the start date should be excluded.
 658      *
 659      * @return bool
 660      */
 661     public function isStartExcluded()
 662     {
 663         return ($this->options & static::EXCLUDE_START_DATE) !== 0;
 664     }
 665
 666     /**
 667      * Returns true if the end date should be excluded.
 668      *
 669      * @return bool
 670      */
 671     public function isEndExcluded()
 672     {
 673         return ($this->options & static::EXCLUDE_END_DATE) !== 0;
 674     }
 675
 676     /**
 677      * Add a filter to the stack.
 678      *
 679      * @param callable $callback
 680      * @param string   $name
 681      *
 682      * @return $this
 683      */
 684     public function addFilter($callback, $name = null)
 685     {
 686         $tuple = $this->createFilterTuple(func_get_args());
 687
 688         $this->filters[] = $tuple;
 689
 690         $this->handleChangedParameters();
 691
 692         return $this;
 693     }
 694
 695     /**
 696      * Prepend a filter to the stack.
 697      *
 698      * @param callable $callback
 699      * @param string   $name
 700      *
 701      * @return $this
 702      */
 703     public function prependFilter($callback, $name = null)
 704     {
 705         $tuple = $this->createFilterTuple(func_get_args());
 706
 707         array_unshift($this->filters, $tuple);
 708
 709         $this->handleChangedParameters();
 710
 711         return $this;
 712     }
 713
 714     /**
 715      * Create a filter tuple from raw parameters.
 716      *
 717      * Will create an automatic filter callback for one of Carbon's is* methods.
 718      *
 719      * @param array $parameters
 720      *
 721      * @return array
 722      */
 723     protected function createFilterTuple(array $parameters)
 724     {
 725         $method = array_shift($parameters);
 726
 727         if (!$this->isCarbonPredicateMethod($method)) {
 728             return array($method, array_shift($parameters));
 729         }
 730
 731         return array(function ($date) use ($method, $parameters) {
 732             return call_user_func_array(array($date, $method), $parameters);
 733         }, $method);
 734     }
 735
 736     /**
 737      * Remove a filter by instance or name.
 738      *
 739      * @param callable|string $filter
 740      *
 741      * @return $this
 742      */
 743     public function removeFilter($filter)
 744     {
 745         $key = is_callable($filter) ? 0 : 1;
 746
 747         $this->filters = array_values(array_filter(
 748             $this->filters,
 749             function ($tuple) use ($key, $filter) {
 750                 return $tuple[$key] !== $filter;
 751             }
 752         ));
 753
 754         $this->updateInternalState();
 755
 756         $this->handleChangedParameters();
 757
 758         return $this;
 759     }
 760
 761     /**
 762      * Return whether given instance or name is in the filter stack.
 763      *
 764      * @param callable|string $filter
 765      *
 766      * @return bool
 767      */
 768     public function hasFilter($filter)
 769     {
 770         $key = is_callable($filter) ? 0 : 1;
 771
 772         foreach ($this->filters as $tuple) {
 773             if ($tuple[$key] === $filter) {
 774                 return true;
 775             }
 776         }
 777
 778         return false;
 779     }
 780
 781     /**
 782      * Get filters stack.
 783      *
 784      * @return array
 785      */
 786     public function getFilters()
 787     {
 788         return $this->filters;
 789     }
 790
 791     /**
 792      * Set filters stack.
 793      *
 794      * @param array $filters
 795      *
 796      * @return $this
 797      */
 798     public function setFilters(array $filters)
 799     {
 800         $this->filters = $filters;
 801
 802         $this->updateInternalState();
 803
 804         $this->handleChangedParameters();
 805
 806         return $this;
 807     }
 808
 809     /**
 810      * Reset filters stack.
 811      *
 812      * @return $this
 813      */
 814     public function resetFilters()
 815     {
 816         $this->filters = array();
 817
 818         if ($this->endDate !== null) {
 819             $this->filters[] = array(static::END_DATE_FILTER, null);
 820         }
 821
 822         if ($this->recurrences !== null) {
 823             $this->filters[] = array(static::RECURRENCES_FILTER, null);
 824         }
 825
 826         $this->handleChangedParameters();
 827
 828         return $this;
 829     }
 830
 831     /**
 832      * Update properties after removing built-in filters.
 833      *
 834      * @return void
 835      */
 836     protected function updateInternalState()
 837     {
 838         if (!$this->hasFilter(static::END_DATE_FILTER)) {
 839             $this->endDate = null;
 840         }
 841
 842         if (!$this->hasFilter(static::RECURRENCES_FILTER)) {
 843             $this->recurrences = null;
 844         }
 845     }
 846
 847     /**
 848      * Add a recurrences filter (set maximum number of recurrences).
 849      *
 850      * @param int|null $recurrences
 851      *
 852      * @throws \InvalidArgumentException
 853      *
 854      * @return $this
 855      */
 856     public function setRecurrences($recurrences)
 857     {
 858         if (!is_numeric($recurrences) && !is_null($recurrences) || $recurrences < 0) {
 859             throw new InvalidArgumentException('Invalid number of recurrences.');
 860         }
 861
 862         if ($recurrences === null) {
 863             return $this->removeFilter(static::RECURRENCES_FILTER);
 864         }
 865
 866         $this->recurrences = (int) $recurrences;
 867
 868         if (!$this->hasFilter(static::RECURRENCES_FILTER)) {
 869             return $this->addFilter(static::RECURRENCES_FILTER);
 870         }
 871
 872         $this->handleChangedParameters();
 873
 874         return $this;
 875     }
 876
 877     /**
 878      * Recurrences filter callback (limits number of recurrences).
 879      *
 880      * @param \Carbon\Carbon $current
 881      * @param int            $key
 882      *
 883      * @return bool|string
 884      */
 885     protected function filterRecurrences($current, $key)
 886     {
 887         if ($key < $this->recurrences) {
 888             return true;
 889         }
 890
 891         return static::END_ITERATION;
 892     }
 893
 894     /**
 895      * Change the period start date.
 896      *
 897      * @param DateTime|DateTimeInterface|string $date
 898      * @param bool|null                         $inclusive
 899      *
 900      * @throws \InvalidArgumentException
 901      *
 902      * @return $this
 903      */
 904     public function setStartDate($date, $inclusive = null)
 905     {
 906         if (!$date = Carbon::make($date)) {
 907             throw new InvalidArgumentException('Invalid start date.');
 908         }
 909
 910         $this->startDate = $date;
 911
 912         if ($inclusive !== null) {
 913             $this->toggleOptions(static::EXCLUDE_START_DATE, !$inclusive);
 914         }
 915
 916         return $this;
 917     }
 918
 919     /**
 920      * Change the period end date.
 921      *
 922      * @param DateTime|DateTimeInterface|string|null $date
 923      * @param bool|null                              $inclusive
 924      *
 925      * @throws \InvalidArgumentException
 926      *
 927      * @return $this
 928      */
 929     public function setEndDate($date, $inclusive = null)
 930     {
 931         if (!is_null($date) && !$date = Carbon::make($date)) {
 932             throw new InvalidArgumentException('Invalid end date.');
 933         }
 934
 935         if (!$date) {
 936             return $this->removeFilter(static::END_DATE_FILTER);
 937         }
 938
 939         $this->endDate = $date;
 940
 941         if ($inclusive !== null) {
 942             $this->toggleOptions(static::EXCLUDE_END_DATE, !$inclusive);
 943         }
 944
 945         if (!$this->hasFilter(static::END_DATE_FILTER)) {
 946             return $this->addFilter(static::END_DATE_FILTER);
 947         }
 948
 949         $this->handleChangedParameters();
 950
 951         return $this;
 952     }
 953
 954     /**
 955      * End date filter callback.
 956      *
 957      * @param \Carbon\Carbon $current
 958      *
 959      * @return bool|string
 960      */
 961     protected function filterEndDate($current)
 962     {
 963         if (!$this->isEndExcluded() && $current == $this->endDate) {
 964             return true;
 965         }
 966
 967         if ($this->dateInterval->invert ? $current > $this->endDate : $current < $this->endDate) {
 968             return true;
 969         }
 970
 971         return static::END_ITERATION;
 972     }
 973
 974     /**
 975      * End iteration filter callback.
 976      *
 977      * @return string
 978      */
 979     protected function endIteration()
 980     {
 981         return static::END_ITERATION;
 982     }
 983
 984     /**
 985      * Handle change of the parameters.
 986      */
 987     protected function handleChangedParameters()
 988     {
 989         $this->validationResult = null;
 990     }
 991
 992     /**
 993      * Validate current date and stop iteration when necessary.
 994      *
 995      * Returns true when current date is valid, false if it is not, or static::END_ITERATION
 996      * when iteration should be stopped.
 997      *
 998      * @return bool|static::END_ITERATION
 999      */
1000     protected function validateCurrentDate()
1001     {
1002         if ($this->current === null) {
1003             $this->rewind();
1004         }
1005
1006         // Check after the first rewind to avoid repeating the initial validation.
1007         if ($this->validationResult !== null) {
1008             return $this->validationResult;
1009         }
1010
1011         return $this->validationResult = $this->checkFilters();
1012     }
1013
1014     /**
1015      * Check whether current value and key pass all the filters.
1016      *
1017      * @return bool|string
1018      */
1019     protected function checkFilters()
1020     {
1021         $current = $this->prepareForReturn($this->current);
1022
1023         foreach ($this->filters as $tuple) {
1024             $result = call_user_func(
1025                 $tuple[0], $current->copy(), $this->key, $this
1026             );
1027
1028             if ($result === static::END_ITERATION) {
1029                 return static::END_ITERATION;
1030             }
1031
1032             if (!$result) {
1033                 return false;
1034             }
1035         }
1036
1037         return true;
1038     }
1039
1040     /**
1041      * Prepare given date to be returned to the external logic.
1042      *
1043      * @param Carbon $date
1044      *
1045      * @return Carbon
1046      */
1047     protected function prepareForReturn(Carbon $date)
1048     {
1049         $date = $date->copy();
1050
1051         if ($this->timezone) {
1052             $date->setTimezone($this->timezone);
1053         }
1054
1055         return $date;
1056     }
1057
1058     /**
1059      * Check if the current position is valid.
1060      *
1061      * @return bool
1062      */
1063     public function valid()
1064     {
1065         return $this->validateCurrentDate() === true;
1066     }
1067
1068     /**
1069      * Return the current key.
1070      *
1071      * @return int|null
1072      */
1073     public function key()
1074     {
1075         if ($this->valid()) {
1076             return $this->key;
1077         }
1078     }
1079
1080     /**
1081      * Return the current date.
1082      *
1083      * @return Carbon|null
1084      */
1085     public function current()
1086     {
1087         if ($this->valid()) {
1088             return $this->prepareForReturn($this->current);
1089         }
1090     }
1091
1092     /**
1093      * Move forward to the next date.
1094      *
1095      * @throws \RuntimeException
1096      *
1097      * @return void
1098      */
1099     public function next()
1100     {
1101         if ($this->current === null) {
1102             $this->rewind();
1103         }
1104
1105         if ($this->validationResult !== static::END_ITERATION) {
1106             $this->key++;
1107
1108             $this->incrementCurrentDateUntilValid();
1109         }
1110     }
1111
1112     /**
1113      * Rewind to the start date.
1114      *
1115      * Iterating over a date in the UTC timezone avoids bug during backward DST change.
1116      *
1117      * @see https://bugs.php.net/bug.php?id=72255
1118      * @see https://bugs.php.net/bug.php?id=74274
1119      * @see https://wiki.php.net/rfc/datetime_and_daylight_saving_time
1120      *
1121      * @throws \RuntimeException
1122      *
1123      * @return void
1124      */
1125     public function rewind()
1126     {
1127         $this->key = 0;
1128         $this->current = $this->startDate->copy();
1129         $this->timezone = static::intervalHasTime($this->dateInterval) ? $this->current->getTimezone() : null;
1130
1131         if ($this->timezone) {
1132             $this->current->setTimezone('UTC');
1133         }
1134
1135         $this->validationResult = null;
1136
1137         if ($this->isStartExcluded() || $this->validateCurrentDate() === false) {
1138             $this->incrementCurrentDateUntilValid();
1139         }
1140     }
1141
1142     /**
1143      * Skip iterations and returns iteration state (false if ended, true if still valid).
1144      *
1145      * @param int $count steps number to skip (1 by default)
1146      *
1147      * @return bool
1148      */
1149     public function skip($count = 1)
1150     {
1151         for ($i = $count; $this->valid() && $i > 0; $i--) {
1152             $this->next();
1153         }
1154
1155         return $this->valid();
1156     }
1157
1158     /**
1159      * Keep incrementing the current date until a valid date is found or the iteration is ended.
1160      *
1161      * @throws \RuntimeException
1162      *
1163      * @return void
1164      */
1165     protected function incrementCurrentDateUntilValid()
1166     {
1167         $attempts = 0;
1168
1169         do {
1170             $this->current->add($this->dateInterval);
1171
1172             $this->validationResult = null;
1173
1174             if (++$attempts > static::NEXT_MAX_ATTEMPTS) {
1175                 throw new RuntimeException('Could not find next valid date.');
1176             }
1177         } while ($this->validateCurrentDate() === false);
1178     }
1179
1180     /**
1181      * Format the date period as ISO 8601.
1182      *
1183      * @return string
1184      */
1185     public function toIso8601String()
1186     {
1187         $parts = array();
1188
1189         if ($this->recurrences !== null) {
1190             $parts[] = 'R'.$this->recurrences;
1191         }
1192
1193         $parts[] = $this->startDate->toIso8601String();
1194
1195         $parts[] = $this->dateInterval->spec();
1196
1197         if ($this->endDate !== null) {
1198             $parts[] = $this->endDate->toIso8601String();
1199         }
1200
1201         return implode('/', $parts);
1202     }
1203
1204     /**
1205      * Convert the date period into a string.
1206      *
1207      * @return string
1208      */
1209     public function toString()
1210     {
1211         $translator = Carbon::getTranslator();
1212
1213         $parts = array();
1214
1215         $format = !$this->startDate->isStartOfDay() || $this->endDate && !$this->endDate->isStartOfDay()
1216             ? 'Y-m-d H:i:s'
1217             : 'Y-m-d';
1218
1219         if ($this->recurrences !== null) {
1220             $parts[] = $translator->transChoice('period_recurrences', $this->recurrences, array(':count' => $this->recurrences));
1221         }
1222
1223         $parts[] = $translator->trans('period_interval', array(':interval' => $this->dateInterval->forHumans()));
1224
1225         $parts[] = $translator->trans('period_start_date', array(':date' => $this->startDate->format($format)));
1226
1227         if ($this->endDate !== null) {
1228             $parts[] = $translator->trans('period_end_date', array(':date' => $this->endDate->format($format)));
1229         }
1230
1231         $result = implode(' ', $parts);
1232
1233         return mb_strtoupper(mb_substr($result, 0, 1)).mb_substr($result, 1);
1234     }
1235
1236     /**
1237      * Format the date period as ISO 8601.
1238      *
1239      * @return string
1240      */
1241     public function spec()
1242     {
1243         return $this->toIso8601String();
1244     }
1245
1246     /**
1247      * Convert the date period into an array without changing current iteration state.
1248      *
1249      * @return array
1250      */
1251     public function toArray()
1252     {
1253         $state = array(
1254             $this->key,
1255             $this->current ? $this->current->copy() : null,
1256             $this->validationResult,
1257         );
1258
1259         $result = iterator_to_array($this);
1260
1261         list(
1262             $this->key,
1263             $this->current,
1264             $this->validationResult
1265         ) = $state;
1266
1267         return $result;
1268     }
1269
1270     /**
1271      * Count dates in the date period.
1272      *
1273      * @return int
1274      */
1275     public function count()
1276     {
1277         return count($this->toArray());
1278     }
1279
1280     /**
1281      * Return the first date in the date period.
1282      *
1283      * @return Carbon|null
1284      */
1285     public function first()
1286     {
1287         if ($array = $this->toArray()) {
1288             return $array[0];
1289         }
1290     }
1291
1292     /**
1293      * Return the last date in the date period.
1294      *
1295      * @return Carbon|null
1296      */
1297     public function last()
1298     {
1299         if ($array = $this->toArray()) {
1300             return $array[count($array) - 1];
1301         }
1302     }
1303
1304     /**
1305      * Call given macro.
1306      *
1307      * @param string $name
1308      * @param array  $parameters
1309      *
1310      * @return mixed
1311      */
1312     protected function callMacro($name, $parameters)
1313     {
1314         $macro = static::$macros[$name];
1315
1316         $reflection = new ReflectionFunction($macro);
1317
1318         $reflectionParameters = $reflection->getParameters();
1319
1320         $expectedCount = count($reflectionParameters);
1321         $actualCount = count($parameters);
1322
1323         if ($expectedCount > $actualCount && $reflectionParameters[$expectedCount - 1]->name === 'self') {
1324             for ($i = $actualCount; $i < $expectedCount - 1; $i++) {
1325                 $parameters[] = $reflectionParameters[$i]->getDefaultValue();
1326             }
1327
1328             $parameters[] = $this;
1329         }
1330
1331         if ($macro instanceof Closure && method_exists($macro, 'bindTo')) {
1332             $macro = $macro->bindTo($this, get_class($this));
1333         }
1334
1335         return call_user_func_array($macro, $parameters);
1336     }
1337
1338     /**
1339      * Convert the date period into a string.
1340      *
1341      * @return string
1342      */
1343     public function __toString()
1344     {
1345         return $this->toString();
1346     }
1347
1348     /**
1349      * Add aliases for setters.
1350      *
1351      * CarbonPeriod::days(3)->hours(5)->invert()
1352      *     ->sinceNow()->until('2010-01-10')
1353      *     ->filter(...)
1354      *     ->count()
1355      *
1356      * Note: We use magic method to let static and instance aliases with the same names.
1357      *
1358      * @param string $method
1359      * @param array  $parameters
1360      *
1361      * @return mixed
1362      */
1363     public function __call($method, $parameters)
1364     {
1365         if (static::hasMacro($method)) {
1366             return $this->callMacro($method, $parameters);
1367         }
1368
1369         $first = count($parameters) >= 1 ? $parameters[0] : null;
1370         $second = count($parameters) >= 2 ? $parameters[1] : null;
1371
1372         switch ($method) {
1373             case 'start':
1374             case 'since':
1375                 return $this->setStartDate($first, $second);
1376
1377             case 'sinceNow':
1378                 return $this->setStartDate(new Carbon, $first);
1379
1380             case 'end':
1381             case 'until':
1382                 return $this->setEndDate($first, $second);
1383
1384             case 'untilNow':
1385                 return $this->setEndDate(new Carbon, $first);
1386
1387             case 'dates':
1388             case 'between':
1389                 return $this->setDates($first, $second);
1390
1391             case 'recurrences':
1392             case 'times':
1393                 return $this->setRecurrences($first);
1394
1395             case 'options':
1396                 return $this->setOptions($first);
1397
1398             case 'toggle':
1399                 return $this->toggleOptions($first, $second);
1400
1401             case 'filter':
1402             case 'push':
1403                 return $this->addFilter($first, $second);
1404
1405             case 'prepend':
1406                 return $this->prependFilter($first, $second);
1407
1408             case 'filters':
1409                 return $this->setFilters($first ?: array());
1410
1411             case 'interval':
1412             case 'each':
1413             case 'every':
1414             case 'step':
1415             case 'stepBy':
1416                 return $this->setDateInterval($first);
1417
1418             case 'invert':
1419                 return $this->invertDateInterval();
1420
1421             case 'years':
1422             case 'year':
1423             case 'months':
1424             case 'month':
1425             case 'weeks':
1426             case 'week':
1427             case 'days':
1428             case 'dayz':
1429             case 'day':
1430             case 'hours':
1431             case 'hour':
1432             case 'minutes':
1433             case 'minute':
1434             case 'seconds':
1435             case 'second':
1436                 return $this->setDateInterval(call_user_func(
1437                     // Override default P1D when instantiating via fluent setters.
1438                     array($this->isDefaultInterval ? new CarbonInterval('PT0S') : $this->dateInterval, $method),
1439                     count($parameters) === 0 ? 1 : $first
1440                 ));
1441         }
1442
1443         throw new BadMethodCallException("Method $method does not exist.");
1444     }
1445 }