README

DISCLAIMER: This is a work in progress! Use at your own risk! When I am happy with API and test coverage, I will tag version. Suggestions welcome :)

An Eloquent model trait that offers flexible timestamp/date/time handling.

Eloquent provides DateTime handling through Date Mutators. However, it can be cumbersome having to set Accessors for custom DateTime formatting in your front end, and Mutators to correct custom DateTime formatting coming into your database. Also, time field handling, nullable fields and timezone conversion are non-existent. Carbonated aims to help you with these things.

Feature Overview
Requirements
Installation
Basic Usage
Customization
Timezone Conversion

Feature Overview

Automatic accessors and mutators for timestamp, date, and time fields.
Set output formatting once in your model.
No need to format() every attribute for output.
Carbon instances are still available when you need to format() output.
Timezone support with automatic conversion between database and front end.
Plays friendly with form generators that use model binding.

Requirements

Laravel 5.0+ or illuminate/database 5.0+

Installation

Via Composer:

composer require 'thisvessel/carbonated:dev-master'

Note: I will tag version as soon I've added sufficient test coverage.

Basic Usage

Use Carbonated trait in your Eloquent model.

<?php namespace App;

use ThisVessel\Carbonated;

class ServiceOrder extends Model {

    use Carbonated;

}

Add timestamp, date, and time fields to their respective carbonated model properties.

public $carbonatedTimestamps = ['created_at', 'updated_at'];
public $carbonatedDates = ['required_by', 'completed_on', 'invoiced_on'];
public $carbonatedTimes = ['pickup_time'];

That's it! Accessors and mutators are automatically applied with sensible formatting for front end.

{{ $serviceOrder->created_at }}  // Outputs 'Jun 09, 2015 4:10pm'.
{{ $serviceOrder->required_by }} // Outputs 'Jul 30, 2015'.
{{ $serviceOrder->pickup_time }} // Outputs '10:30am'.

If you need access to raw carbon instances, the withCarbon attribute returns a clone of your object with carbon instances instead of formatted strings.

{{ $serviceOrder->withCarbon->required_by->format('M Y') }}

Customization

Customize view output format by adding these properties to your model.

public $carbonatedTimestampFormat = 'M d, Y g:ia';
public $carbonatedDateFormat = 'M d, Y';
public $carbonatedTimeFormat = 'g:ia';

Customize JSON output format by adding these properties to your model.

public $jsonTimestampFormat = 'Y-m-d H:i:s';
public $jsonDateFormat = 'Y-m-d';
public $jsonTimeFormat = 'H:i:s';

Customize database storage format by adding these properties to your model.

public $databaseTimestampFormat = 'Y-m-d H:i:s';
public $databaseDateFormat = 'Y-m-d';
public $databaseTimeFormat = 'H:i:s';

You can also override all automatic accessors and mutators by providing your own Accessor and Mutator methods in your model.

public function getRequiredByAttribute($value)
{
    return $value; // Returns raw value from database.
}

Timezone Conversion

Carbonated supports automatic timezone conversion between your database and front end. For example, maybe you are storing as UTC in your database, but want to output as America/Toronto.

You can set explicitly set timezones by adding these properties to your model.

public $carbonatedTimezone = 'America/Toronto';
public $jsonTimezone = 'UTC';
public $databaseTimezone = 'UTC';

If $carbonatedTimezone is not defined in your model, Carbonated will search for an authenticated user with a $timezone property. This allows the user model be responsible for user specific timezones.

public $timezone = 'America/Toronto;'

The above properties can be set dynamically using Accessors instead of explicit properties.

public function getTimezoneAttribute()
{
    return 'America/Toronto';
}

If either $carbonatedTimezone or $jsonTimezone are undefined, $databaseTimezone will be used as a fallback.

If $databaseTimezone is undefined, the app's timezone (found in /config/app.php) will be used as a fallback.

If you are using Carbonated with Eloquent outside of Laravel, $databaseTimezone will fallback to UTC.

thisvessel / carbonated

Maintainers

Details