jdmonthname()

PHP-Funktion: cal_jdmonthname()

Die PHP-Funktion cal_jdmonthname() gibt den Monatsnamen für eine bestimmte Julianische Tageszahl im gewünschten Kalendersystem zurück. Diese Seite erklärt, was eine Julianische Tageszahl ist, die Syntax der Funktion und ihre Moduskonstanten, ausführbare Beispiele, den Rückgabewert sowie häufige Fallstricke.

Hinweis: Die URL dieses Kapitels trägt historisch den Namen jdmonthname, die moderne PHP-Funktion lautet jedoch cal_jdmonthname(). Der alte Alias jdmonthname() gehörte zur jd-Familie, die PHP in PHP 8.0 entfernt hat — verwenden Sie stattdessen cal_jdmonthname().

Syntax

cal_jdmonthname(int $julian_day, int $mode): string

• $julian_day — eine Julianische Tageszahl (ein Integer), typischerweise erzeugt durch cal_to_jd() aus einem normalen Datum.
• $mode — aus welchem Kalender der Monatsname gelesen werden soll. Die zulässigen Werte sind:

Die Funktion gibt den Monatsnamen als string zurück. Sie setzt die calendar-Erweiterung voraus, die in Ihrem PHP-Build aktiviert sein muss.

Was ist eine Julianische Tageszahl?

Bevor wir uns mit der Funktionsweise von cal_jdmonthname() befassen, ist es wichtig zu verstehen, was eine Julianische Tageszahl ist. Eine Julianische Tageszahl ist eine fortlaufende Zählung von Tagen, die am Mittag des 1. Januar 4713 v. Chr. begann. Sie wurde 1583 von Joseph Scaliger eingeführt, um astronomische Berechnungen und Datumsvergleiche zu erleichtern.

Was macht die Funktion cal_jdmonthname?

Die Funktion cal_jdmonthname() nimmt zwei Parameter entgegen: die Julianische Tageszahl und eine Moduskonstante (einen der CAL_MONTH_*-Werte aus der obigen Tabelle), die den Kalender sowie die Wahl zwischen langem und kurzem Namen festlegt. Die Funktion gibt den entsprechenden Monatsnamen als string zurück.

Ein häufiger Verwirrungspunkt: Der erste Schritt (cal_to_jd()) verwendet Kalenderkonstanten wie CAL_GREGORIAN, aber der an cal_jdmonthname() übergebene Modus muss eine CAL_MONTH_*-Konstante sein. Diese sind nicht austauschbar.

Hier ein Beispiel:

Beispiel der Funktion cal_jdmonthname() in PHP

<?php
// Convert today's date to a Julian day count.
$jd = cal_to_jd(CAL_GREGORIAN, (int) date("m"), (int) date("d"), (int) date("Y"));

// Read the long Gregorian month name back from that Julian day.
echo "Today is " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG) . ".";
?>

In einem Monat wie März gibt dies aus: Today is March.

Wie verwendet man die Funktion cal_jdmonthname?

Um die Funktion cal_jdmonthname() in Ihrem PHP-Code zu verwenden, gehen Sie folgendermaßen vor:

1. Ermitteln Sie die Julianische Tageszahl für das gewünschte Datum. Mit der Funktion cal_to_jd() können Sie ein gregorianisches Datum in eine Julianische Tageszahl umrechnen.
2. Rufen Sie die Funktion cal_jdmonthname() auf und übergeben Sie die Julianische Tageszahl sowie eine Moduskonstante (z. B. CAL_MONTH_GREGORIAN_LONG oder CAL_MONTH_JULIAN_LONG).
3. Verwenden Sie den zurückgegebenen Wert nach Bedarf in Ihrem Code.

Hinweis: Die älteren jd-Erweiterungsfunktionen wurden in PHP 8.0 entfernt. Verwenden Sie für Kalenderoperationen in modernem PHP stets die cal_*-Funktionen.

Beispiel

So lassen sich sowohl der vollständige als auch der abgekürzte Monatsname für dasselbe Datum abrufen, indem lediglich die Moduskonstante geändert wird:

Verwendung der Funktion cal_jdmonthname() in PHP

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 1, 2023);   // March 1, 2023

echo "Long:  " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG)  . "\n"; // Long:  March
echo "Short: " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_SHORT) . "\n"; // Short: Mar
?>

Da sich nur der Modus ändert, ist dies der sauberste Weg, zwischen vollständigen Namen (March) und Abkürzungen (Mar) oder zwischen verschiedenen Kalendersystemen zu wechseln, ohne das Datum neu berechnen zu müssen.

Hinweis zum Julianischen Kalender: Das Übergeben eines CAL_MONTH_JULIAN_*-Modus liest dieselbe Julianische Tageszahl über den älteren Julianischen Kalender. Da der Julianische Kalender derzeit etwa 13 Tage hinter dem Gregorianischen liegt, kann ein Datum nahe dem Monatsanfang oder -ende in einem anderen Monatsnamen enden als beim gregorianischen Lesen.

Vorteile der Funktion cal_jdmonthname

Die Verwendung der Funktion cal_jdmonthname() erleichtert die Arbeit mit Julianischen Tageszahlen in PHP erheblich. Hier einige Vorteile:

1. Zeitersparnis: Anstatt den Monatsnamen für eine gegebene Julianische Tageszahl manuell zu berechnen, rufen Sie einfach die Funktion cal_jdmonthname() auf.
2. Konsistenz: Die Funktion stellt sicher, dass Sie jedes Mal den richtigen Monatsnamen erhalten, was das Fehlerrisiko in Ihrem Code verringert.
3. Flexibilität: Die Funktion erlaubt die Angabe des Kalendersystems und gibt Ihnen damit mehr Kontrolle darüber, wie Ihr Code Informationen über verschiedene historische oder regionale Kalender hinweg darstellt.

Fallstricke

• Verwenden Sie eine CAL_MONTH_*-Moduskonstante, keine CAL_*-Kalenderkonstante. Das Übergeben von CAL_GREGORIAN (Wert 0) entspricht zufällig CAL_MONTH_GREGORIAN_LONG, aber CAL_JULIAN liefert keine Julianischen Monatsnamen — verwenden Sie stattdessen CAL_MONTH_JULIAN_LONG.
• Die calendar-Erweiterung muss aktiviert sein. In vielen Standard-Builds ist sie es nicht. Wenn Sie Call to undefined function cal_jdmonthname() erhalten, aktivieren Sie ext-calendar in Ihrer PHP-Konfiguration.
• Die alten jd*-Aliasse sind entfernt. jdmonthname() und verwandte Funktionen wurden in PHP 8.0 entfernt; verwenden Sie in modernem Code stets die cal_*-Funktionen.

Verwandte Funktionen

• cal_to_jd() — konvertiert ein Kalenderdatum in eine Julianische Tageszahl (die Eingabe für diese Funktion).
• cal_from_jd() — konvertiert eine Julianische Tageszahl zurück in Datumsteile, einschließlich Monatsnummer und Monatsname.
• cal_days_in_month() — Anzahl der Tage in einem bestimmten Monat.
• cal_info() — Monats- und Tagnamen für einen ganzen Kalender auf einmal.

Fazit

Die Funktion cal_jdmonthname() ist ein praktisches Werkzeug für PHP-Entwickler, die mit Julianischen Tageszahlen arbeiten: Sie wandelt eine rohe Tageszahl in einen lesbaren Monatsnamen im Kalendersystem Ihrer Wahl um. Kombinieren Sie sie mit cal_to_jd() für die Datumskonvertierung, denken Sie daran, eine CAL_MONTH_*-Moduskonstante zu übergeben, und stellen Sie sicher, dass die calendar-Erweiterung aktiviert ist.

Practice