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