Carbon Extension

Table of contents

• Installation
  • Laravel
  • Symfony
• Output
  • Formats
• Input
  • Formats

Installation

• composer require railt/carbon-extension
• Add extension to your application:

$app = new Railt\Foundation\Application();

$app->extend(Railt\CarbonExtension\Extension::class); // Here

Laravel

In that case, if you use Laravel Service Provider this extension can be added as follows:

Open the railt.php configuration file and add:

'extensions' => [
    // ...
    \Railt\CarbonExtension\Extension::class, // Here
]

Symfony

In that case, if you use Symfony Bundle this extension can be added as follows:

Open the config.yml configuration file and add:

railt:
    extensions:
        - Railt\CarbonExtension\Extension # Here

Output

You can use it within your types. After you add type Carbon, two optional arguments appear in the field which is defined by this type.

Those. Client will see the following scheme:

# Definition
type YourExampleType {
    id: ID!
    some: String!
    createdAt: Carbon!
}

# What the client will see
type YourExampleType {
    id: ID!
    some: String!
    createdAt(
        """
        An argument that provides a format of the given value that 
        are contained in a CarbonFormat enumeration type.
        """
        format: CarbonFormat = RFC3339
    ): Carbon!
}

In order to correctly return data - just pass the date type.

Note: The "createdAt" field should provide datetime compatible type, like:

1. DateTime object: http://php.net/manual/en/class.datetime.php
2. Carbon object: https://carbon.nesbot.com/docs/
3. String datetime format
4. Integer timestamp

public function resolver(): array
{
    return [
        'id'        => 42,
        'some'      => 'Example',
        'createdAt' => '2018-04-28T17:55:27+00:00', // Yesterday
    ];
}

The request might look like this:

{
    example {
        id
        some
        a: createdAt(format: COOKIE)
        b: createdAt(format: HUMAN_READABLE)
    }
}

The response is as follows:

{
    "example": {
        "id": 42,
        "some": "Example",
        "createdAt": "Saturday, 28-Apr-2018 17:55:27 GMT+0000",
        "a": "Saturday, 28-Apr-2018 17:55:27 GMT+0000",
        "b": "4 months ago"
    }
}

Output formats

The return value can correspond to one of the valid formats defined in the CarbonFormat enumeration. In order to specify what date format in the response you want to see - it should be passed as the value of the format argument.

{
    example {
        createdAt(format: COOKIE) 
        # createdAt field date will return in the COOKIE format.
    }
}

Below is a list of valid CarbonFormat enum formats:

• ISO8601 - ISO-8601 date format.

Example: 2005-08-15T15:52:01+00:00 Note: This format is an alias of the RFC 3339 specification: ISO8601: https://www.iso.org/iso-8601-date-and-time-format.html RFC3339: https://www.ietf.org/rfc/rfc3339.txt

• RFC822 - RFC 822 date format.

Example: Mon, 15 Aug 05 15:52:01 +0000

• RFC850 - RFC 850 date format.

Example: Monday, 15-Aug-05 15:52:01 UTC

• RFC1036 - RFC 1036 date format.

Example: Mon, 15 Aug 05 15:52:01 +0000

• RFC1123 - RFC 1123 date format.

Example: Mon, 15 Aug 2005 15:52:01 +0000

• RFC2822 - RFC 2822 date format.

Example: Mon, 15 Aug 2005 15:52:01 +0000

• RFC3339 - RFC 3339 date format.

Example: 2005-08-15T15:52:01+00:00 Note: This format is an alias of the ISO-8601 specification: RFC3339: https://www.ietf.org/rfc/rfc3339.txt ISO8601: https://www.iso.org/iso-8601-date-and-time-format.html

• RFC3339_EXTENDED - RFC 3339 date format. In contrast to the usual RFC3339 additionally contains milliseconds.

Example: 2005-08-15T15:52:01.000+00:00

• RFC7231 - RFC 7231 date format.

Example: Mon, 15 Aug 2005 15:52:01 GMT

• COOKIE - HTTP Cookies date format.

Example: Monday, 15-Aug-2005 15:52:01 UTC

• DATE_TIME - Simple DateTime format.

Example: 2005-08-15 15:52:01

• DATE - Simple Date format.

Example: 2005-08-15

• TIME - Simple Time format.

Example: 15:52:01

• RSS - RSS date format.

Example: Mon, 15 Aug 2005 15:52:01 +0000

• W3C - World Wide Web Consortium date format.

Example: 2005-08-15T15:52:01+00:00

• HUMAN_READABLE - Human readable string.

Example: 2 days ago

Input

A scalar Carbon type can be passed as an argument to any field. In this case it will be coerced into Carbon PHP object.

# Definition
type Example {
    field(arg: Carbon!): String
}

// Resolver
// Note: "$arg" argument definition similar with "$input->get('arg')"
public function handle(\DateTimeInterface $arg)
{
    return $arg->format(\DateTime::RFC3339);
}

# Query
{
    field(arg: "now")
}

{
    "field": "2018-04-29T17:55:27+00:00"
}

Input formats

As the admissible input values, the following formats are allowed:

• Time Formats
• Date Formats
• Compound Formats
• Relative Formats