====== Laravel Dátum és idő kezelés ======

  * **Szerző:** Rékási József
  * Copyright (c) Rékási József, 2022
  * Licenc: [[https://creativecommons.org/licenses/by-sa/4.0/|CC Attribution-Share Alike 4.0 International]]
  * Web: https://szit.hu
==== Carbon osztály ====
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.
<code>
use Carbon\Carbon
</code>
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.
<code php>
$actualTime = Carbon::now();
$actualTimeZone = Carbon::now()->timezoneName;
$actualTimeBudapest = Carbon::now( "Europe/Budapest" );
</code>
Lekérdezhetünk közvetlenül napokat is. Ebben az esetben az idő mindig 00:00:00 lesz.
<code php>
$yesterday = Carbon::yesterday();
$today = Carbon::today();
$tomorrow = Carbon::tomorrow();
$dayOfWeek01 = new Carbon( "last wednesday" );
$dayOfWeek02 = new Carbon( "next thursday" ); 
$dayOfWeek03 = new Carbon( "this friday" ); 
</code>
Az aktuális Carbon objektum tárolja a lekérdezett időt, ezekhez tudunk hozzáadni időintervallumokat is.
<code php>
$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 );
</code>
=== Konstansok ===
<code php>
Carbon::SUNDAY;                          // int(0)
Carbon::MONDAY;                          // int(1)
Carbon::TUESDAY;                         // int(2)
Carbon::WEDNESDAY;                       // int(3)
Carbon::THURSDAY;                        // int(4)
Carbon::FRIDAY;                          // int(5)
Carbon::SATURDAY;                        // int(6)

Carbon::YEARS_PER_CENTURY;               // int(100)
Carbon::YEARS_PER_DECADE;                // int(10)
Carbon::MONTHS_PER_YEAR;                 // int(12)
Carbon::WEEKS_PER_YEAR;                  // int(52)
Carbon::DAYS_PER_WEEK;                   // int(7)
Carbon::HOURS_PER_DAY;                   // int(24)
Carbon::MINUTES_PER_HOUR;                // int(60)
Carbon::SECONDS_PER_MINUTE;              // int(60)
</code>
==== Dátumok generálása ====
<code php>
// é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" )
</code>
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.
<code php>
$date = Carbon::createSafe( $year, $month, $day );
</code> 
Megadhatunk konkrét feltételeket is.
<code php>
$saturday = new Carbon( "first saturday of 2024" );
$sunday = new Carbon( "first sunday of 2024" );
$monday = new Carbon( "first monday of 2024" );
</code>
Ezeket le is tudjuk kérdezni.
<code php>
$weekend01 = $saturday->isWeekend();     // true
$weekend02 = $sunday->isWeekend();       // true
$weekend03 = $monday->isWeekend();       // false
</code>
==== String típusban tárolt dátumok ====
Az első lehetőség a createFromFormat() metódus.
<code php>
$date = Carbon::createFromFormat( "Y-m-d H", "2025-01-01 15" )->toDateTimeString();    //2025-01-01 15:00:00
</code>
A másik lehetőség a parse() metódus használata.
<code php>
$dateString = "2025-01-01";
$carbonDate = Carbon::parse( $dateString );
</code>
A Carbon több féle dátum típust tud kezelni. Néhány példa:
<code php>
$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" );
</code>
Képes lefordítani nyelvek között a dátumokat. Ezt két féle képpen adhatjuk meg.
<code php>
$translate01 = Carbon::translateTimeString( "January 26, 2024", "en", "hu" );
$translate02 = Carbon::now()->locale( "en" )->translateTimeString( "January 26, 2024",  "hu" );
</code>
==== Getterek ====

A getterek a PHP <nowiki>__get()</nowiki> 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:

<code php>
$testDate = Carbon::parse( "2024-01-01 11:15:00");
</code>

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


<code php>
$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)
</code>

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.

<code php>
$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;
</code>


További adatokat kérdezhetünk le.
<code php>
$week = $testDate->weekOfYear;
$dayNumber = $testDate->daysInMonth;
$timestamp = $testDate->getTimeStamp();     //Ezt Unix időben kapjuk
</code>
==== Szetterek ====
A szetterek a PHP <nowiki>__set()</nowiki> 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.
<code php>
$date = Carbon::now();

$date->year = 1975;
$date->month = 13;
$date->month = 5;
$date->day = 21;
$date->hour = 22;
$date->minute = 32;
$date->second = 5;
</code>

Másik lehetőség:
<code php>
$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();
</code>
Van lehetőség egy meglévő időpont módosítására is a modify() metódus használatával.
<code php>
$modTime = $testDate->modify( "+3 hours" );
</code>
==== Dátumok formázott kimenete ====
Lehetőség van a Carbon objektumban tárolt dátumok kimenetének a formázására is. Generáljunk egy dátumot.
<code php>
$date = Carbon::create( 2024, 5, 22, 14, 15 );
</code>
Néhány példa a formázásra:
<code php>
$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
</code>
==== Dátumok összehasonlítása ====
Lehetőség van két dátum különböző vizsgálatára. Generáljunk két dátumot.
<code php>
$date01 = Carbon::create( 2024, 5, 15, 12, 21, 0 );
$date02 = Carbon::create( 2024, 5, 25, 6, 12, 0 );
</code>
Néhány példa az összehasonlításukra. Ezeket a feltételeket több formában is megadhatjuk.
=== Egyezés ===
<code php>
$test01 = $date01->equalTo( $date02 );
$test02 = $date01->eq( $date02 );
$test03 = $date01 == $date02

$test04 = $date01->notEqualTo( $date02 );
$test05 = $date01->ne( $date02 );
$test06 = $date01 != $date02
</code>
=== Nagyobb mint ===
<code php>
$test01 = $date01->greatherThan( $date02 );
$test02 = $date01->gt( $date02 );
$test03 = $date01->isAfter( $date02 );
$test04 = $date01 > $date02;
</code>
=== Nagyobb vagy egyenlő ===
<code php>
$test01 = $date01->greatherThanOrEqualTo( $date02 );
$test02 = $date01->gte( $date02 );
$test04 = $date01 >= $date02;
</code>
=== Kisebb mint ===
<code php>
$test01 = $date01->lessThan( $date02 );
$test02 = $date01->lt( $date02 );
$test03 = $date01->isBefore( $date02 );
$test04 = $date01 < $date02;
</code>
=== Kisebb vagy egyenlő ===
<code php>
$test01 = $date01->lessThanOrEqualTo( $date02 );
$test02 = $date01->lte( $date02 );
$test04 = $date01 <= $date02;
</code>
=== Benne van -e egy időintervallumban ===
Generáljunk egy harmadik dátumot.
<code php>
$date03 = Carbon::create( 2024, 5, 20, 15, 45, 0 );
</code>
<code php>
$test01 = $date03->between( $date01, $date02 );
$test02 = $date03->isBetween( $date01, $date02 );
$test03 = $date03->betweenIncluded( $date01, $date02 );
$test04 = $date03->betweenExcluded( $date01, $date02 );
</code>
==== Időintervallumok ====
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.
<code php>
$testDate = Carbon::create( 2024, 5, 16, 11, 40, 0 );  //2024-05-16 11:40:00
</code>
=== Hozzáadás ===
<code php>
$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 );
</code>
=== Kivonás ===
<code php>
$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 );
</code>
==== Időpontok közötti különbségek ====
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.
<code php>
$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
</code>
A különbségeket lekérdezhetjük több időegységben. Néhány példa:
<code php>
$diff01 = $testDate01->diffInWeeks( $testDate02 );
$diff02 = $testDate01->diffInWeekDays( $testDate02 );
$diff03 = $testDate01->diffInWeekendDays( $testDate02 );
$diff04 = $testDate01->diffInDays( $testDate02 );
$diff05 = $testDate01->diffInHours( $testDate02 );
$diff06 = $testDate01->diffInMinutes( $testDate02 );
</code>
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.
<code php>
$diff01 = $testDate01->floatDiffInMonths( $testDate02 );
$diff02 = $testDate01->floatDiffInHours( $testDate02 );
$diff03 = $testDate01->floatDiffInMinutes( $testDate02 );
</code>
==== Módosítók ====
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.
<code php>
$testTime = Carbon::create( 2024, 11, 5, 9, 26 );
</code>
Néhány példa a módosítókra:
<code php>
$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();
</code>
Másik példa a módosítókra, átadhatunk paraméterként adott napokat is.
<code php>
$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();
</code>
===== Linkek =====
  * https://laravel.com/docs/12.x
  * https://carbon.nesbot.com/docs