add documentation

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+on:
+  push:
+    branches: [master]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,2 +1,3 @@
 composer.lock
 vendor
+.cache

Makefile

@@ -0,0 +1,6 @@
+# This command is intended to be run on your computer
+serve-doc:
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+
+build-doc:
+	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

docs/assets/stylesheets/extra.css

@@ -0,0 +1,113 @@
+@font-face {
+  font-family: "Monaspace Neon";
+  font-weight: normal;
+  font-style: normal;
+  src: url("../fonts/MonaspaceNeon-Regular.woff");
+}
+
+:root {
+  --md-code-font: "Monaspace Neon";
+}
+
+:root {
+  --light-md-code-hl-number-color: #f76d47;
+  --light-md-code-hl-function-color: #6384b9;
+  --light-md-code-hl-operator-color: #39adb5;
+  --light-md-code-hl-constant-color: #7c4dff;
+  --light-md-code-hl-string-color: #9fc06f;
+  --light-md-code-hl-punctuation-color: #39adb5;
+  --light-md-code-hl-keyword-color: #7c4dff;
+  --light-md-code-hl-variable-color: #80cbc4;
+  --light-md-code-hl-comment-color: #ccd7da;
+  --light-md-code-bg-color: #fafafa;
+  --light-md-code-fg-color: #ffb62c;
+  --light-md-code-hl-variable-color: #6384b9;
+  --dark-md-code-hl-number-color: #f78c6c;
+  --dark-md-code-hl-function-color: #82aaff;
+  --dark-md-code-hl-operator-color: #89ddff;
+  --dark-md-code-hl-constant-color: #c792ea;
+  --dark-md-code-hl-string-color: #c3e88d;
+  --dark-md-code-hl-punctuation-color: #89ddff;
+  --dark-md-code-hl-keyword-color: #c792ea;
+  --dark-md-code-hl-variable-color: #e8f9f9;
+  --dark-md-code-hl-comment-color: #546e7a;
+  --dark-md-code-bg-color: #263238;
+  --dark-md-code-fg-color: #ffcb6b;
+  --dark-md-code-hl-variable-color: #82aaff;
+}
+
+@media (prefers-color-scheme: light) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+    --md-code-bg-color: var(--light-md-code-bg-color);
+    --md-code-fg-color: var(--light-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php > * {
+  --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+  --md-code-bg-color: var(--light-md-code-bg-color);
+  --md-code-fg-color: var(--light-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php .na {
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+}
+
+@media (prefers-color-scheme: dark) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+    --md-code-bg-color: var(--dark-md-code-bg-color);
+    --md-code-fg-color: var(--dark-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php > * {
+  --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+  --md-code-bg-color: var(--dark-md-code-bg-color);
+  --md-code-fg-color: var(--dark-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php .na {
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+}

docs/getting-started/clocks.md

@@ -0,0 +1,88 @@
+# Clocks
+
+!!! success "Dependency injection"
+    A `Clock` should be treated as a singleton and instanciated once in your program and then passed as argument everywhere you need it in your program.
+
+## Live
+
+This is the clock you should use in your programs. By default it's set to the [UTC](https://en.wikipedia.org/wiki/UTC%2B00:00) [timezone](timezones.md) (no matter the configuration of your machine).
+
+To access the current time you would do:
+
+```php
+use Innmind\TimeContinuum\{
+    Clock,
+    PointInTime,
+};
+
+$clock = Clock::live();
+$point = $clock->now(); // instance of PointInTime
+echo $point->toString(); // prints something like 2024-11-24T12:34:25+00:00
+```
+
+And to build a [`PointInTime`](points-in-time.md) back from a `string`:
+
+```php
+use Innmind\TimeContinuum\{
+    Clock,
+    Format,
+    PointInTime,
+};
+use Innmind\Immutable\Maybe;
+
+$time = '2024-11-24T12:34:25+00:00';
+
+$clock = Clock::live();
+$at = $clock->at($time, Format::iso8601()); // instance of Maybe<PointInTime>
+$point = $at->match(
+    static fn(PointInTime $point) => $point,
+    static fn() => null,
+);
+```
+
+The `at` method returns a [`Maybe` monad](https://innmind.org/Immutable/structures/maybe/) that may contain a `PointInTime`. This is in case the `#!php $time` variable contains a value that doesn't correspond to the specified format (here `ISO8601`).
+
+This means that the `#!php $point` variable here is an instance of `PointInTime` because the `#!php $time` value is valid. If it's invalid then `#!php $point` is `#!php null`.
+
+## Logger
+
+This clock will create a log everytime you call `#!php ->now()` or `#!php ->at()`.
+
+To build this clock you need another clock (typically a live one) and a [PSR logger](https://packagist.org/packages/psr/log):
+
+```php
+use Innmind\TimeContinuum\Clock;
+use Psr\Log\LoggerInterface;
+
+$clock = Clock::logger(
+    Clock::live(),
+    /* any instance of LoggerInterface (1) */
+);
+```
+
+1. Like [monolog](https://packagist.org/packages/monolog/monolog) for example.
+
+You can then use `#!php $clock` like any other clock.
+
+## Frozen
+
+This clock is only useful when testing your program. It allows to specify the point in time at which your programs run.
+
+This way you can test your program for special scenarii like a leap year, daylight saving time and so on...
+
+```php
+use Innmind\TimeContinuum\{
+    Clock,
+    Format,
+};
+
+$clock = Clock::live()
+    ->at('2024-11-24T12:34:25+00:00', Format::iso8601())
+    ->match(
+        Clock::frozen(...),
+        static fn() => throw new \LogicException('Specify a valid date'),
+    );
+```
+
+??? warning
+    Bear in mind that `#!php $clock->now()` will always return the same object. This means that if your program rely on calculating an [elapsed period](elapsed-period.md) it will always return `#!php 0`. If run in a loop you may end up with an inifinite one.

docs/getting-started/elapsed-period.md

@@ -0,0 +1,31 @@
+# Elapsed period
+
+This is the number of microseconds between two [points in time](points-in-time.md).
+
+```php
+use Innmind\TimeContinuum\Clock;
+
+$clock = Clock::live();
+$start = $clock->now();
+// do some stuff
+$end = $clock->now();
+
+$elapsed = $end->elapsedSince($start);
+```
+
+`$elapsed` is an instance of `#!php Innmind\TimeContinuum\ElapsedPeriod`.
+
+Depending on the precision you need you can call either `$elapsed->milliseconds()` or `$elapsed->microseconds()`.
+
+This is especially useful when working with network I/O to check for timeouts.
+
+!!! success ""
+    This example uses a monotonic clock internally to avoid the problem where the server clock re-synchronize and jump back in time. In this case `$end` is _technically_ before `$start` but the elapsed period is still a positive `int`.
+
+??? info
+    Bear in mind that the monotonic clock only works on `PointInTime`s returned by `$clock->now()`. If `->elapsedSince()` is called on points returned by `$clock->at()` it will compare the number od microseconds [since epoch](points-in-time.md#milliseconds-since-epoch).
+
+??? warning
+    `ElapsedPeriod` uses an `int` internally to represent the number of microseconds. If you compare two points far away between each other you may end up with an overflow.
+
+    Since this feature is mainly intended for network I/O handling the points should be close from one another. So this bug won't be addresed at least for now.

docs/getting-started/formats.md

@@ -0,0 +1,72 @@
+# Formats
+
+A `Format` is a representation on how to convert a [`PointInTime`](points-in-time.md) to a `string`, or vice versa.
+
+By default this library comes with these formats:
+
+```php
+use Innmind\TimeContinuum\Format;
+
+Format::cookie();
+Format::iso8601();
+Format::rfc1036();
+Format::rfc1123();
+Format::rfc2822();
+Format::rfc822();
+Format::rfc850();
+Format::rss();
+```
+
+Formats are wrapped in an object in order to give them a name. When used in your application you can reference these names instead of duplicating the strings everywhere.
+
+## Convert to a string
+
+```php
+use Innmind\TimeContinuum\{
+    Clock,
+    Format,
+};
+
+echo Clock::live()
+    ->now()
+    ->format(Format::iso8601());
+```
+
+This would print something like `#!php '2024-11-24T14:50:00+00:00'`.
+
+## Convert from a string
+
+```php
+use Innmind\TimeContinuum\{
+    Clock,
+    Format,
+    PointInTime,
+};
+
+$point = Clock::live()
+    ->at('some string', Format::iso8601())
+    ->match(
+        static fn(PointInTime $point) => $point,
+        static fn() => null,
+    );
+```
+
+Here `#!php $point` is `#!php null` because `#!php 'some string'` is not a valid date.
+
+## Define your own format
+
+If you want to use your own format you can do this via `#!php Format::of('date format')`. The `string` can be anything accepted by [`#!php \DateTimeImmutable::format()`](https://www.php.net/manual/en/datetime.format.php).
+
+You're encouraged to statically define these formats somewhere in your program like this:
+
+```php
+use Innmind\TimeContinuum\Format;
+
+final class MyFormats
+{
+    public static function iso8601WithMicroseconds(): Format
+    {
+        return Format::of('Y-m-dT:H:i:s.uP');
+    }
+}
+```

docs/getting-started/index.md

@@ -0,0 +1,7 @@
+# Getting started
+
+## Installation
+
+```sh
+composer require innmind/time-continuum
+```