Carbon PHP: методы, примеры, установка

Что такое Carbon и зачем он нужен?

Carbon — это мощная и элегантная библиотека для PHP, которая расширяет встроенный класс DateTime. Если вы когда-либо работали с датами в PHP нативно, вы знаете, что стандартный DateTime и DateTimeImmutable предоставляют базовый функционал, но их API часто громоздкий и неинтуитивный. Carbon решает эту проблему, предлагая чистый, читаемый и выразительный синтаксис для работы с датами и временем.

Зачем использовать Carbon? Представьте, что вам нужно:

Добавить 3 дня к текущей дате: $date->add(new DateInterval('P3D')) (нативный PHP) vs $date->addDays(3) (Carbon).
Получить разницу в днях между двумя датами: громоздкий DateTime::diff() с последующим форматированием vs $date1->diffInDays($date2).
Проверить, является ли дата выходным днём: написание собственной логики vs $date->isWeekend().

Carbon делает код не только короче, но и значительно понятнее. Он широко используется в современных PHP-фреймворках, таких как Laravel (где он является стандартом), Symfony, Yii и других. Библиотека полностью совместима с нативным DateTime, что означает, что вы можете использовать Carbon везде, где ожидается DateTime.

Ключевые преимущества Carbon:

Выразительный синтаксис: методы названы так, что их назначение понятно без комментариев (startOfDay(), endOfMonth(), isFuture()).
Неизменяемость (Immutable): поддержка CarbonImmutable для безопасной работы с датами без побочных эффектов.
Локализация: встроенная поддержка форматирования дат на разных языках.
Богатый API: сотни методов для манипуляции, сравнения, форматирования и вычисления дат.
Интуитивное сравнение: методы типа isBefore(), isAfter(), isSameDay().

Установка Carbon

Carbon устанавливается через Composer — стандартный менеджер пакетов для PHP. Если у вас ещё нет Composer, его необходимо установить (см. getcomposer.org).

Откройте терминал в корне вашего проекта и выполните команду:

composer require nesbot/carbon

После успешной установки в вашем проекте появится папка vendor/ и файл composer.json с добавленной зависимостью. Чтобы использовать Carbon в своём коде, необходимо подключить автозагрузчик Composer:

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

use Carbon\Carbon;

// Теперь можно использовать Carbon
echo Carbon::now(); // 2025-04-03 15:30:00
?>

Важно: Carbon требует PHP версии 8.0 или выше (для последних версий). Рекомендуется использовать PHP 8.1+.

Быстрый старт с примером кода

Давайте сразу перейдём к практике. Вот несколько простых примеров, которые демонстрируют мощь Carbon:

<?php
require_once 'vendor/autoload.php';
use Carbon\Carbon;

// Текущая дата и время
$now = Carbon::now();
echo "Сейчас: " . $now . "\n"; // 2025-04-03 15:30:00

// Создание даты из строки
$birthday = Carbon::createFromDate(1990, 5, 15);
echo "День рождения: " . $birthday->format('d.m.Y') . "\n"; // 15.05.1990

// Манипуляции с датами
$tomorrow = Carbon::tomorrow();
echo "Завтра: " . $tomorrow . "\n";

$nextWeek = Carbon::now()->addWeek();
echo "Через неделю: " . $nextWeek . "\n";

// Разница между датами
$age = $birthday->diffInYears(Carbon::now());
echo "Возраст: $age лет\n"; // 34 или 35

// Проверка условий
$date = Carbon::parse('2025-12-25');
if ($date->isChristmas()) {
    echo "Это Рождество!\n";
}

// Человекочитаемое представление разницы
echo Carbon::now()->subDays(5)->diffForHumans(); // "5 дней назад"
?>

Как видите, код читается почти как обычный английский язык. Это и есть главная философия Carbon.

Основные методы и функции Carbon

Рассмотрим 10 наиболее часто используемых методов Carbon с подробным описанием и примерами.

1. `Carbon::now()` и `Carbon::today()`

Что делает: Создаёт объект Carbon с текущей датой и временем (now) или только с текущей датой, обнуляя время до 00:00:00 (today).

Параметры: Необязательный параметр — часовой пояс (строка, например, 'Europe/Moscow').

Пример:

<?php
$nowInMoscow = Carbon::now('Europe/Moscow');
echo $nowInMoscow; // 2025-04-03 18:30:00 (если UTC+3)

$todayStart = Carbon::today();
echo $todayStart; // 2025-04-03 00:00:00
?>

2. `Carbon::parse()`

Что делает: Универсальный метод для создания объекта Carbon из различных форматов даты и времени. Принимает строку, число (timestamp) или другой объект DateTime.

Параметры: $time — строка, int, DateTime; $tz — часовой пояс (опционально).

Пример:

<?php
$date1 = Carbon::parse('2025-04-03');
$date2 = Carbon::parse('next Friday');
$date3 = Carbon::parse('+2 weeks');
$date4 = Carbon::parse('2025-04-03 15:30:00', 'America/New_York');

echo $date1; // 2025-04-03 00:00:00
echo $date2; // 2025-04-11 00:00:00 (если сегодня четверг)
echo $date3; // 2025-04-17 15:30:00 (относительно текущего момента)
?>

3. `addDays()`, `subDays()` и аналогичные

Что делает: Добавляет или вычитает указанное количество дней (недель, месяцев, лет, часов, минут, секунд) к дате. Методы возвращают новый объект Carbon (Carbon неизменяем).

Параметры: $value — целое число (может быть отрицательным).

Пример:

<?php
$date = Carbon::parse('2025-04-03');

$nextDay = $date->addDay(); // +1 день
$previousMonth = $date->subMonth(); // -1 месяц
$inTwoYears = $date->addYears(2); // +2 года
$minus30Minutes = $date->subMinutes(30); // -30 минут

echo $nextDay; // 2025-04-04
echo $previousMonth; // 2025-03-03
echo $inTwoYears; // 2027-04-03
echo $minus30Minutes; // 2025-04-03 14:30:00 (если исходное время было 15:00)
?>

Важно: Все методы модификации (add*, sub*) возвращают новый объект. Исходный объект остаётся неизменным.

4. `diffInDays()`, `diffInHours()` и другие `diff*()`

Что делает: Вычисляет разницу между текущим объектом и переданной датой в указанных единицах (дни, часы, минуты, секунды, годы, месяцы и т.д.).

Параметры: $date — объект Carbon или DateTime; $absolute — boolean (если true, возвращает абсолютное значение).

Пример:

<?php
$start = Carbon::parse('2025-01-01');
$end = Carbon::parse('2025-04-03');

$days = $start->diffInDays($end);
$hours = $start->diffInHours($end);
$weeks = $start->diffInWeeks($end);
$minutes = $start->diffInMinutes($end, false); // отрицательное, если start > end

echo "Дней: $days"; // 92
echo "Часов: $hours"; // 2208
echo "Недель: $weeks"; // 13
echo "Минут: $minutes"; // 132480
?>

5. `diffForHumans()`

Что делает: Возвращает человекочитаемое представление разницы между датами. Идеально подходит для вывода типа "3 дня назад", "через 2 недели".

Параметры: $other — дата для сравнения (если не указана, сравнивается с now()); $syntax — флаги для настройки вывода; $short — использовать короткую форму (например, "3 дн. назад").

Пример:

<?php
$date = Carbon::parse('-3 days');
echo $date->diffForHumans(); // "3 дня назад"

$futureDate = Carbon::parse('+2 weeks');
echo $futureDate->diffForHumans(); // "через 2 недели"

// Сравнение с конкретной датой
$birthday = Carbon::parse('1990-05-15');
echo $birthday->diffForHumans(Carbon::now()); // "34 года назад" (или "35 лет назад")

// Короткая форма
echo $date->diffForHumans(null, true); // "3 дн. назад"
?>

6. `format()`

Что делает: Форматирует дату в строку согласно переданному формату. Использует те же символы формата, что и стандартная PHP-функция date().

Параметры: $format — строка формата (например, 'd.m.Y H:i:s').

Пример:

<?php
$date = Carbon::now();

echo $date->format('d.m.Y'); // 03.04.2025
echo $date->format('l, jS F Y'); // Thursday, 3rd April 2025
echo $date->format('H:i:s'); // 15:30:00
echo $date->format('Y-m-d\TH:i:sP'); // 2025-04-03T15:30:00+03:00 (ISO 8601)
?>

7. `isWeekend()`, `isWeekday()`, `isMonday()` и другие `is*()`

Что делает: Проверяет, соответствует ли дата определённому условию (выходной, будний день, конкретный день недели, начало/конец месяца, года и т.д.).

Параметры: Нет (для простых проверок) или дата для сравнения.

Пример:

<?php
$saturday = Carbon::parse('2025-04-05'); // Это суббота
$friday = Carbon::parse('2025-04-04');

var_dump($saturday->isWeekend()); // true
var_dump($friday->isWeekday()); // true
var_dump($saturday->isMonday()); // false
var_dump($saturday->isSaturday()); // true

// Проверка начала/конца
$date = Carbon::parse('2025-04-01');
var_dump($date->isStartOfMonth()); // true
var_dump($date->isEndOfMonth()); // false

// isPast / isFuture
var_dump(Carbon::parse('-1 day')->isPast()); // true


                
    
  Также в библиотеке
  
                
                  
                 Webpack для JavaScript (Node.js): полное руководство с примерами
      
                
                  
                 Lodash для JavaScript (Node.js): полное руководство с примерами
      
                
                  
                 Работа с ZIP/архивами в Kotlin: ZIP-InputStream и ZipFile
      
                
                  
                 Тестирование в TypeScript с Jest
      
                
                  
                 WebSocket библиотеки для Node.js: ws, Socket.IO, uWS — полный обзор