docs: adding documentation

trickeyone · Oct 23, 2023 · cc7e1b0 · cc7e1b0
1 parent ac17b70
commit cc7e1b0
Show file tree

Hide file tree

Showing 8 changed files with 307 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -6,8 +6,34 @@ Epoch
 [![Test Coverage](https://codeclimate.com/github/trickeyone/epoch/badges/coverage.svg)](https://codeclimate.com/github/trickeyone/epoch/coverage)
 [![Code Climate](https://codeclimate.com/github/trickeyone/epoch/badges/gpa.svg)](https://codeclimate.com/github/trickeyone/epoch)
 
+## Installation
+```shell
+$ composer require trickeyone/epoch
+```
+
 ## Usage
-* [Creation](docs/creation.md)
+- [Creation](docs/creation/01-creation.md)
+  - [Now](docs/creation/01-creation.md#now)
+  - [Create from `DateTimeInterface`](docs/creation/01-creation.md#datetimeinterface)
+  - [String + Format](docs/creation/01-creation.md#strings)
+  - [Unix Timestamp](docs/creation/01-creation.md#unix-timestamp)
+  - [Create from year, month, day, etc.](docs/creation/01-creation.md#specific-values)
+  - [Cloning](docs/creation/01-creation.md#cloning)
+- [Get/Set](docs/01-get-set.md)
+  - [Microseconds](docs/01-get-set.md#microseconds)
+  - [Milliseconds](docs/01-get-set.md#milliseconds)
+  - [Seconds](docs/01-get-set.md#seconds)
+  - [Minutes](docs/01-get-set.md#minutes)
+  - [Hours](docs/01-get-set.md#hours)
+  - [Day of the Month](docs/01-get-set.md#day-of-the-month)
+  - [Day of the Week](docs/01-get-set.md#day-of-the-week)
+  - [ISO Day of the Week](docs/01-get-set.md#iso-day-of-the-week)
+  - [Day of the Year](docs/01-get-set.md#day-of-the-year)
+  - [Week of the Year](docs/01-get-set.md#week-of-the-year)
+  - [Month](docs/01-get-set.md#month)
+  - [Quarter](docs/01-get-set.md#quarter)
+  - [Year](docs/01-get-set.md#year)
+- [Manipulate](docs/02-manipulate.md)
 
 Requirements
 -----------

diff --git a/docs/01-get-set.md b/docs/01-get-set.md
@@ -0,0 +1,155 @@
+Get + Set
+=========
+
+All setter methods are fluent.
+```php
+\Epoch\Epoch::create()->setMinutes(integer)->minutes(); // returns the value passed to setMinutes()
+```
+
+## Microseconds
+```php
+\Epoch\Epoch::create()->microseconds(); // integer
+\Epoch\Epoch::create()->setMicroseconds(integer);
+```
+
+Get or set the milliseconds.
+
+Accepts an integer from 0 to 999999. If the range is exceeded, it is limited to the max value of 999999.
+
+## Milliseconds
+```php
+\Epoch\Epoch::create()->milliseconds(); // integer
+\Epoch\Epoch::create()->setMilliseconds(integer);
+```
+
+Get or set the milliseconds.
+
+Accepts an integer from 0 to 999. If the range is exceeded, it is limited to the max value of 999.
+
+## Seconds
+```php
+\Epoch\Epoch::create()->seconds(); // integer
+\Epoch\Epoch::create()->setSeconds(integer);
+```
+
+Get or set the seconds.
+
+Accepts an integer from 0 to 59. If the range is exceeded, it is limited to the max value of 59.
+
+## Minutes
+```php
+\Epoch\Epoch::create()->minutes(); // integer
+\Epoch\Epoch::create()->setMinutes(integer);
+```
+
+Get or set the minutes.
+
+Accepts an integer from 0 to 59. If the range is exceeded, it is limited to the max value of 59.
+
+## Hours
+```php
+\Epoch\Epoch::create()->hours(); // integer
+\Epoch\Epoch::create()->setHours(integer);
+```
+
+Get or set the hours;
+
+Accepts an integer from 0 to 23. If the range is exceeded, it is limited to the max value of 23.
+
+## Day of the Month
+```php
+\Epoch\Epoch::create()->day(); // integer
+\Epoch\Epoch::create()->setDay(integer);
+```
+
+Get or set the day of the month.
+
+Accepts an integer from 1 to 31. If the range is exceeded, it is limited to the max number of days in the month.
+
+**Note:** If you chain multiple actions to construct a date, you should start from a year, then month,
+then day, etc. If done otherwise, you may encounter unexpected results. i.e. If the day is first
+set to 31, then month set to a month that has less than 31 days, the date will bubble over into the
+next month (see [month](#month) for more details).
+
+## Day of the Week
+```php
+\Epoch\Epoch::create()->weekday(); // integer
+\Epoch\Epoch::create()->setWeekday(integer);
+```
+
+Get or set the day of the week.
+
+Accepts an integer from 0 to 6 (Sunday is 0 and Saturday is 6).
+
+If the value given is from 0-6, the weekday will remain in the current week.
+
+If the value exceeds the range, it will bubble to another week.
+```php
+\Epoch\Epoch::create()->setWeekday(-7); // last Sunday
+\Epoch\Epoch::create()->setWeekday(0); // this Sunday
+\Epoch\Epoch::create()->setWeekday(7); // next Sunday
+\Epoch\Epoch::create()->setWeekday(10); // next Wednesday
+```
+
+## ISO Day of the Week
+```php
+\Epoch\Epoch::create()->isoWeekday(); // integer
+\Epoch\Epoch::create()->setIsoWeekday(integer);
+```
+
+Get or set the [ISO day of the week](https://en.wikipedia.org/wiki/ISO_week_date) with 1 being Monday and 7 being Sunday.
+
+As with [Day of Week](#day-of-week), if the value exceeds the range, it will bubble to another week.
+
+## Day of the Year
+```php
+\Epoch\Epoch::create()->dayOfYear(); // integer
+```
+
+Gets the day of the year (1-366).
+
+## Week of the Year
+```php
+\Epoch\Epoch::create()->weekOfYear(); // integer
+```
+
+Gets the [ISO week of the year](https://en.wikipedia.org/wiki/ISO_week_date).
+
+## Month
+```php
+\Epoch\Epoch::create()->month(); // integer
+\Epoch\Epoch::create()->setMonth(integer);
+```
+
+Get or set the month.
+
+Accepts an integer from 1 to 12. If the value exceeds the range, it will bubble to the year.
+
+If the month is changed and the new month does not have enough days to keep the current day of
+the month, it will bubble to the next month.
+
+## Quarter
+```php
+\Epoch\Epoch::create()->quarter(); // integer
+\Epoch\Epoch::create()->setQuarter(integer);
+```
+
+Get or set the quarter (1 to 4).
+
+When setting the quarter, if the value exceeds the bound, it will be forced to the min/max of the bounds.
+i.e.
+```php
+\Epoch\Epoch::fromString('2013-01-01T00:00:00.000')->setQuarter(-1); // Quarter will be 1
+\Epoch\Epoch::fromString('2013-06-01T00:00:00.000')->setQuarter(-1); // Quarter will be 1
+\Epoch\Epoch::fromString('2013-06-01T00:00:00.000')->setQuarter(5); // Quarter will be 4
+```
+
+## Year
+```php
+\Epoch\Epoch::create()->year(); // integer
+\Epoch\Epoch::create()->setYear(integer);
+```
+
+Get or set the year.
+
+Accepts integers from `-PHP_INT_MAX` to `PHP_INT_MAX`
diff --git a/docs/02-manipulate.md b/docs/02-manipulate.md
@@ -0,0 +1,13 @@
+Manipulate
+==========
+
+Easily manipulate a date with the convenient fluent methods provided by Epoch.
+
+If you want to copy an instance and manipulate it, please see [cloning](creation/01-creation.md#cloning) for more information.
+
+## Add
+```php
+\Epoch\Epoch::create()->add(integer, \Epoch\Units);
+```
+
+Mutates the date by adding time.
diff --git a/docs/creation.md b/docs/creation.md
diff --git a/docs/creation/01-creation.md b/docs/creation/01-creation.md
@@ -0,0 +1,62 @@
+Creation
+========
+
+### Time Zones
+All creation methods that accept a `DateTimeZone` parameter, default to the system/PHP default timezone if no value is provided.
+
+## Now
+Create a fresh instance for "now". Optionally pass a `DateTimeZone` to set for the newly created instance.
+```php
+\Epoch\Epoch::create(?\DateTimeZone $timeZone): Epoch
+```
+```php
+$epoch = \Epoch\Epoch::create(); // Create an instance for the current date/time (aka "now")
+```
+
+## `DateTimeInterface`
+Create from `DateTimeInterface` object.
+The passed object is treated as immutable and a new instance is created internally.
+```php
+\Epoch\Epoch::fromDateTimeInterface(\DateTimeInterface $dateTime): \Epoch\Epoch
+```
+```php
+$myDate = new DateTime('2023-03-31T13:24:56Z');
+$epoch = \Epoch\Epoch::fromDateTimeInterface($myDate);
+```
+
+## [Strings](02-string-format.md)
+Create from string and date-time format.
+```php
+$epoch = \Epoch\Epoch::fromString('2023-03-31T13:24:56Z'); // Create from default ATOM date-time format
+$epoch = \Epoch\Epoch::fromString('March 31, 2023', 'F j, Y'); // Create from provided date-time format
+```
+
+## Unix Timestamp
+Create from Unix timestamp.
+```php
+\Epoch\Epoch::fromTimestamp(int $timestamp, ?DateTimeZone $timeZone): \Epoch\Epoch
+```
+```php
+$epoch = \Epoch\Epoch::fromTimestamp(1680269096);
+```
+
+## [Specific Values](03-specific-values.md)
+Create from specific values (i.e. year, month, day, hour, etc.).
+```php
+$epoch = \Epoch\Epoch::from(2023);
+echo (string)$epoch; // Echos "2023-01-01T00:00:00+00:00"
+$epoch = \Epoch\Epoch::from(2023, 3, 31);
+echo (string)$epoch; // Echos "2023-03-31T00:00:00+00:00"
+```
+
+## Cloning
+All Epochs are mutable. If you want to clone an instance, you can do so by using PHP's native `clone` keyword 
+or by one of the fluent methods provided by Epoch.
+
+```php
+$original = \Epoch\Epoch::create();
+$copy1 = clone $original; // creates a new instance with its own date and will not affect the original
+$copy2 = $original->clone(); // uses the same methodology as the above, only allows for fluent method calls on the new instance
+
+$original->clone()->add(1, \Epoch\Units::DAYS); // adds 1 day to the new instance, but will not affect $original
+```
diff --git a/docs/creation/02-string-format.md b/docs/creation/02-string-format.md
@@ -0,0 +1,30 @@
+String + Format
+===============
+
+Create a new instance from a string and the provided date-time format. The date-time format is 
+required to properly parse the date-time string.
+
+```php
+\Epoch\Epoch::fromString(string $dateString, string $format = \DateTimeInterface::ATOM, ?\DateTimeZone $timeZone): \Epoch\Epoch
+```
+
+| Parameter     |                                                                                                                                                                                                                                                                                  |
+|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `$dateString` | Date-time string<br>Type: `string`                                                                                                                                                                                                                                               |
+| `$format`     | Date-time format used to parse `$dateString`. Defaults to `DateTimeInterface::ATOM`<br>Type: `string`<br>See DateTime [format](https://www.php.net/manual/en/datetimeimmutable.createfromformat.php#datetimeimmutable.createfromformat.parameters) for acceptable values to use. |
+| `$timeZone`   | Optional. Timezone to use for the date. See [Time Zones](01-creation.md#time-zones) for information.                                                                                                                                                                             |
+
+
+By default, the `DateTimeInterace::ATOM` format will be used.
+```php
+$epoch = \Epoch\Epoch::fromString('2023-03-31T13:24:56Z');
+```
+
+Otherwise you can provide any format that is supposed by `DateTime::createFromFormat()`.
+```php
+$epoch = \Epoch\Epoch::fromString('12-25-1995', 'm-d-Y');
+$epoch = \Epoch\Epoch::fromString('19951225', 'Ymd');
+$epoch = \Epoch\Epoch::fromString('24/12/2019 09:15:00', 'd/m/Y H:i:s');
+```
+
+If an invalid date and/or format are provided, then a `DateCreationException` is thrown.
diff --git a/docs/creation/03-specific-values.md b/docs/creation/03-specific-values.md
@@ -0,0 +1,18 @@
+Specific Values
+===============
+
+Create a new instance from a specific values.
+```php
+\Epoch\Epoch::from(int $year, ?int $month, ?int $day, ?int $hours, ?int $minutes, ?int $seconds, ?float $milliseconds, ?\DateTimeZone $timeZone)
+```
+
+| Parameter       |                                                                                                                                    |
+|-----------------|------------------------------------------------------------------------------------------------------------------------------------|
+| `$year`         | Required. The year of the date. This is the minimum required parameter.<br>Type: `integer`                                         |
+| `$month`        | Optional. The month of the date (1-12).<br>Type: `integer`                                                                         |
+| `$day`          | Optional. The day of the date (Starting from 1).<br>Type: `integer`                                                                |
+| `$hours`        | Optional. The hour of the date (0-23).<br>Type: `integer`                                                                          |
+| `$minutes`      | Optional. The minute of the date (0-59).<br>Type: `integer`                                                                        |
+| `$seconds`      | Optional. The second of the date (0-59).<br>Type: `integer`                                                                        |
+| `$milliseconds` | Optional. The millisecond of the date, this does accept fractional values (0-999.999).<br>Type: `float`                            |              
+| `$timeZone`     | Optional. Timezone to use for the date. See [Time Zones](01-creation.md#time-zones) for information.<br>Type: `DateTimeZone` |
diff --git a/src/Trait/GetSetTrait.php b/src/Trait/GetSetTrait.php
@@ -70,8 +70,7 @@ public function month(): int
      */
     public function setMonth(int|string $value): Epoch
     {
-        $value = Utils::boundValue($value, 1, 12);
-        $this->date->setDate($this->year(), $value, $this->day());
+        $this->date->setDate($this->year(), (int)$value, $this->day());
 
         return $this;
     }
@@ -101,8 +100,7 @@ public function day(): int
 
     public function setDay(int|string $value): Epoch
     {
-        $value = Utils::boundValue($value, 1, Utils::daysInMonths($this->year(), $this->month()));
-        $this->date->setDate($this->year(), $this->month(), $value);
+        $this->date->setDate($this->year(), $this->month(), (int)$value);
 
         return $this;
     }