Carbon

Carbon extends PHP’s native DateTime class with a fluent, chainable API for creating, parsing, comparing, and formatting dates and times. It is one of the most widely used PHP packages, forming the date-handling backbone of the Laravel framework and countless standalone projects.

Beyond convenience methods like addDays(), isWeekend(), or diffForHumans(), Carbon ships with extensive internationalization support, covering over 280 languages and regional variants, plus first-class support for immutable dates, custom test-time mocking, and period/interval calculations.

What You Get

• Fluent, chainable methods for creating, mutating, and comparing dates (addDay(), subWeek(), gte(), isWeekend())
• Both mutable (Carbon) and immutable (CarbonImmutable) date classes
• Human-readable relative time formatting (diffForHumans()) in 280+ languages and regional variants
• CarbonInterval and CarbonPeriod classes for representing durations and recurring date ranges
• Deterministic testing support via Carbon::setTestNow() to mock the current time
• A Laravel service provider and macro system for extending Carbon with custom methods

Common Use Cases

• Formatting and displaying human-friendly timestamps (‘2 minutes ago’) in web applications
• Calculating durations, ages, and business-day offsets between dates
• Generating recurring date schedules (e.g. billing cycles) with CarbonPeriod
• Localizing date and time output for internationalized applications
• Writing deterministic, time-independent unit tests via test-now mocking

Under The Hood

Architecture Carbon layers on top of PHP’s built-in DateTime/DateTimeImmutable classes rather than replacing them: Carbon extends DateTime and CarbonImmutable extends DateTimeImmutable, so any code that type-hints against the native classes keeps working. Behavior shared between the two variants (formatting, diffing, localization, period math) lives in ~25 traits under src/Carbon/Traits/ (e.g. Units.php, Difference.php, Rounding.php, Comparison.php) that both classes compose via use, keeping the mutable/immutable split from duplicating logic. CarbonInterval and CarbonPeriod are separate value-object classes built on the same traits for durations and recurring ranges. Tech Stack The library targets PHP 8.1+, depends on symfony/translation and symfony/clock for localization and clock abstraction, and provides a psr/clock-implementation. A Laravel ServiceProvider (src/Carbon/Laravel/ServiceProvider.php) auto-registers Carbon as Laravel’s date class. Tooling includes PHPUnit, PHPStan, PHP-CS-Fixer, and PHPMD, all wired through Composer scripts. Code Quality The tests/ directory mirrors src/Carbon/ closely, with dedicated suites per trait/class plus AbstractTestCase/AbstractTestCaseWithOldNow base classes for time-mocked assertions; PHPStan and PHPMD run in CI alongside PHPUnit for static analysis and style enforcement. With 369 contributors and 4,794+ commits, naming and structure are consistent throughout. API Design The fluent, chainable method style (Carbon::now()->addDay()->startOfDay()) is Carbon’s signature strength — method names read close to natural language, static factories (Carbon::create(), ::parse(), ::createFromTimestamp()) cover common construction paths, and diffForHumans() gives good defaults for the most common formatting need without extra configuration.