Carbonated

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.
• Localizable Dates (cause Carbon use strftime internally, you have to change the placeholders. http://www.php.net/strftime)

Requirements

• PHP 7.0+ and Laravel 5.0+ or illuminate/database 5.0+

Installation

Via Composer:

composer require okaufmann/carbonated

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

Configuration

Register the Service Provider

// config/app.php
'providers' => [
    ...
    ThisVessel\CarbonatedServiceProvider::class,
];

Carbonated provides a configuration example.

So you can test publishing assets with:

$ php artisan vendor:publish --provider="ThisVessel\CarbonatedServiceProvider"

This will create a config/carbonated.php file in your app that you can modify to set your configuration. Also, make sure you check for changes to the original config file in this package between releases.

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.

Localization

If you need to display your dates with days of week, you can enable Localization in config file config/carbonated.php.

return [
    /*
     * Format dates with carbons formatLocalized method to localize ex. weekday.
     */
    'localization' => true,
];

If this is set, Carbonated will use http://www.php.net/strftime to format date strings. Follow the docs to choose placeholdes (the %A ones...).