Carbon (Date/Time)

• Introduction
• Creating Carbon Instances
• Formatting
• Manipulation
• Comparison
• Human Readable
• Model Integration

Introduction

Magic includes Carbon, a powerful date/time utility inspired by PHP's Carbon library. Carbon provides an expressive, fluent API for creating, formatting, and manipulating dates and times.

// Create, manipulate, and format dates fluently
Carbon.now().addDays(5).format('MMMM d, yyyy');  // "January 20, 2024"

// Human-readable differences
carbon.diffForHumans();  // "2 days ago"

Creating Carbon Instances

// Current date/time
final now = Carbon.now();

// Parse from string
final date = Carbon.parse('2024-01-15');
final datetime = Carbon.parse('2024-01-15 14:30:00');
final iso = Carbon.parse('2024-01-15T14:30:00Z');

// From DateTime
final fromDart = Carbon.fromDateTime(DateTime.now());

// Specific dates
final today = Carbon.today();       // Today at 00:00:00
final tomorrow = Carbon.tomorrow();
final yesterday = Carbon.yesterday();

Formatting

final date = Carbon.now();

// Standard formats
date.format('yyyy-MM-dd');           // "2024-01-15"
date.format('dd/MM/yyyy');           // "15/01/2024"
date.format('MMMM d, yyyy');         // "January 15, 2024"
date.format('EEEE');                 // "Monday"
date.format('h:mm a');               // "2:30 PM"

// ISO 8601
date.toIso8601String();              // "2024-01-15T14:30:00.000Z"

// Convenience methods
date.toDateString();                 // "2024-01-15"
date.toTimeString();                 // "14:30:00"
date.toDateTimeString();             // "2024-01-15 14:30:00"

Format Tokens

Manipulation

Adding Time

final date = Carbon.now();

date.addSeconds(30);
date.addMinutes(15);
date.addHours(2);
date.addDays(5);
date.addWeeks(2);
date.addMonths(3);
date.addYears(1);

Subtracting Time

date.subSeconds(30);
date.subMinutes(15);
date.subHours(2);
date.subDays(5);
date.subWeeks(2);
date.subMonths(3);
date.subYears(1);

Start/End of Period

date.startOfDay();     // 00:00:00
date.endOfDay();       // 23:59:59
date.startOfWeek();    // Monday 00:00:00
date.endOfWeek();      // Sunday 23:59:59
date.startOfMonth();   // First day 00:00:00
date.endOfMonth();     // Last day 23:59:59

Comparison

final date1 = Carbon.parse('2024-01-15');
final date2 = Carbon.parse('2024-01-20');

// Boolean comparisons
date1.isBefore(date2);    // true
date1.isAfter(date2);     // false
date1.isSame(date2);      // false

// Special checks
date.isToday();
date.isTomorrow();
date.isYesterday();
date.isWeekend();
date.isWeekday();
date.isFuture();
date.isPast();

// Between check
date.isBetween(startDate, endDate);

Difference

final start = Carbon.parse('2024-01-15');
final end = Carbon.parse('2024-01-20');

start.diff(end).inDays;      // 5
start.diff(end).inHours;     // 120
start.diff(end).inMinutes;   // 7200

Human Readable

The diffForHumans() method returns a human-readable string:

Carbon.now().subMinutes(5).diffForHumans();   // "5 minutes ago"
Carbon.now().subHours(2).diffForHumans();     // "2 hours ago"
Carbon.now().subDays(1).diffForHumans();      // "1 day ago"
Carbon.now().subMonths(3).diffForHumans();    // "3 months ago"

// Future dates
Carbon.now().addDays(3).diffForHumans();      // "in 3 days"
Carbon.now().addHours(1).diffForHumans();     // "in 1 hour"

Relative To Another Date

final date1 = Carbon.parse('2024-01-15');
final date2 = Carbon.parse('2024-01-20');

date1.diffForHumans(date2);  // "5 days before"
date2.diffForHumans(date1);  // "5 days after"

Model Integration

Carbon integrates seamlessly with Eloquent models through attribute casting:

class Post extends Model with HasTimestamps {
  @override
  Map get casts => {
    'published_at': 'datetime',
    'expires_at': 'datetime',
  };

  // Typed getter
  Carbon? get publishedAt => getAttribute('published_at') as Carbon?;
  Carbon? get expiresAt => getAttribute('expires_at') as Carbon?;
}

Using in Views

// Display formatted date
WText(post.publishedAt?.format('MMMM d, yyyy') ?? 'Draft')

// Human-readable
WText(post.publishedAt?.diffForHumans() ?? '')  // "2 days ago"

// Conditional display
if (post.expiresAt?.isFuture() == true) {
  WText('Expires ${post.expiresAt!.diffForHumans()}');
}

HasTimestamps Mixin

Models using HasTimestamps automatically get createdAt and updatedAt as Carbon instances:

class User extends Model with HasTimestamps {
  // Automatically available:
  // Carbon? get createdAt
  // Carbon? get updatedAt
}

// Usage
WText('Member since ${user.createdAt?.format('MMM yyyy')}');

[!TIP] Use diffForHumans() in your UI for relative timestamps that are easier for users to understand.