Added begin of casting

Author: toonvandenbos

README.md

@@ -1,6 +1,6 @@
 # Laravel Timezones
 
-## Usage
+## Getting started
 
 All database dates should be stored using the `app.timezone` config setting. We highly suggest keeping it as `UTC` since it's a global standard for dates storage.
 
@@ -12,4 +12,46 @@ Useful when the app's timezone should be set by ther user's settings.
 
 ### 2. Using a Service Provider
 
-Useful when the app's timezone should be set by the application itself.
+Useful when the app's timezone should be set by the application itself.
+
+## Usage
+
+Once everything's setup, the easiest way to manipulate dates configured with the app's current timezone is to use the `TimezonedDatetime` or `ImmutableTimezonedDatetime` cast types on your models:
+
+```php
+/**
+ * The attributes that should be cast.
+ *
+ * @var array
+ */
+protected $casts = [
+    'published_at' => \Whitecube\LaravelTimezones\Casts\TimezonedDatetime::class,
+    'birthday' => \Whitecube\LaravelTimezones\Casts\ImmutableTimezonedDatetime::class . ':Y-m-d',
+];
+```
+
+In other scenarios, use the `Timezone`'s static methods directly for conversion:
+
+```php
+use Carbon\Carbon;
+use Whitecube\LaravelTimezones\Timezone;
+
+// Get the current date configured with the current timezone:
+$now = Timezone::now();
+
+// Create a date using the current timezone:
+$date = Timezone::date('2023-01-01 00:00:00');
+// Alternatively, set the timezone manually on a Carbon instance:
+$date = new Carbon('2023-01-01 00:00:00', Timezone::current());
+
+
+// Convert a date to the current timezone:
+$date = Timezone::date(new Carbon('2023-01-01 00:00:00', 'UTC'));
+// Alternatively, set the application timezone yourself:
+$date = (new Carbon('2023-01-01 00:00:00', 'UTC'))->setTimezone(Timezone::current());
+
+// Convert a date to the storage timezone:
+$date = Timezone::store(new Carbon('2023-01-01 00:00:00', 'Europe/Brussels'));
+// Alternatively, set the storage timezone yourself:
+$date = (new Carbon('2023-01-01 00:00:00', 'Europe/Brussels'))->setTimezone(Timezone::storage());
+```

src/Casts/ImmutableTimezonedDatetime.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Whitecube\LaravelTimezones\Casts;
+
+class ImmutableTimezonedDatetime extends TimezonedDatetime
+{
+    /**
+     * Cast the given value.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return array
+     */
+    public function get($model, $key, $value, $attributes)
+    {
+        return parent::get($model, $key, $value, $attributes)->toImmutable();
+    }
+}

src/Casts/TimezonedDatetime.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Whitecube\LaravelTimezones\Casts;
+
+use Whitecube\LaravelTimezones\Timezone;
+use Illuminate\Support\Facades\Date;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+
+class TimezonedDatetime implements CastsAttributes
+{
+    /**
+     * A developer-specific format to use for string parsing
+     *
+     * @var null|string
+     */
+    protected ?string $format;
+
+    /**
+     * Create a new casting instance.
+     *
+     * @param null|string $format
+     * @return void
+     */
+    public function __construct(?string $format = null)
+    {
+        $this->format = $format;
+    }
+
+    /**
+     * Cast the given value.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return \Carbon\CarbonInterface
+     */
+    public function get($model, $key, $value, $attributes)
+    {
+        return Timezone::date($value, fn($raw, $tz) => $this->asDateTime($raw, $tz, $model));
+    }
+ 
+    /**
+     * Prepare the given value for storage.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return string
+     */
+    public function set($model, $key, $value, $attributes)
+    {
+        return Timezone::store($value, fn($raw, $tz) => $this->asDateTime($raw, $tz, $model))
+            ->format($this->format ?? $model->getDateFormat());
+    }
+ 
+    /**
+     * Create a new date value from raw material
+     *
+     * @param  mixed  $value
+     * @param  Carbon\CarbonTimeZone  $timezone
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @return \Carbon\CarbonInterface
+     */
+    public function asDateTime($value, $timezone, $model)
+    {
+        return Date::createFromFormat(
+            $this->format ?? $model->getDateFormat(),
+            $value,
+            $timezone,
+        );
+    }
+}

src/Timezone.php

@@ -4,6 +4,7 @@
 
 use Carbon\CarbonTimeZone;
 use Carbon\CarbonInterface;
+use Illuminate\Support\Facades\Date;
 
 class Timezone
 {
@@ -20,6 +21,17 @@ class Timezone
      */
     protected CarbonTimeZone $storage;
 
+    public function __construct(string $default)
+    {
+        $this->setStorage($default);
+        $this->setCurrent($default);
+    }
+
+    public static function instance(): static
+    {
+        return app()->make(self::class);
+    }
+
     public static function set($timezone = null)
     {
         static::instance()->setCurrent($timezone);
@@ -35,15 +47,27 @@ public static function storage(): CarbonTimeZone
         return static::instance()->getStorage();
     }
 
-    public function instance(): static
+    public static function now(): CarbonInterface
     {
-        return app()->make(self::class);
+        return static::instance()->convertToCurrent(now());
     }
 
-    public function __construct(string $default)
+    public static function date($value, callable $maker = null): CarbonInterface
     {
-        $this->setStorage($default);
-        $this->setCurrent($default);
+        $instance = static::instance();
+
+        return $instance->convertToCurrent(
+            $instance->makeDateWithStorage($value, $maker)
+        );
+    }
+
+    public static function store($value, callable $maker = null): CarbonInterface
+    {
+        $instance = static::instance();
+
+        return $instance->convertToStorage(
+            $instance->makeDateWithCurrent($value, $maker)
+        );
     }
 
     public function setCurrent($timezone)
@@ -76,6 +100,27 @@ public function convertToStorage(CarbonInterface $date): CarbonInterface
         return $date->copy()->setTimezone($this->getStorage());
     }
 
+    public function makeDateWithCurrent($value, callable $maker = null): CarbonInterface
+    {
+        return is_a($value, CarbonInterface::class)
+            ? $this->convertToCurrent($value)
+            : $this->makeDate($value, $this->getCurrent(), $maker);
+    }
+
+    public function makeDateWithStorage($value, callable $maker = null): CarbonInterface
+    {
+        return is_a($value, CarbonInterface::class)
+            ? $this->convertToStorage($value)
+            : $this->makeDate($value, $this->getStorage(), $maker);
+    }
+
+    protected function makeDate($value, CarbonTimeZone $timezone, callable $maker = null): CarbonInterface
+    {
+        return ($maker)
+            ? call_user_func($maker, $value, $timezone)
+            : Date::create($value, $timezone);
+    }
+
     protected function makeTimezone($value): CarbonTimeZone
     {
         if(! is_a($value, CarbonTimeZone::class)) {

tests/TimezoneSingletonTest.php

@@ -1,7 +1,9 @@
 <?php
 
 use Carbon\Carbon;
+use Carbon\CarbonImmutable;
 use Carbon\CarbonTimeZone;
+use Carbon\CarbonInterface;
 use Whitecube\LaravelTimezones\Timezone;
 
 it('can create a default Timezone instance and access its current & storage settings', function() {
@@ -32,3 +34,36 @@
     expect($instance->convertToCurrent($date)->getTimezone()->getName() ?? null)->toBe('Europe/Brussels');
     expect($date->getTimezone()->getName() ?? null)->toBe(date_default_timezone_get());
 });
+
+it('can create date with current timezone', function() {
+    $instance = new Timezone('UTC');
+    $instance->setCurrent('Europe/Brussels');
+
+    $string = $instance->makeDateWithCurrent('1993-03-16 03:00:00');
+    $date = $instance->makeDateWithCurrent(new Carbon('1993-03-16 03:00:00', 'UTC'));
+    $custom = $instance->makeDateWithCurrent('1993-03-16 03:00:00', fn($value, $tz) => new CarbonImmutable($value, $tz));
+
+    expect($string)->toBeInstanceOf(CarbonInterface::class);
+    expect($string->getTimezone()->getName() ?? null)->toBe('Europe/Brussels');
+    expect($date)->toBeInstanceOf(CarbonInterface::class);
+    expect($date->getTimezone()->getName() ?? null)->toBe('Europe/Brussels');
+    expect($custom)->toBeInstanceOf(CarbonImmutable::class);
+    expect($custom->getTimezone()->getName() ?? null)->toBe('Europe/Brussels');
+});
+
+it('can create date with storage timezone', function() {
+    $instance = new Timezone('UTC');
+    $instance->setCurrent('Europe/Brussels');
+
+    $string = $instance->makeDateWithStorage('1993-03-16 03:00:00');
+    $date = $instance->makeDateWithStorage(new Carbon('1993-03-16 03:00:00', 'Europe/Brussels'));
+    $custom = $instance->makeDateWithStorage('1993-03-16 03:00:00', fn($value, $tz) => new CarbonImmutable($value, $tz));
+
+    expect($string)->toBeInstanceOf(CarbonInterface::class);
+    expect($string->getTimezone()->getName() ?? null)->toBe('UTC');
+    expect($date)->toBeInstanceOf(CarbonInterface::class);
+    expect($date->getTimezone()->getName() ?? null)->toBe('UTC');
+    expect($custom)->toBeInstanceOf(CarbonImmutable::class);
+    expect($custom->getTimezone()->getName() ?? null)->toBe('UTC');
+});
+