• Szerző: Rékási József
• Copyright © Rékási József, 2022
• Licenc: CC Attribution-Share Alike 4.0 International
• Web: https://szit.hu

Laravel 11 -es verzió óta composer telepítés nélkül támogatott a Carbon osztály. Ezt az osztályt kifejezetetten a dátumok kezelésére készítették. A használathoz importálni kell.

use Carbon\Carbon

Aktuális idő lekérdezése, valamint adhatunk át a now() függvénynek paramétert is amelyben megadhatjuk a lekérdezni kívánt időzónát. A Carbon alapértelmezetten az UTC időt használja.

$actualTime = Carbon::now();
$actualTimeZone = Carbon::now()->timezoneName;
$actualTimeBudapest = Carbon::now( "Europe/Budapest" );

Lekérdezhetünk közvetlenül napokat is. Ebben az esetben az idő mindig 00:00:00 lesz.

$yesterday = Carbon::yesterday();
$today = Carbon::today();
$tomorrow = Carbon::tomorrow();
$dayOfWeek01 = new Carbon( "last wednesday" );
$dayOfWeek02 = new Carbon( "next thursday" ); 
$dayOfWeek03 = new Carbon( "this friday" ); 

Az aktuális Carbon objektum tárolja a lekérdezett időt, ezekhez tudunk hozzáadni időintervallumokat is.

$time01 = Carbon::now()->addSeconds( 10 );
$time02 = Carbon::now()->addMinutes( 5 );
$time03 = Carbon::today()->addHours( 2 );
$time04 = Carbon::tomorrow()->addDays( 3 );
$time05 = Carbon::yesterDay()->addYears( 2 );

// év, hónap, nap, óra, perc, másodperc
$date01 = Carbon::createFromDate( 2024, 1, 1, 0, 0, 0 ); //2024-01-01 00:00:00
$date02 = Carbon::createMidnightDate( 2024, 1, 1 );      //Megegyezik az előzővel
 
//óra, perc, másodperc, időzóna
$time01 = Carbon::createFromTime( 20, 15, 30, "Europe/Budapest" )

Ha bármelyik paramétert null értékre állítjuk akkor alapértelmezetten a helyi aktuális érték kerül behelyettesítésre. A Carbon osztály alapértelmezetten kezeli a szökőéveket, illetve a téli nyári időszámítás átállásakor keletkezett időkieséseket is. Ha a megadott dátum nem felel meg valamelyik feltételnek akkor InvalidDateException -t dob. Használjuk a createSafe() metódust.

$date = Carbon::createSafe( $year, $month, $day );

Megadhatunk konkrét feltételeket is.

$saturday = new Carbon( "first saturday of 2024" );
$sunday = new Carbon( "first sunday of 2024" );
$monday = new Carbon( "first monday of 2024" );

Ezeket le is tudjuk kérdezni.

$weekend01 = $saturday->isWeekend();     // true
$weekend02 = $sunday->isWeekend();       // true
$weekend03 = $monday->isWeekend();       // false

Az első lehetőség a createFromFormat() metódus.

$date = Carbon::createFromFormat( "Y-m-d H", "2025-01-01 15" )->toDateTimeString();    //2025-01-01 15:00:00

A másik lehetőség a parse() metódus használata.

$dateString = "2025-01-01";
$carbonDate = Carbon::parse( $dateString );

A Carbon több féle dátum típust tud kezelni. Néhány példa:

$dateString01 = "January 26, 2024";
$dateString02 = "01/01/2024";
$dateTimeString = "2024-01-01 11:00:00";
$timeString = "11:00";
$dateString03 = new Carbon( "first day of January 2024" );

Képes lefordítani nyelvek között a dátumokat. Ezt két féle képpen adhatjuk meg.

$translate01 = Carbon::translateTimeString( "January 26, 2024", "en", "hu" );
$translate02 = Carbon::now()->locale( "en" )->translateTimeString( "January 26, 2024",  "hu" );

A getterek a PHP __get() metódusán keresztül valósulnak meg, ez lehetővé teszi, hogy a dátum értékeket tulajdonságként érjük el és ne metódushíváson keresztül. Hozzunk létre egy teszt dátumot:

$testDate = Carbon::parse( "2024-01-01 11:15:00");

Getterek használatánál a dátum értékeket integer típusban kapjuk vissza.

$year = $testDate->year;     //int(2024)
$month = $testDate->month;   //int(1)
$day = $testDate->day;       //int(1)
$hour = $testDate->hour;     //int(11)
$minute = $testDate->minute; //int(15)
$second = $testDate->second; //int(0)

A napokat számozva kapjuk meg, Hétfő = 1, Vasárnap = 7. Lekérdezhetjük szöveges formátumban is, illetve lehetőség van nyelvi fordításra. Ugyanez igaz a hónapokra is.

$day01 = $testDate->englishDayOfWeek;
$day02 = $testDate->shortEnglisDayOfWeek;
$day03 = $testDate->locale( "hu" )->dayName;
$day04 = $testDate->locale( "hu" )->shortDayName;
$day04 = $testDate->locale( "hu" )->minDayName;
 
$month01 = $testDate->englishMonth;
$month02 = $testDate->shortEnglishMonth;
$month03 = $testDate->locale( "hu" )->monthName;

További adatokat kérdezhetünk le.

$week = $testDate->weekOfYear;
$dayNumber = $testDate->daysInMonth;
$timestamp = $testDate->getTimeStamp();     //Ezt Unix időben kapjuk

A szetterek a PHP __set() metódusán keresztül valósulnak meg, fontos, hogy a Carbon példány időzónáját nem módosítják.

$date = Carbon::now();
 
$date->year = 1975;
$date->month = 13;
$date->month = 5;
$date->day = 21;
$date->hour = 22;
$date->minute = 32;
$date->second = 5;

Másik lehetőség:

$date->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();
$date->setDate(1975, 5, 21)->setTime(22, 32, 5)->toDateTimeString();
$date->setDate(1975, 5, 21)->setTimeFromTimeString('22:32:05')->toDateTimeString();
$date->setDateTime(1975, 5, 21, 22, 32, 5)->toDateTimeString();

Van lehetőség egy meglévő időpont módosítására is a modify() metódus használatával.

$modTime = $testDate->modify( "+3 hours" );

Lehetőség van a Carbon objektumban tárolt dátumok kimenetének a formázására is. Generáljunk egy dátumot.

$date = Carbon::create( 2024, 5, 22, 14, 15 );

Néhány példa a formázásra:

$date->toDateString();               // 2024-05-22
$date->toFormattedDateString();      // May 05 2024 14:15:00
$date->toFormattedDayDateString();   // Wed, May 05 2024 14:15:00
$date->toTimeString();               // 14:15:00
$date->toDateTimeString();           // 2024-05-22 14:15:00
$date->toDayDateTimeString();        // Wed, May 22, 2024 2:15 PM
$date->toJSON()                      // 2024-05-22T14:15:00.61258Z

Lehetőség van két dátum különböző vizsgálatára. Generáljunk két dátumot.

$date01 = Carbon::create( 2024, 5, 15, 12, 21, 0 );
$date02 = Carbon::create( 2024, 5, 25, 6, 12, 0 );

Néhány példa az összehasonlításukra. Ezeket a feltételeket több formában is megadhatjuk.

$test01 = $date01->equalTo( $date02 );
$test02 = $date01->eq( $date02 );
$test03 = $date01 == $date02
 
$test04 = $date01->notEqualTo( $date02 );
$test05 = $date01->ne( $date02 );
$test06 = $date01 != $date02

$test01 = $date01->greatherThan( $date02 );
$test02 = $date01->gt( $date02 );
$test03 = $date01->isAfter( $date02 );
$test04 = $date01 > $date02;

$test01 = $date01->greatherThanOrEqualTo( $date02 );
$test02 = $date01->gte( $date02 );
$test04 = $date01 >= $date02;

$test01 = $date01->lessThan( $date02 );
$test02 = $date01->lt( $date02 );
$test03 = $date01->isBefore( $date02 );
$test04 = $date01 < $date02;

$test01 = $date01->lessThanOrEqualTo( $date02 );
$test02 = $date01->lte( $date02 );
$test04 = $date01 <= $date02;

Generáljunk egy harmadik dátumot.

$date03 = Carbon::create( 2024, 5, 20, 15, 45, 0 );

$test01 = $date03->between( $date01, $date02 );
$test02 = $date03->isBetween( $date01, $date02 );
$test03 = $date03->betweenIncluded( $date01, $date02 );
$test04 = $date03->betweenExcluded( $date01, $date02 );

A Carbon osztállyal kezelhetünk időintervallumokat is, tudunk hozzáadni illetve kivonni időintervallumokat az aktuálisan kezelt időhöz képest. Generáljunk egy időpontot.

$testDate = Carbon::create( 2024, 5, 16, 11, 40, 0 );  //2024-05-16 11:40:00

$century01 = $testDate->addCentury();
$century02 = $testDate->addCenturies( 5 );
 
$year01 = $testDate->addYear();
$year02 = $testDate->addYears( 5 );
 
$month01 = $testDAte->addMonth();
$month02 = $testDAte->addMonths( 5 );
 
$week01 = $testDate->addWeek();
$week02 = $testDate->addWeeks( 5 );
 
$day01 = $testDate->addDay();
$day02 = $testDate->addDays( 5 );
$day03 = $testDate->addWeekDay();
$day03 = $testDate->addWeekDays( 5 );
 
$hour01 = $testDate->addHour();
$hour02 = $testDate->addHours( 5 );
 
$minute01 = $testDate->addMinute();
$minute02 = $testDate->addMinutes( 5 );
 
$second01 = $testDate->addSecond();
$second02 = $testDate->addSeconds( 5 );
 
$milliSecond01 = $testDate->addMilliSecond();
$milliSecond02 = $testDate->addMilliSeconds( 5 );
 
$microSecond01 = $testDate->addMicroSecond();
$microSecond02 = $testDate->addMicroSeconds( 5 );

$century01 = $testDate->subCentury();
$century02 = $testDate->subCenturies( 5 );
 
$year01 = $testDate->subYear();
$year02 = $testDate->subYears( 5 );
 
$month01 = $testDAte->subMonth();
$month02 = $testDAte->subMonths( 5 );
 
$week01 = $testDate->subWeek();
$week02 = $testDate->subWeeks( 5 );
 
$day01 = $testDate->subDay();
$day02 = $testDate->subDays( 5 );
$day03 = $testDate->subWeekDay();
$day03 = $testDate->subWeekDays( 5 );
 
$hour01 = $testDate->subHour();
$hour02 = $testDate->subHours( 5 );
 
$minute01 = $testDate->subMinute();
$minute02 = $testDate->subMinutes( 5 );
 
$second01 = $testDate->subSecond();
$second02 = $testDate->subSeconds( 5 );
 
$milliSecond01 = $testDate->subMilliSecond();
$milliSecond02 = $testDate->subMilliSeconds( 5 );
 
$microSecond01 = $testDate->subMicroSecond();
$microSecond02 = $testDate->subMicroSeconds( 5 );

A diff kifejezéssel tudjuk vizsgálni az időkülönbségeket. Ezek a vizsgálatok integer típust adnak vissza, tehát, ha nem egész szám az eredmény abban az esetben csonkolják a visszaadott értéket. Generáljunk két időpontot.

$testDate01 = Carbon::create( 2024, 6, 11, 16, 42, 0,);     // 2024-06-11 16:42:00
$testDate02 = Carbon::create( 2024, 10, 26, 9, 16, 0,);     // 2024-10-16 09:16:00

A különbségeket lekérdezhetjük több időegységben. Néhány példa:

$diff01 = $testDate01->diffInWeeks( $testDate02 );
$diff02 = $testDate01->diffInWeekDays( $testDate02 );
$diff03 = $testDate01->diffInWeekendDays( $testDate02 );
$diff04 = $testDate01->diffInDays( $testDate02 );
$diff05 = $testDate01->diffInHours( $testDate02 );
$diff06 = $testDate01->diffInMinutes( $testDate02 );

Ha szeretnénk megkapni a pontos értéket, abban az esetben használjuk a floatDiffIn() metódust. Természetesen ezt csak abban az esetben használhatjuk mikor nem egész szám az eredmény.

$diff01 = $testDate01->floatDiffInMonths( $testDate02 );
$diff02 = $testDate01->floatDiffInHours( $testDate02 );
$diff03 = $testDate01->floatDiffInMinutes( $testDate02 );

Mint a neve is mutatja a Carbon objektumoknak átadhatunk módosítókat melyek visszaadják a megadott dátumhoz képest a megváltoztatott időpontot. Fontos, hogy a visszaadott érték ideje mindig 00:00:00, kivéve a lekérdezett vég időpontot. Ilyenkor az alapértelmezett idő a 23:59:59. Generáljunk egy dátumot.

$testTime = Carbon::create( 2024, 11, 5, 9, 26 );

Néhány példa a módosítókra:

$time01 = $testTime->startOfYear();
$time02 = $testTime->endOfYear();
$time03 = $testTime->startOfMonth();
$time04 = $testTime->endOfMonth();
$time05 = $testTime->startOfWeek();
$time06 = $testTime->endOfWeek();
$time07 = $testTime->startOfDay();
$time08 = $testTime->endOfDay();
$time09 = $testTime->startOfHour();
$time10 = $testTime->endOfHour();
$time11 = $testTime->startOfMinute();
$time12 = $testTime->endOfMinute();
$time13 = $testTime->endOfSecond();

Másik példa a módosítókra, átadhatunk paraméterként adott napokat is.

$time01 = $testTime->firstOfYear();
$time02 = $testTime->firstOfYear( Carbon::MONDAY );
$time03 = $testTime->lastOfYear();
$time04 = $testTime->lastOfYear( Carbon::FRIDAY );
$time05 = $testTime->firstOfMonth();
$time06 = $testTime->firstOfMonth( Carbon::TUESDAY );
$time07 = $testTime->lastOfMonth();
$time08 = $testTime->lastOfMonth( Carbon::SATURDAY );
 
$time09 = $testTime->nextWeekDay();
$time10 = $testTime->previousWeekDay();
$time11 = $testTime->nextWeekendDay();
$time12 = $testTime->previousWeekendDay();

• https://laravel.com/docs/12.x
• https://carbon.nesbot.com/docs