Carbon PHP Extension

The recommended way to install Carbon is using Composer. Run the following command in your terminal:

$ composer require nesbot/carbon

Alternatively, you can manually add it to your composer.json file:

{
    "require": {
        "nesbot/carbon": "^3"
    }
}

After installation, ensure you require the Composer autoloader in your PHP script to use Carbon classes.

If you are not using Composer, download the latest release ZIP archive from the GitHub releases page. Extract the contents into a directory within your project, then require the autoload.php file located in that directory to load Carbon and its dependencies.

<?php
require 'path-to-Carbon-directory/autoload.php';

use Carbon// Carbon class

printf("Now: %s", Carbon::now());

<?php
require 'path-to-Carbon-directory/autoload.php';

use Carbon\Carbon;

printf("Now: %s", Carbon::now());

For testing purposes, you can mock the current time using Carbon::setTestNow(). This allows you to simulate a specific point in time throughout your application. To return to the actual current time, call Carbon::setTestNow() without any arguments.

<?php

use Carbon\Carbon;

// Mock 'now' to a specific date
Carbon::setTestNow(Carbon::createFromDate(2000, 1, 1));

// ... perform tests where Carbon::now() returns Jan 1, 2000

// Return to normal behavior
Carbon::setTestNow();

You can retrieve the abbreviated name of a timezone (e.g., EST, GMT) based on whether Daylight Saving Time (DST) is active.

• getAbbreviatedName(bool $dst = false): Returns the abbreviation. Set $dst to true to get the abbreviation used during DST.
• getAbbr(bool $dst = false): An alias for getAbbreviatedName().

// Get abbreviation for standard time
$abbr = $timezone->getAbbr(false); // e.g., 'EST'

// Get abbreviation for daylight saving time
$abbr = $timezone->getAbbr(true);  // e.g., 'EDT'

The getType() method returns an integer representing the type of timezone identifier used:

• Type 1: A UTC offset (e.g., -0300).
• Type 2: A timezone abbreviation (e.g., GMT).
• Type 3: A timezone identifier (e.g., Europe/London).

The cast() method allows you to convert the current CarbonTimeZone instance into another class, provided that the target class implements an instance() method designed to handle the conversion.

If the target class is a subclass of DateTimeZone but lacks an instance() method, cast() will return a new instance of that class using the current timezone name.

// Example: Casting to a specific DateTimeZone implementation if available
$otherTz = $carbonTz->cast(SomeCustomDateTimeZone::class);

When performing date string parsing operations in Carbon, a ParseErrorException may be thrown if the input string does not match the expected format. This exception extends InvalidArgumentException and provides specific details about the mismatch.

You can catch this exception to programmatically inspect what format was expected versus what was actually received, or to display a custom help message provided by the library.

Key methods for inspecting the error:

• getExpected(): Returns the format string that was expected.
• getActual(): Returns the actual value that caused the failure (or 'data is missing' if the input was empty).
• getHelp(): Returns an additional help message describing how to resolve the error.

The CarbonPeriodImmutable class extends CarbonPeriod to provide a period where the individual date instances returned during iteration are immutable. By default, it uses CarbonImmutable as the date class for all iteration items. This ensures that any modifications to a date within the period do not affect the period itself or other dates in the sequence.

use Carbon\CarbonPeriodImmutable;
use Carbon\CarbonImmutable;

// Example usage (conceptual based on class definition):
// Creating a period where each step is a CarbonImmutable instance
$period = CarbonPeriodImmutable::create('2023-01-01', '2023-01-05');

foreach ($period as $date) {
    // $date is an instance of CarbonImmutable
    echo $date->toDateTimeString() . PHP_EOL;
}