[6.x] Time field enhancements (#13799)

* add format_time modifier

* add augment_format option to time fieldtype

* pint

Author: jasonvarga

lang/en/fieldtypes.php

@@ -201,6 +201,7 @@
     'text.config.prepend' => 'Add text before (to the left of) the input.',
     'text.title' => 'Text',
     'textarea.title' => 'Textarea',
+    'time.config.augment_format' => 'Optionally format the output using [PHP date format](https://www.php.net/manual/en/datetime.format.php) syntax. e.g. `g:ia`.',
     'time.config.seconds_enabled' => 'Show seconds in the timepicker.',
     'time.title' => 'Time',
     'toggle.config.inline_label' => 'Set an inline label to be shown beside the toggle input.',

src/Fieldtypes/Time.php

@@ -2,6 +2,7 @@
 
 namespace Statamic\Fieldtypes;
 
+use Illuminate\Support\Facades\Date;
 use Statamic\Fields\Fieldtype;
 use Statamic\Rules\TimeFieldtype as ValidationRule;
 
@@ -31,11 +32,25 @@ protected function configFieldItems(): array
                         'instructions' => __('statamic::messages.fields_default_instructions'),
                         'type' => 'text',
                     ],
+                    'augment_format' => [
+                        'display' => __('Augment Format'),
+                        'instructions' => __('statamic::fieldtypes.time.config.augment_format'),
+                        'type' => 'text',
+                    ],
                 ],
             ],
         ];
     }
 
+    public function augment($value)
+    {
+        if (! $value || ! $this->config('augment_format')) {
+            return $value;
+        }
+
+        return Date::parse($value)->format($this->config('augment_format'));
+    }
+
     public function rules(): array
     {
         return [new ValidationRule($this)];

src/Modifiers/CoreModifiers.php

@@ -821,6 +821,20 @@ public function formatTranslated($value, $params)
         return $this->carbon($value)->translatedFormat(Arr::get($params, 0));
     }
 
+    /**
+     * Format a time string without timezone conversion.
+     *
+     * @return string
+     */
+    public function formatTime($value, $params)
+    {
+        if (! $value) {
+            return $value;
+        }
+
+        return Date::parse($value)->format(Arr::get($params, 0, 'g:ia'));
+    }
+
     /**
      * Format a number with grouped thousands and decimal points.
      *

tests/Fieldtypes/TimeTest.php

@@ -117,6 +117,53 @@ public static function validationProvider()
         ];
     }
 
+    #[Test]
+    #[DataProvider('augmentProvider')]
+    public function it_augments($config, $value, $expected)
+    {
+        $this->assertSame($expected, $this->fieldtype($config)->augment($value));
+    }
+
+    public static function augmentProvider()
+    {
+        return [
+            'null without format' => [
+                [],
+                null,
+                null,
+            ],
+            'null with format' => [
+                ['augment_format' => 'g:ia'],
+                null,
+                null,
+            ],
+            'time without format returns as-is' => [
+                [],
+                '14:30',
+                '14:30',
+            ],
+            'time with format' => [
+                ['augment_format' => 'g:ia'],
+                '14:30',
+                '2:30pm',
+            ],
+            'time with seconds and format' => [
+                ['augment_format' => 'g:i:sa'],
+                '14:30:45',
+                '2:30:45pm',
+            ],
+        ];
+    }
+
+    #[Test]
+    public function it_does_not_apply_timezone_when_augmenting()
+    {
+        config()->set('statamic.system.display_timezone', 'Europe/Berlin');
+        config()->set('statamic.system.localize_dates_in_modifiers', true);
+
+        $this->assertSame('2:30pm', $this->fieldtype(['augment_format' => 'g:ia'])->augment('14:30'));
+    }
+
     public function fieldtype($config = [])
     {
         $field = new Field('test', array_replace([

tests/Modifiers/FormatTimeTest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Tests\Modifiers;
+
+use PHPUnit\Framework\Attributes\Test;
+use Statamic\Modifiers\Modify;
+use Tests\TestCase;
+
+class FormatTimeTest extends TestCase
+{
+    #[Test]
+    public function it_formats_time_with_default_format()
+    {
+        $this->assertSame('2:45pm', $this->modify('14:45'));
+    }
+
+    #[Test]
+    public function it_formats_time_with_custom_format()
+    {
+        $this->assertSame('2:45 PM', $this->modify('14:45', 'g:i A'));
+    }
+
+    #[Test]
+    public function it_formats_time_with_seconds()
+    {
+        $this->assertSame('2:45:30pm', $this->modify('14:45:30', 'g:i:sa'));
+    }
+
+    #[Test]
+    public function it_does_not_apply_timezone_conversion()
+    {
+        config()->set('statamic.system.display_timezone', 'Europe/Berlin');
+        config()->set('statamic.system.localize_dates_in_modifiers', true);
+
+        $this->assertSame('2:45pm', $this->modify('14:45', 'g:ia'));
+    }
+
+    #[Test]
+    public function it_returns_null_for_null_value()
+    {
+        $this->assertNull($this->modify(null, 'g:ia'));
+    }
+
+    #[Test]
+    public function it_returns_empty_string_for_empty_string_value()
+    {
+        $this->assertSame('', $this->modify('', 'g:ia'));
+    }
+
+    public function modify($value, $format = null)
+    {
+        return Modify::value($value)->formatTime($format)->fetch();
+    }
+}