Carbon for PHP

If you are not using Composer, you can install Carbon manually:

1. Download the latest release from the GitHub releases page.
2. Extract the contents of the ZIP archive into a directory within your project.
3. Require the autoload.php file from that directory in your project to load Carbon and its dependencies.

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

use Carbon//Carbon;

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

To add Carbon to your PHP project 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 include the Composer autoloader in your PHP script to use Carbon classes:

<?php
require 'vendor/autoload.php';

use Carbon//Carbon;

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

The ParseErrorException is thrown by Carbon when a date string does not match the expected format during parsing operations. This exception extends InvalidArgumentException.

When catching this exception, you can inspect the following methods to understand why the parsing failed:

• getExpected(): Returns the format or pattern that was expected.
• getActual(): Returns the actual value that was provided (or 'data is missing' if the input was empty).
• getHelp(): Returns an additional help message provided during the exception construction.

The error message follows the pattern: Format expected {expected} but {actual} {help}.

The cast(string $className) method allows you to convert the current CarbonTimeZone instance into another class.

For the cast to work, the target $className must have an instance() method. If the target class is a subclass of DateTimeZone but lacks an instance() method, Carbon will attempt to return a new instance of that class using the current timezone name.

use Carbon\CarbonTimeZone;

$tz = new CarbonTimeZone('UTC');

// Cast to a specific class that implements instance()
// Note: The target class must have an instance() method
$other = $tz->cast(SomeOtherTimeZoneClass::class);

You can retrieve the abbreviated name of a timezone (e.g., 'EST', 'GMT') using getAbbreviatedName() or its alias getAbbr(). This method allows you to specify whether Daylight Saving Time (DST) is active to ensure the correct abbreviation is returned.

• $dst = true: Returns the abbreviation used during DST.
• $dst = false: Returns the abbreviation used during standard time.

use Carbon\CarbonTimeZone;

$tz = new CarbonTimeZone('America/New_York');

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

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

The NotACarbonClassException is thrown when an operation expects a class implementing CarbonInterface, but receives a different class. This is a security measure to prevent unpredictable behavior, especially when unserializing untrusted data.

If you are certain that the class being used is safe, you can bypass this check using the allow() method. This method accepts a closure containing the logic that would otherwise trigger the exception.

// Example of bypassing the check safely if you trust the input
$result = NotACarbonClassException::allow(static fn () => $yourCarbonOperation);

You can create a CarbonTimeZone instance using the constructor or the instance() static method. The instance() method is more flexible as it handles various input types including DateTimeZone objects, strings, integers, floats, null, or false.

Supported inputs:

• Strings: Timezone identifiers (e.g., 'Europe/London') or offset strings (e.g., '+05:30').
• Numeric values: Hour or minute offsets.
• DateTimeZone: Existing PHP DateTimeZone objects.

If the input is null or false, instance() returns null. If the timezone is invalid, it throws an InvalidTimeZoneException.

use Carbon\CarbonTimeZone;

// From string identifier
$tz = new CarbonTimeZone('America/New_York');

// From mixed input using instance()
$tz = CarbonTimeZone::instance('+05:30');

// Handling null/false
$tz = CarbonTimeZone::instance(null); // returns null

Carbon provides specialized static methods to create timezones based on numeric offsets (hours or minutes).

• createFromHourOffset(float $hourOffset): Creates a timezone from a decimal hour offset (e.g., 5.5 for UTC+5:30).
• createFromMinuteOffset(float $minuteOffset): Creates a timezone from a total number of minutes.
• getOffsetNameFromMinuteOffset(float $minutes): A utility to convert a minute offset into a standardized string format like +HH:MM or -HH:MM.

use Carbon\CarbonTimeZone;

// Create from 5.5 hours
$tz = CarbonTimeZone::createFromHourOffset(5.5);

// Create from 330 minutes
$tz = CarbonTimeZone::createFromMinuteOffset(330);

// Get the string representation of an offset
$offsetString = CarbonTimeZone::getOffsetNameFromMinuteOffset(330); // '+05:30'

The NotACarbonClassException::expectCarbonInterface(mixed $className) method can be used to programmatically verify if a given class name implements CarbonInterface.

If the class does not implement the interface, it throws a NotACarbonClassException. Note that this check is subject to the TogglableDetection trait, meaning the exception might not be thrown if detection is disabled via the internal state of the exception class.

use Carbon\Exceptions\NotACarbonClassException;

// This will throw NotACarbonClassException if $className is not a CarbonInterface implementation
NotACarbonClassException::expectCarbonInterface($className);