Merge pull request #10 from edwinvdpol/feature/consistent-docblocks

Consistent docblocks

Author: toonvandenbos

src/Casts/ImmutableTimezonedDatetime.php

@@ -2,18 +2,14 @@
 
 namespace Whitecube\LaravelTimezones\Casts;
 
+use Illuminate\Database\Eloquent\Model;
+
 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)
+    public function get(Model $model, string $key, mixed $value, array $attributes)
     {
         if($date = parent::get($model, $key, $value, $attributes)) {
             return $date->toImmutable();

src/Casts/TimezonedDatetime.php

@@ -15,17 +15,12 @@
 class TimezonedDatetime implements CastsAttributes
 {
     /**
-     * A developer-specific format to use for string parsing
-     *
-     * @var null|string
+     * A developer-specific format to use for string parsing.
      */
     protected ?string $format;
 
     /**
      * Create a new casting instance.
-     *
-     * @param null|string $format
-     * @return void
      */
     public function __construct(?string $format = null)
     {
@@ -35,10 +30,6 @@ public function __construct(?string $format = null)
     /**
      * 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 $model, string $key, mixed $value, array $attributes)
@@ -50,19 +41,15 @@ public function get(Model $model, string $key, mixed $value, array $attributes)
         if ($this->isTimestamp($model, $key)) {
             $value = Carbon::parse($value)->format($this->format ?? $model->getDateFormat());
         }
-        
+
         $original = Timezone::store($value, fn($raw, $tz) => $this->asDateTime($raw, $tz, $model));
 
         return Timezone::date($original);
     }
- 
+
     /**
      * 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 $model, string $key, mixed $value, array $attributes)
@@ -81,24 +68,15 @@ public function set(Model $model, string $key, mixed $value, array $attributes)
     }
 
     /**
-     * Check if the given key is part of the model's known timestamps
-     * 
-     * @param Model $model 
-     * @param string $key 
-     * @return bool 
+     * Check if the given key is part of the model's known timestamps.
      */
     protected function isTimestamp(Model $model, string $key): bool
     {
         return $model->usesTimestamps() && in_array($key, $model->getDates());
     }
- 
+
     /**
-     * Create a new date value from raw material
-     *
-     * @param  mixed  $value
-     * @param  Carbon\CarbonTimeZone  $timezone
-     * @param  \Illuminate\Database\Eloquent\Model  $model
-     * @return \Carbon\CarbonInterface
+     * Create a new date value from raw material.
      */
     public function asDateTime(mixed $value, CarbonTimeZone $timezone, Model $model): CarbonInterface
     {
@@ -112,15 +90,11 @@ public function asDateTime(mixed $value, CarbonTimeZone $timezone, Model $model)
     }
 
     /**
-     * Check if the provided value contains timezone information
-     * 
-     * @param mixed $value 
-     * @return bool 
+     * Check if the provided value contains timezone information.
      */
     protected function hasTimezone(mixed $value): bool
     {
         return (is_string($value) && array_key_exists('zone', date_parse($value)))
             || (is_a($value, DateTime::class) && $value->getTimezone());
     }
-
 }

src/Concerns/HasTimezonedTimestamps.php

@@ -9,22 +9,16 @@ trait HasTimezonedTimestamps
 {
     /**
      * Determine if the given attribute is a date or date castable.
-     *
-     * @param  string  $key
-     * @return bool
      */
-    protected function isDateAttribute($key): bool
+    protected function isDateAttribute(string $key): bool
     {
         return (in_array($key, $this->getDates(), true) ||
             $this->isDateCastable($key)) &&
             ! $this->hasTimezonedDatetimeCast($key);
     }
 
     /**
-     * Check if key is a timezoned datetime cast
-     * 
-     * @param string $key 
-     * @return bool 
+     * Check if key is a timezoned datetime cast.
      */
     protected function hasTimezonedDatetimeCast(string $key): bool
     {
@@ -37,8 +31,8 @@ protected function hasTimezonedDatetimeCast(string $key): bool
         $castClassName = explode(':', $cast)[0];
 
         return in_array(
-            $castClassName, 
+            $castClassName,
             [TimezonedDatetime::class, ImmutableTimezonedDatetime::class]
         );
     }
-}
+}

src/DatetimeParser.php

@@ -10,16 +10,12 @@ class DatetimeParser
     use HasAttributes;
 
     /**
-     * The model's date storage format
+     * The model's date storage format.
      */
     protected ?string $format;
 
     /**
-     * Parse the value into a carbon instance
-     * 
-     * @param mixed $value 
-     * @param null|string $format 
-     * @return CarbonInterface
+     * Parse the value into a carbon instance.
      */
     public function parse(mixed $value, ?string $format): CarbonInterface
     {
@@ -28,11 +24,8 @@ public function parse(mixed $value, ?string $format): CarbonInterface
         return $this->asDateTime($value);
     }
 
-
     /**
      * Get the format for database stored dates.
-     *
-     * @return string
      */
     public function getDateFormat(): ?string
     {

src/Facades/Timezone.php

@@ -18,8 +18,10 @@ class Timezone extends Facade
 {
     /**
      * Get the registered name of the component.
+     *
+     * @return string
      */
-    public static function getFacadeAccessor(): string
+    public static function getFacadeAccessor()
     {
         return \Whitecube\LaravelTimezones\Timezone::class;
     }

src/ServiceProvider.php

@@ -9,8 +9,6 @@ class ServiceProvider extends BaseServiceProvider
 {
     /**
      * Register any application services.
-     *
-     * @return void
      */
     public function register()
     {

src/Timezone.php

@@ -12,23 +12,16 @@ class Timezone
     use Macroable;
 
     /**
-     * The app's current display & manipulation timezone
-     *
-     * @var \Carbon\CarbonTimeZone
+     * The app's current display & manipulation timezone.
      */
     protected CarbonTimeZone $current;
     /**
-     * The app's current storage timezone
-     *
-     * @var \Carbon\CarbonTimeZone
+     * The app's current storage timezone.
      */
     protected CarbonTimeZone $storage;
 
     /**
      * Create a new singleton instance.
-     *
-     * @param string $default
-     * @return void
      */
     public function __construct(string $default)
     {
@@ -40,9 +33,6 @@ public function __construct(string $default)
      * @alias setCurrent
      *
      * Set the current application timezone.
-     *
-     * @param mixed $timezone
-     * @return void
      */
     public function set(mixed $timezone = null): void
     {
@@ -51,9 +41,6 @@ public function set(mixed $timezone = null): void
 
     /**
      * Set the current application timezone.
-     *
-     * @param mixed $timezone
-     * @return void
      */
     public function setCurrent(mixed $timezone): void
     {
@@ -62,8 +49,6 @@ public function setCurrent(mixed $timezone): void
 
     /**
      * Return the current application timezone.
-     *
-     * @return \Carbon\CarbonTimeZone
      */
     public function current(): CarbonTimeZone
     {
@@ -72,9 +57,6 @@ public function current(): CarbonTimeZone
 
     /**
      * Set the current database timezone.
-     *
-     * @param mixed $timezone
-     * @return void
      */
     public function setStorage(mixed $timezone): void
     {
@@ -83,8 +65,6 @@ public function setStorage(mixed $timezone): void
 
     /**
      * Return the current application timezone.
-     *
-     * @return \Carbon\CarbonTimeZone
      */
     public function storage(): CarbonTimeZone
     {
@@ -93,8 +73,6 @@ public function storage(): CarbonTimeZone
 
     /**
      * Get the current timezoned date.
-     *
-     * @return \Carbon\CarbonInterface
      */
     public function now(): CarbonInterface
     {
@@ -103,10 +81,6 @@ public function now(): CarbonInterface
 
     /**
      * Configure given date for the application's current timezone.
-     *
-     * @param mixed $value
-     * @param null|callable $maker
-     * @return \Carbon\CarbonInterface
      */
     public function date(mixed $value, callable $maker = null): CarbonInterface
     {
@@ -115,10 +89,6 @@ public function date(mixed $value, callable $maker = null): CarbonInterface
 
     /**
      * Configure given date for the database storage timezone.
-     *
-     * @param mixed $value
-     * @param null|callable $maker
-     * @return \Carbon\CarbonInterface
      */
     public function store(mixed $value, callable $maker = null): CarbonInterface
     {
@@ -127,9 +97,6 @@ public function store(mixed $value, callable $maker = null): CarbonInterface
 
     /**
      * Duplicate the given date and shift its timezone to the application's current timezone.
-     *
-     * @param \Carbon\CarbonInterface
-     * @return \Carbon\CarbonInterface
      */
     protected function convertToCurrent(CarbonInterface $date): CarbonInterface
     {
@@ -138,9 +105,6 @@ protected function convertToCurrent(CarbonInterface $date): CarbonInterface
 
     /**
      * Duplicate the given date and shift its timezone to the database's storage timezone.
-     *
-     * @param \Carbon\CarbonInterface
-     * @return \Carbon\CarbonInterface
      */
     protected function convertToStorage(CarbonInterface $date): CarbonInterface
     {
@@ -149,10 +113,6 @@ protected function convertToStorage(CarbonInterface $date): CarbonInterface
 
     /**
      * Create or configure date using the application's current timezone.
-     *
-     * @param mixed $value
-     * @param null|callable $maker
-     * @return \Carbon\CarbonInterface
      */
     protected function makeDateWithCurrent(mixed $value, callable $maker = null): CarbonInterface
     {
@@ -163,10 +123,6 @@ protected function makeDateWithCurrent(mixed $value, callable $maker = null): Ca
 
     /**
      * Create or configure date using the database's storage timezone.
-     *
-     * @param mixed $value
-     * @param null|callable $maker
-     * @return \Carbon\CarbonInterface
      */
     protected function makeDateWithStorage(mixed $value, callable $maker = null): CarbonInterface
     {
@@ -177,11 +133,6 @@ protected function makeDateWithStorage(mixed $value, callable $maker = null): Ca
 
     /**
      * Create a date using the provided timezone.
-     *
-     * @param mixed $value
-     * @param \Carbon\CarbonTimeZone $timezone
-     * @param null|callable $maker
-     * @return \Carbon\CarbonInterface
      */
     protected function makeDate(mixed $value, CarbonTimeZone $timezone, callable $maker = null): CarbonInterface
     {
@@ -192,9 +143,6 @@ protected function makeDate(mixed $value, CarbonTimeZone $timezone, callable $ma
 
     /**
      * Create a Carbon timezone from given value.
-     *
-     * @param mixed $value
-     * @return \Carbon\CarbonTimeZone
      */
     protected function makeTimezone(mixed $value): CarbonTimeZone
     {