Add FrozenClock and SystemClock implementations with service provider integration

- Introduced `FrozenClock` for deterministic time in tests, supporting various input formats.
- Implemented `SystemClock` for current system time with optional timezone support.
- Created `ClockServiceProvider` to register clock services in the Fast Forward Container.
- Added `DateTimeZoneFactory` for creating timezone instances based on configuration.
- Developed usage examples demonstrating clock functionalities.
- Wrote comprehensive tests for `FrozenClock`, `SystemClock`, and service provider functionalities.
- Updated documentation to include usage instructions and examples.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

.docheader

@@ -0,0 +1,13 @@
+/**
+ * This file is part of php-fast-forward/clock.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @copyright Copyright (c) 2025-%year% Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ *
+ * @see       https://github.com/php-fast-forward/clock
+ * @see       https://github.com/php-fast-forward
+ * @see       https://datatracker.ietf.org/doc/html/rfc2119
+ */

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1,7 @@
+*                   text=auto
+/.github/           export-ignore
+/docs/              export-ignore
+/tests/             export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.gitmodules        export-ignore

.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "composer"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "Composer"
+      include: "scope"
+    labels:
+      - "composer"
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "GitHub Actions"
+      include: "scope"
+    labels:
+      - "github-actions"
+      - "continuous-integration"

.github/wiki

@@ -0,0 +1,17 @@
+name: "Fast Forward Reports"
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  reports:
+    uses: php-fast-forward/dev-tools/.github/workflows/reports.yml@main
+    secrets: inherit

.github/workflows/reports.yml

@@ -0,0 +1,15 @@
+name: "Fast Forward Test Suite"
+
+on:
+  push:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  tests:
+    uses: php-fast-forward/dev-tools/.github/workflows/tests.yml@main
+    secrets: inherit

.github/workflows/tests.yml

@@ -0,0 +1,17 @@
+name: "Fast Forward Wiki Update"
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  wiki:
+    uses: php-fast-forward/dev-tools/.github/workflows/wiki.yml@main
+    secrets: inherit

.github/workflows/wiki.yml

@@ -0,0 +1,9 @@
+.idea/
+.vscode/
+backup/
+public/
+tmp/
+vendor/
+.DS_Store
+composer.lock
+*.cache

.gitignore

@@ -0,0 +1,3 @@
+[submodule ".github/wiki"]
+	path = .github/wiki
+	url = git@github.com:php-fast-forward/clock.wiki.git