Fincallorca DateTimeBundle

The symfony DateTimeBundle provides a couple of functionalities to get rid of the current lack of php, symfony and doctrine date management support:

Usage of new DateTime/DateTimeImmutable methods.
Access Symfony's http request time by method - not by global $_SERVER property. See class Request.
Save datetime values in database always in the same timezone.
Switch between different preconfigured timezone settings easily (available configs: server, database and client).
Use the doctrine's column type date as primary key.
A new central point for \DateTimeZone object caching.

All these functionalities are optional. You can install this bundle without using any of this features or with using only one or a few of them.

Requirements
Integration
Usage
Deprecated: Symfony v3
Credits

Requirements

The usage of PHP v7.3 is obligatory. It is strongly recommend to start with Symfony v4.

If you want to use the library in Symfony v3 (and PHP _v5.*) please use the release version 0.*.

Integration

composer require fincallorca/datetimebundle "^1.0"

Usage

To use the new datetime method replace the instantiation of your existing \DateTime/\DateTimeImmutable objects to the provided \Fincallorca\DateTimeBundle\Component\DateTime/\Fincallorca\DateTimeBundle\Component\DateTimeImmutable classes.

These classes provide additional useful datetime methods like

$dateTime->duplicate()
$dateTime->addHours()
$dateTime->toEndOfDay()
etc.

Please visit prokki/ext-datetime to get more information of all new features.

Furthermore the datetime classes support all preconfigured timezones. Use the methods

$dateTime->toServerDateTime()
$dateTime->toDatabaseDateTime()
$dateTime->toClientDateTime()

to switch fast between the timezones. To see how to configure the timezones take a look chapter Configure Timezones.

Enable Support in Class Request

The current symfony's request class does not return the request's time value properly. Especially if need to access the request's time often the change of the Request object will help you to save a lot of time.

To use the \Fincallorca\DateTimeBundle\Component\HttpFoundation\Request class in your controllers replace the current request class by the new one in your public/index.php or in all public/app*.php files (Symfony v3.*).

// comment follwing line
//use Symfony\Component\HttpFoundation\Request;

// and add the new request class
use Fincallorca\DateTimeBundle\Component\HttpFoundation\Request;

Additionally do the same in all controllers or at least in these controllers you want to access the request's time.

Afterwards you can access the request's time method specified in the RequestDateTimeInterface.

Example:

use Fincallorca\DateTimeBundle\Component\HttpFoundation\Request;

class MyController extends Controller

    /**
     * @param Request $request
     *
     * @return Response
     */
    public function indexAction(Request $request)
    {
        // get the request's date time
        $requestDateTime = $request->getDateTime();
    }

Configure Timezones

The possibilities

to save all datetimes in one common timezone and
to initialize a general client timezone

are both optional.

To configure at least one of both you need to create a new file config/packages/datetime.yml and insert following content:

datetime:
  database: ~  
  client: ~

Configure Database Timezone

To save all datetime objects into the database with one common timezone only (i.e. with UTC), modify the configuration variable database:

datetime:
  # feel free to change the timezone name to your needs!
  database: "UTC" 
  client: ~

⚠️ But please take care that

all datetimes read from the database are initialized with the new database timezone and
all datetimes saved into the database are converted into the given timezone before saving.

Configure Default Client Timezone

You can set up a client's default timezone by simply changing the variable client in the configuration:

datetime:
  database: ~
  # both variables (database and client) are optional...
  # if you do not specify the timezones, all times will be saved with your default server time  
  client: "Europe/London"

In opposite to the configured database timezone it is possible to change the default client's timezone during the runtime by calling Fincallorca\DateTimeBundle\Component\DateTimeKernel::setTimeZoneClient()

Use Timezone Caching

If you are working intensively with timezones, you might want to avoid instantiating timezone object multiple times. Thus the Fincallorca\DateTimeBundle\Component\DateTimeKernel class provides the static method getTimeZoneByName() to work with cached timezone.

A call of DateTimeKernel::getTimeZoneByName() with the same passed timezone name for multiple times will always return the same timezone object.

To be sure to use the timezone caching, change the instantiations of all your \DateTimeZone objects from new \DateTimeZone($STRING) to DateTimeKernel::getTimeZoneByName($STRING).

Deprecated: Symfony v3

Install the bundle via composer:

composer require fincallorca/datetimebundle "^0.0"

Extend your AppKernel.php with the new bundle:

class Kernel extends \Symfony\Component\HttpKernel\Kernel
{
    public function registerBundles()
    {
        return [
            // [...]
            new Fincallorca\DateTimeBundle\DateTimeBundle(),
        ];
    }
    
    // [...]
}

Configure the bundle by adding the timezone configuration to your config.yml

datetime:
    database: "UTC"
    client: "Europe/London"

Credits

A big thank you to prokki/ext-datetime for the extension of the \DateTime/\DateTimeImmutable classes.

Fincallorca/DateTimeBundle