1<?php 2 3/** 4 * webtrees: online genealogy 5 * Copyright (C) 2021 webtrees development team 6 * This program is free software: you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation, either version 3 of the License, or 9 * (at your option) any later version. 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * You should have received a copy of the GNU General Public License 15 * along with this program. If not, see <https://www.gnu.org/licenses/>. 16 */ 17 18declare(strict_types=1); 19 20namespace Fisharebest\Webtrees; 21 22use DomainException; 23use Fisharebest\ExtCalendar\GregorianCalendar; 24use Fisharebest\Webtrees\Date\AbstractCalendarDate; 25use Fisharebest\Webtrees\Date\FrenchDate; 26use Fisharebest\Webtrees\Date\GregorianDate; 27use Fisharebest\Webtrees\Date\HijriDate; 28use Fisharebest\Webtrees\Date\JalaliDate; 29use Fisharebest\Webtrees\Date\JewishDate; 30use Fisharebest\Webtrees\Date\JulianDate; 31use Fisharebest\Webtrees\Date\RomanDate; 32 33/** 34 * A representation of GEDCOM dates and date ranges. 35 * 36 * Since different calendars start their days at different times, (civil 37 * midnight, solar midnight, sunset, sunrise, etc.), we convert on the basis of 38 * midday. 39 * 40 * We assume that years start on the first day of the first month. Where 41 * this is not the case (e.g. England prior to 1752), we need to use modified 42 * years or the OS/NS notation "4 FEB 1750/51". 43 */ 44class Date 45{ 46 // Optional qualifier, such as BEF, FROM, ABT 47 public string $qual1 = ''; 48 49 // The first (or only) date 50 private AbstractCalendarDate $date1; 51 52 // Optional qualifier, such as TO, AND 53 public string $qual2 = ''; 54 55 // Optional second date 56 private ?AbstractCalendarDate $date2 = null; 57 58 // Optional text, as included with an INTerpreted date 59 private string $text = ''; 60 61 /** 62 * Create a date, from GEDCOM data. 63 * 64 * @param string $date A date in GEDCOM format 65 */ 66 public function __construct(string $date) 67 { 68 // Extract any explanatory text 69 if (preg_match('/^(.*) ?[(](.*)[)]/', $date, $match)) { 70 $date = $match[1]; 71 $this->text = $match[2]; 72 } 73 if (preg_match('/^(FROM|BET) (.+) (AND|TO) (.+)/', $date, $match)) { 74 $this->qual1 = $match[1]; 75 $this->date1 = $this->parseDate($match[2]); 76 $this->qual2 = $match[3]; 77 $this->date2 = $this->parseDate($match[4]); 78 } elseif (preg_match('/^(TO|FROM|BEF|AFT|CAL|EST|INT|ABT) (.+)/', $date, $match)) { 79 $this->qual1 = $match[1]; 80 $this->date1 = $this->parseDate($match[2]); 81 } else { 82 $this->date1 = $this->parseDate($date); 83 } 84 } 85 86 /** 87 * When we copy a date object, we need to create copies of 88 * its child objects. 89 */ 90 public function __clone() 91 { 92 $this->date1 = clone $this->date1; 93 if ($this->date2 !== null) { 94 $this->date2 = clone $this->date2; 95 } 96 } 97 98 /** 99 * Convert a calendar date, such as "12 JUN 1943" into calendar date object. 100 * A GEDCOM date range may have two calendar dates. 101 * 102 * @param string $date 103 * 104 * @return AbstractCalendarDate 105 * @throws DomainException 106 */ 107 private function parseDate(string $date): AbstractCalendarDate 108 { 109 // Valid calendar escape specified? - use it 110 if (preg_match('/^(@#D(?:GREGORIAN|JULIAN|HEBREW|HIJRI|JALALI|FRENCH R|ROMAN)+@) ?(.*)/', $date, $match)) { 111 $cal = $match[1]; 112 $date = $match[2]; 113 } else { 114 $cal = ''; 115 } 116 // A date with a month: DM, M, MY or DMY 117 if (preg_match('/^(\d?\d?) ?(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|TSH|CSH|KSL|TVT|SHV|ADR|ADS|NSN|IYR|SVN|TMZ|AAV|ELL|VEND|BRUM|FRIM|NIVO|PLUV|VENT|GERM|FLOR|PRAI|MESS|THER|FRUC|COMP|MUHAR|SAFAR|RABI[AT]|JUMA[AT]|RAJAB|SHAAB|RAMAD|SHAWW|DHUAQ|DHUAH|FARVA|ORDIB|KHORD|TIR|MORDA|SHAHR|MEHR|ABAN|AZAR|DEY|BAHMA|ESFAN) ?((?:\d{1,4}(?: B\.C\.)?|\d\d\d\d\/\d\d)?)$/', $date, $match)) { 118 $d = $match[1]; 119 $m = $match[2]; 120 $y = $match[3]; 121 } elseif (preg_match('/^(\d{1,4}(?: B\.C\.)?|\d\d\d\d\/\d\d)$/', $date, $match)) { 122 // A date with just a year 123 $d = ''; 124 $m = ''; 125 $y = $match[1]; 126 } else { 127 // An invalid date - do the best we can. 128 $d = ''; 129 $m = ''; 130 $y = ''; 131 // Look for a 3/4 digit year anywhere in the date 132 if (preg_match('/\b(\d{3,4})\b/', $date, $match)) { 133 $y = $match[1]; 134 } 135 // Look for a month anywhere in the date 136 if (preg_match('/(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC|TSH|CSH|KSL|TVT|SHV|ADR|ADS|NSN|IYR|SVN|TMZ|AAV|ELL|VEND|BRUM|FRIM|NIVO|PLUV|VENT|GERM|FLOR|PRAI|MESS|THER|FRUC|COMP|MUHAR|SAFAR|RABI[AT]|JUMA[AT]|RAJAB|SHAAB|RAMAD|SHAWW|DHUAQ|DHUAH|FARVA|ORDIB|KHORD|TIR|MORDA|SHAHR|MEHR|ABAN|AZAR|DEY|BAHMA|ESFAN)/', $date, $match)) { 137 $m = $match[1]; 138 // Look for a day number anywhere in the date 139 if (preg_match('/\b(\d\d?)\b/', $date, $match)) { 140 $d = $match[1]; 141 } 142 } 143 } 144 145 // Unambiguous dates - override calendar escape 146 if (preg_match('/^(TSH|CSH|KSL|TVT|SHV|ADR|ADS|NSN|IYR|SVN|TMZ|AAV|ELL)$/', $m)) { 147 $cal = JewishDate::ESCAPE; 148 } elseif (preg_match('/^(VEND|BRUM|FRIM|NIVO|PLUV|VENT|GERM|FLOR|PRAI|MESS|THER|FRUC|COMP)$/', $m)) { 149 $cal = FrenchDate::ESCAPE; 150 } elseif (preg_match('/^(MUHAR|SAFAR|RABI[AT]|JUMA[AT]|RAJAB|SHAAB|RAMAD|SHAWW|DHUAQ|DHUAH)$/', $m)) { 151 $cal = HijriDate::ESCAPE; // This is a WT extension 152 } elseif (preg_match('/^(FARVA|ORDIB|KHORD|TIR|MORDA|SHAHR|MEHR|ABAN|AZAR|DEY|BAHMA|ESFAN)$/', $m)) { 153 $cal = JalaliDate::ESCAPE; // This is a WT extension 154 } elseif (preg_match('/^\d{1,4}( B\.C\.)|\d\d\d\d\/\d\d$/', $y)) { 155 $cal = JulianDate::ESCAPE; 156 } 157 158 // Ambiguous dates - don't override calendar escape 159 if ($cal === '') { 160 if (preg_match('/^(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC)$/', $m)) { 161 $cal = GregorianDate::ESCAPE; 162 } elseif (preg_match('/^[345]\d\d\d$/', $y)) { 163 // Year 3000-5999 164 $cal = JewishDate::ESCAPE; 165 } else { 166 $cal = GregorianDate::ESCAPE; 167 } 168 } 169 // Now construct an object of the correct type 170 switch ($cal) { 171 case GregorianDate::ESCAPE: 172 return new GregorianDate([ 173 $y, 174 $m, 175 $d, 176 ]); 177 case JulianDate::ESCAPE: 178 return new JulianDate([ 179 $y, 180 $m, 181 $d, 182 ]); 183 case JewishDate::ESCAPE: 184 return new JewishDate([ 185 $y, 186 $m, 187 $d, 188 ]); 189 case HijriDate::ESCAPE: 190 return new HijriDate([ 191 $y, 192 $m, 193 $d, 194 ]); 195 case FrenchDate::ESCAPE: 196 return new FrenchDate([ 197 $y, 198 $m, 199 $d, 200 ]); 201 case JalaliDate::ESCAPE: 202 return new JalaliDate([ 203 $y, 204 $m, 205 $d, 206 ]); 207 case RomanDate::ESCAPE: 208 return new RomanDate([ 209 $y, 210 $m, 211 $d, 212 ]); 213 default: 214 throw new DomainException('Invalid calendar'); 215 } 216 } 217 218 /** 219 * A list of supported calendars and their names. 220 * 221 * @return array<string> 222 */ 223 public static function calendarNames(): array 224 { 225 return [ 226 /* I18N: The gregorian calendar */ 227 'gregorian' => I18N::translate('Gregorian'), 228 /* I18N: The julian calendar */ 229 'julian' => I18N::translate('Julian'), 230 /* I18N: The French calendar */ 231 'french' => I18N::translate('French'), 232 /* I18N: The Hebrew/Jewish calendar */ 233 'jewish' => I18N::translate('Jewish'), 234 /* I18N: The Arabic/Hijri calendar */ 235 'hijri' => I18N::translate('Hijri'), 236 /* I18N: The Persian/Jalali calendar */ 237 'jalali' => I18N::translate('Jalali'), 238 ]; 239 } 240 241 /** 242 * Convert a date to the preferred format and calendar(s) display. 243 * 244 * @param Tree|null $tree Wrap the date in a link to the calendar page for the tree 245 * @param string|null $date_format Override the default date format 246 * @param bool $convert_calendars Convert the date into other calendars (requires a tree) 247 * 248 * @return string 249 */ 250 public function display(Tree $tree = null, string $date_format = null, bool $convert_calendars = false): string 251 { 252 if ($tree instanceof Tree) { 253 $CALENDAR_FORMAT = $tree->getPreference('CALENDAR_FORMAT'); 254 } else { 255 $CALENDAR_FORMAT = 'none'; 256 } 257 258 $date_format = $date_format ?? I18N::dateFormat(); 259 260 if ($convert_calendars) { 261 $calendar_format = explode('_and_', $CALENDAR_FORMAT); 262 } else { 263 $calendar_format = []; 264 } 265 266 // Two dates with text before, between and after 267 $q1 = $this->qual1; 268 $d1 = $this->date1->format($date_format, $this->qual1); 269 $q2 = $this->qual2; 270 if ($this->date2 === null) { 271 $d2 = ''; 272 } else { 273 $d2 = $this->date2->format($date_format, $this->qual2); 274 } 275 // Con vert to other calendars, if requested 276 $conv1 = ''; 277 $conv2 = ''; 278 foreach ($calendar_format as $cal_fmt) { 279 if ($cal_fmt !== 'none') { 280 $d1conv = $this->date1->convertToCalendar($cal_fmt); 281 if ($d1conv->inValidRange()) { 282 $d1tmp = $d1conv->format($date_format, $this->qual1); 283 } else { 284 $d1tmp = ''; 285 } 286 if ($this->date2 === null) { 287 $d2conv = null; 288 $d2tmp = ''; 289 } else { 290 $d2conv = $this->date2->convertToCalendar($cal_fmt); 291 if ($d2conv->inValidRange()) { 292 $d2tmp = $d2conv->format($date_format, $this->qual2); 293 } else { 294 $d2tmp = ''; 295 } 296 } 297 // If the date is different from the unconverted date, add it to the date string. 298 if ($d1 != $d1tmp && $d1tmp !== '') { 299 if ($tree instanceof Tree) { 300 if ($CALENDAR_FORMAT !== 'none') { 301 $conv1 .= ' <span dir="' . I18N::direction() . '">(<a href="' . e($d1conv->calendarUrl($date_format, $tree)) . '" rel="nofollow">' . $d1tmp . '</a>)</span>'; 302 } else { 303 $conv1 .= ' <span dir="' . I18N::direction() . '"><br><a href="' . e($d1conv->calendarUrl($date_format, $tree)) . '" rel="nofollow">' . $d1tmp . '</a></span>'; 304 } 305 } else { 306 $conv1 .= ' <span dir="' . I18N::direction() . '">(' . $d1tmp . ')</span>'; 307 } 308 } 309 if ($this->date2 !== null && $d2 != $d2tmp && $d1tmp != '') { 310 if ($tree instanceof Tree) { 311 $conv2 .= ' <span dir="' . I18N::direction() . '">(<a href="' . e($d2conv->calendarUrl($date_format, $tree)) . '" rel="nofollow">' . $d2tmp . '</a>)</span>'; 312 } else { 313 $conv2 .= ' <span dir="' . I18N::direction() . '">(' . $d2tmp . ')</span>'; 314 } 315 } 316 } 317 } 318 319 // Add URLs, if requested 320 if ($tree instanceof Tree) { 321 $d1 = '<a href="' . e($this->date1->calendarUrl($date_format, $tree)) . '" rel="nofollow">' . $d1 . '</a>'; 322 if ($this->date2 instanceof AbstractCalendarDate) { 323 $d2 = '<a href="' . e($this->date2->calendarUrl($date_format, $tree)) . '" rel="nofollow">' . $d2 . '</a>'; 324 } 325 } 326 327 // Localise the date 328 switch ($q1 . $q2) { 329 case '': 330 $tmp = $d1 . $conv1; 331 break; 332 case 'ABT': 333 /* I18N: Gedcom ABT dates */ 334 $tmp = I18N::translate('about %s', $d1 . $conv1); 335 break; 336 case 'CAL': 337 /* I18N: Gedcom CAL dates */ 338 $tmp = I18N::translate('calculated %s', $d1 . $conv1); 339 break; 340 case 'EST': 341 /* I18N: Gedcom EST dates */ 342 $tmp = I18N::translate('estimated %s', $d1 . $conv1); 343 break; 344 case 'INT': 345 /* I18N: Gedcom INT dates */ 346 $tmp = I18N::translate('interpreted %s (%s)', $d1 . $conv1, e($this->text)); 347 break; 348 case 'BEF': 349 /* I18N: Gedcom BEF dates */ 350 $tmp = I18N::translate('before %s', $d1 . $conv1); 351 break; 352 case 'AFT': 353 /* I18N: Gedcom AFT dates */ 354 $tmp = I18N::translate('after %s', $d1 . $conv1); 355 break; 356 case 'FROM': 357 /* I18N: Gedcom FROM dates */ 358 $tmp = I18N::translate('from %s', $d1 . $conv1); 359 break; 360 case 'TO': 361 /* I18N: Gedcom TO dates */ 362 $tmp = I18N::translate('to %s', $d1 . $conv1); 363 break; 364 case 'BETAND': 365 /* I18N: Gedcom BET-AND dates */ 366 $tmp = I18N::translate('between %s and %s', $d1 . $conv1, $d2 . $conv2); 367 break; 368 case 'FROMTO': 369 /* I18N: Gedcom FROM-TO dates */ 370 $tmp = I18N::translate('from %s to %s', $d1 . $conv1, $d2 . $conv2); 371 break; 372 default: 373 $tmp = I18N::translate('Invalid date'); 374 break; 375 } 376 377 if (strip_tags($tmp) === '') { 378 return ''; 379 } 380 381 return '<span class="date">' . $tmp . '</span>'; 382 } 383 384 /** 385 * Get the earliest calendar date from this GEDCOM date. 386 * 387 * In the date “FROM 1900 TO 1910”, this would be 1900. 388 * 389 * @return AbstractCalendarDate 390 */ 391 public function minimumDate(): AbstractCalendarDate 392 { 393 return $this->date1; 394 } 395 396 /** 397 * Get the latest calendar date from this GEDCOM date. 398 * 399 * In the date “FROM 1900 TO 1910”, this would be 1910. 400 * 401 * @return AbstractCalendarDate 402 */ 403 public function maximumDate(): AbstractCalendarDate 404 { 405 return $this->date2 ?? $this->date1; 406 } 407 408 /** 409 * Get the earliest Julian day number from this GEDCOM date. 410 * 411 * @return int 412 */ 413 public function minimumJulianDay(): int 414 { 415 return $this->minimumDate()->minimumJulianDay(); 416 } 417 418 /** 419 * Get the latest Julian day number from this GEDCOM date. 420 * 421 * @return int 422 */ 423 public function maximumJulianDay(): int 424 { 425 return $this->maximumDate()->maximumJulianDay(); 426 } 427 428 /** 429 * Get the middle Julian day number from the GEDCOM date. 430 * 431 * For a month-only date, this would be somewhere around the 16th day. 432 * For a year-only date, this would be somewhere around 1st July. 433 * 434 * @return int 435 */ 436 public function julianDay(): int 437 { 438 return intdiv($this->minimumJulianDay() + $this->maximumJulianDay(), 2); 439 } 440 441 /** 442 * Offset this date by N years, and round to the whole year. 443 * 444 * This is typically used to create an estimated death date, 445 * which is before a certain number of years after the birth date. 446 * 447 * @param int $years a number of years, positive or negative 448 * @param string $qualifier typically “BEF” or “AFT” 449 * 450 * @return Date 451 */ 452 public function addYears(int $years, string $qualifier = ''): Date 453 { 454 $tmp = clone $this; 455 $tmp->date1->year += $years; 456 $tmp->date1->month = 0; 457 $tmp->date1->day = 0; 458 $tmp->date1->setJdFromYmd(); 459 $tmp->qual1 = $qualifier; 460 $tmp->qual2 = ''; 461 $tmp->date2 = null; 462 463 return $tmp; 464 } 465 466 /** 467 * Compare two dates, so they can be sorted. 468 * 469 * return -1 if $a<$b 470 * return +1 if $b>$a 471 * return 0 if dates same/overlap 472 * BEF/AFT sort as the day before/after 473 * 474 * @param Date $a 475 * @param Date $b 476 * 477 * @return int 478 */ 479 public static function compare(Date $a, Date $b): int 480 { 481 // Get min/max JD for each date. 482 switch ($a->qual1) { 483 case 'BEF': 484 $amin = $a->minimumJulianDay() - 1; 485 $amax = $amin; 486 break; 487 case 'AFT': 488 $amax = $a->maximumJulianDay() + 1; 489 $amin = $amax; 490 break; 491 default: 492 $amin = $a->minimumJulianDay(); 493 $amax = $a->maximumJulianDay(); 494 break; 495 } 496 switch ($b->qual1) { 497 case 'BEF': 498 $bmin = $b->minimumJulianDay() - 1; 499 $bmax = $bmin; 500 break; 501 case 'AFT': 502 $bmax = $b->maximumJulianDay() + 1; 503 $bmin = $bmax; 504 break; 505 default: 506 $bmin = $b->minimumJulianDay(); 507 $bmax = $b->maximumJulianDay(); 508 break; 509 } 510 if ($amax < $bmin) { 511 return -1; 512 } 513 514 if ($amin > $bmax && $bmax > 0) { 515 return 1; 516 } 517 518 if ($amin < $bmin && $amax <= $bmax) { 519 return -1; 520 } 521 522 if ($amin > $bmin && $amax >= $bmax && $bmax > 0) { 523 return 1; 524 } 525 526 return 0; 527 } 528 529 /** 530 * Check whether a gedcom date contains usable calendar date(s). 531 * 532 * An incomplete date such as "12 AUG" would be invalid, as 533 * we cannot sort it. 534 * 535 * @return bool 536 */ 537 public function isOK(): bool 538 { 539 return $this->minimumJulianDay() && $this->maximumJulianDay(); 540 } 541 542 /** 543 * Calculate the gregorian year for a date. This should NOT be used internally 544 * within WT - we should keep the code "calendar neutral" to allow support for 545 * jewish/arabic users. This is only for interfacing with external entities, 546 * such as the ancestry.com search interface or the dated fact icons. 547 * 548 * @return int 549 */ 550 public function gregorianYear(): int 551 { 552 if ($this->isOK()) { 553 $gregorian_calendar = new GregorianCalendar(); 554 [$year] = $gregorian_calendar->jdToYmd($this->julianDay()); 555 556 return $year; 557 } 558 559 return 0; 560 } 561} 562