feat: add ClockServiceProvider integration to FrameworkServiceProvider and update documentation

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

Author: coisa

composer.json

@@ -16,6 +16,7 @@
     },
     "require": {
         "php": "^8.3",
+        "fast-forward/clock": "^1.0",
         "fast-forward/config": "^1.4",
         "fast-forward/container": "^1.5",
         "fast-forward/defer": "^1.0",

docs/api/service-map.rst

@@ -32,6 +32,9 @@ Framework-level classes and providers
    * - ``FastForward\EventDispatcher\EventDispatcher``
      - ``fast-forward/event-dispatcher``
      - Concrete dispatcher implementation behind the PSR-14 and Symfony contracts interfaces
+   * - ``FastForward\Clock\ServiceProvider\ClockServiceProvider``
+     - ``fast-forward/clock``
+     - Registers the PSR-20 clock, a system clock implementation, and timezone factory
 
 Installed entry points outside the framework provider
 -----------------------------------------------------

docs/api/service-provider.rst

@@ -4,9 +4,10 @@ FrameworkServiceProvider
 .. php:class:: FastForward\Framework\ServiceProvider\FrameworkServiceProvider
 
    Aggregates the default Fast Forward framework providers into a single container entry point.
-   In the current package, it composes the HTTP stack and the event-dispatcher stack by delegating
-   to ``FastForward\Http\ServiceProvider\HttpServiceProvider`` and
-   ``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``.
+   In the current package, it composes the HTTP stack, the event-dispatcher stack, and the clock utilities
+   by delegating to ``FastForward\Http\ServiceProvider\HttpServiceProvider``,
+   ``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``, and
+   ``FastForward\Clock\ServiceProvider\ClockServiceProvider``.
 
    The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``,
    so it inherits the provider-merging behavior used across the ecosystem.
@@ -28,6 +29,8 @@ What it aggregates
 - Through that provider, the HTTP message factories and HTTP client service providers
 - ``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``
 - Through that provider, the PSR-14 dispatcher, Symfony contracts dispatcher alias, and listener-provider services
+- ``FastForward\Clock\ServiceProvider\ClockServiceProvider``
+- Through that provider, the PSR-20 clock, a system clock implementation, and timezone factory
 
 Important behavior inherited from ``AggregateServiceProvider``
 --------------------------------------------------------------
@@ -48,7 +51,12 @@ Constructor
 Current scope
 -------------
 
-Although the metapackage installs multiple libraries, this local service provider currently wires
-the HTTP and event-dispatcher stacks only. Packages such as ``fast-forward/config``,
-``fast-forward/defer``, ``fast-forward/fork``, and ``fast-forward/iterators`` remain available
-through Composer autoloading and can be introduced into your application as needed.
+The framework provider wires three main stacks:
+
+- HTTP (via ``HttpServiceProvider``)
+- Event-dispatching (via ``EventDispatcherServiceProvider``)
+- Clock/time utilities (via ``ClockServiceProvider``)
+
+Packages such as ``fast-forward/config``, ``fast-forward/defer``, ``fast-forward/fork``, and
+``fast-forward/iterators`` remain available through Composer autoloading and can be introduced
+into your application as needed.

grumphp.yml

@@ -18,28 +18,29 @@
 
 namespace FastForward\Framework\ServiceProvider;
 
+use FastForward\Clock\ServiceProvider\ClockServiceProvider;
 use FastForward\Container\ServiceProvider\AggregateServiceProvider;
 use FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider;
 use FastForward\Http\ServiceProvider\HttpServiceProvider;
 
 /**
- * Class FrameworkServiceProvider.
- *
  * Aggregates core framework service providers into a unified service provider.
+ *
  * This class MUST be used to encapsulate all foundational service providers
  * required to initialize the application container.
  *
- * The current aggregation includes:
- * - {@see HttpServiceProvider} for the HTTP stack
- * - {@see EventDispatcherServiceProvider} for PSR-14 and Symfony-compatible event dispatching
- *
  * This class SHALL implement the ServiceProviderInterface and MUST delegate
  * its service discovery responsibilities to an internal AggregateServiceProvider.
+ *
+ * @see AggregateServiceProvider for composing multiple service providers into one
+ * @see HttpServiceProvider for HTTP handling and middleware support
+ * @see EventDispatcherServiceProvider for PSR-14 and Symfony-compatible event dispatching
+ * @see ClockServiceProvider for time and scheduling utilities
  */
 final class FrameworkServiceProvider extends AggregateServiceProvider
 {
     /**
-     * Constructs the FrameworkServiceProvider.
+     * Creates a new FrameworkServiceProvider instance.
      *
      * This constructor MUST initialize the aggregate service provider using
      * a composition of essential framework service providers.
@@ -49,6 +50,7 @@ public function __construct()
         parent::__construct(
             new HttpServiceProvider(),
             new EventDispatcherServiceProvider(),
+            new ClockServiceProvider(),
         );
     }
 }

src/ServiceProvider/FrameworkServiceProvider.php

@@ -18,6 +18,7 @@
 
 namespace FastForward\Framework\Tests\ServiceProvider;
 
+use FastForward\Clock\ServiceProvider\ClockServiceProvider;
 use FastForward\Container\Factory\ServiceFactory;
 use FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider;
 use FastForward\Framework\ServiceProvider\FrameworkServiceProvider;
@@ -47,12 +48,15 @@ public function getFactoriesWillReturnAggregatedServiceProviderFactories(): void
     {
         $eventDispatcherServiceProvider = new EventDispatcherServiceProvider();
         $httpServiceProvider = new HttpServiceProvider();
+        $clockServiceProvider = new ClockServiceProvider();
 
         $expectedFactories = array_merge(
             $httpServiceProvider->getFactories(),
             $eventDispatcherServiceProvider->getFactories(),
+            $clockServiceProvider->getFactories(),
             [
                 EventDispatcherServiceProvider::class => new ServiceFactory($eventDispatcherServiceProvider),
+                ClockServiceProvider::class => new ServiceFactory(new ClockServiceProvider()),
                 FrameworkServiceProvider::class => new ServiceFactory($this->provider),
             ]
         );
@@ -76,6 +80,7 @@ public function getExtensionsWillReturnAggregatedServiceProviderExtensions(): vo
         $expectedExtensions = array_merge(
             (new HttpServiceProvider())->getExtensions(),
             (new EventDispatcherServiceProvider())->getExtensions(),
+            (new ClockServiceProvider())->getExtensions(),
         );
 
         $actualExtensions = $this->provider->getExtensions();