Merge branch 'review-container'

Author: lkrms

CHANGELOG.md

@@ -10,6 +10,24 @@ The format is based on [Keep a Changelog][], and this project adheres to [Semant
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
+## [v0.99.79] - 2025-03-31
+
+### Added
+
+#### `Container`
+
+- Add and implement `ApplicationInterface` methods:
+  - `hasOutputLog()`
+  - `hasHarRecorder()`
+  - `hasCache()`
+  - `hasSync()`
+
+### Changed
+
+#### `Container`
+
+- Rename `ApplicationInterface` method `exportHar()` to `recordHar()`
+
 ## [v0.99.78] - 2025-03-28
 
 ### Added
@@ -4917,6 +4935,7 @@ This is the final release of `lkrms/util`. It is moving to [Salient](https://git
 
 - Allow `CliOption` value names to contain arbitrary characters
 
+[v0.99.79]: https://github.com/salient-labs/toolkit/compare/v0.99.78...v0.99.79
 [v0.99.78]: https://github.com/salient-labs/toolkit/compare/v0.99.77...v0.99.78
 [v0.99.77]: https://github.com/salient-labs/toolkit/compare/v0.99.76...v0.99.77
 [v0.99.76]: https://github.com/salient-labs/toolkit/compare/v0.99.75...v0.99.76

src/Toolkit/Container/Application.php

@@ -394,6 +394,14 @@ public function isRunningInProduction(): bool
             ));
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function hasOutputLog(): bool
+    {
+        return $this->OutputLogIsRegistered;
+    }
+
     /**
      * @inheritDoc
      */
@@ -416,7 +424,15 @@ public function logOutput(?string $name = null, ?bool $debug = null)
     /**
      * @inheritDoc
      */
-    public function exportHar(
+    public function hasHarRecorder(): bool
+    {
+        return $this->HarListenerId !== null || $this->HarRecorder;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function recordHar(
         ?string $name = null,
         ?string $creatorName = null,
         ?string $creatorVersion = null,
@@ -487,6 +503,16 @@ public function getHarFilename(): ?string
             : null;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function hasCache(): bool
+    {
+        return $this->CacheStore || (
+            Cache::isLoaded() && $this->globalCacheIsValid()
+        );
+    }
+
     /**
      * @inheritDoc
      */
@@ -496,16 +522,12 @@ public function startCache()
             throw new LogicException('Cache already started');
         }
         if (Cache::isLoaded()) {
-            $cache = Cache::getInstance();
-            if (
-                $cache instanceof CacheStore
-                && File::same($this->getCacheDb(false), $file = $cache->getFilename())
-            ) {
+            if ($this->globalCacheIsValid($name)) {
                 return $this;
             }
             throw new LogicException(sprintf(
                 'Global cache already started: %s',
-                $file ?? get_class($cache),
+                $name,
             ));
         }
         $this->CacheStore = new CacheStore($this->getCacheDb());
@@ -540,11 +562,33 @@ public function stopCache()
         return $this;
     }
 
+    /**
+     * @param-out string $name
+     */
+    private function globalCacheIsValid(?string &$name = null): bool
+    {
+        $cache = Cache::getInstance();
+        $isValid = $cache instanceof CacheStore
+            && File::same($this->getCacheDb(false), $file = $cache->getFilename());
+        $name = $file ?? get_class($cache);
+        return $isValid;
+    }
+
     private function getCacheDb(bool $create = true): string
     {
         return $this->getCachePath($create) . '/cache.db';
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function hasSync(): bool
+    {
+        return $this->SyncStore || (
+            Sync::isLoaded() && $this->globalSyncIsValid()
+        );
+    }
+
     /**
      * @param string[]|null $arguments
      */
@@ -554,16 +598,12 @@ public function startSync(?string $command = null, ?array $arguments = null)
             throw new LogicException('Sync entity store already started');
         }
         if (Sync::isLoaded()) {
-            $store = Sync::getInstance();
-            if (
-                $store instanceof SyncStore
-                && File::same($this->getSyncDb(false), $file = $store->getFilename())
-            ) {
+            if ($this->globalSyncIsValid($name)) {
                 return $this;
             }
             throw new LogicException(sprintf(
                 'Global sync entity store already started: %s',
-                $file ?? get_class($store),
+                $name,
             ));
         }
         if ($arguments === null && $command === null) {
@@ -615,6 +655,18 @@ public function sync(
         return $this;
     }
 
+    /**
+     * @param-out string $name
+     */
+    private function globalSyncIsValid(?string &$name = null): bool
+    {
+        $store = Sync::getInstance();
+        $isValid = $store instanceof SyncStore
+            && File::same($this->getSyncDb(false), $file = $store->getFilename());
+        $name = $file ?? get_class($store);
+        return $isValid;
+    }
+
     private function getSyncDb(bool $create = true): string
     {
         return $this->getDataPath($create) . '/sync.db';

src/Toolkit/Contract/Container/ApplicationInterface.php

@@ -66,6 +66,12 @@ public function getTempPath(): string;
      */
     public function isRunningInProduction(): bool;
 
+    /**
+     * Check if console output is being logged to the application's log
+     * directory
+     */
+    public function hasOutputLog(): bool;
+
     /**
      * Log console output to the application's log directory
      *
@@ -83,7 +89,15 @@ public function isRunningInProduction(): bool;
     public function logOutput(?string $name = null, ?bool $debug = null);
 
     /**
-     * Export the application's HTTP requests to an HTTP Archive (HAR) file in
+     * Check if the application's HTTP requests are being recorded
+     *
+     * Returns `true` if {@see recordHar()} has been called, even if no
+     * subsequent HTTP requests have been made.
+     */
+    public function hasHarRecorder(): bool;
+
+    /**
+     * Record the application's HTTP requests to an HTTP Archive (HAR) file in
      * its log directory
      *
      * If any HTTP requests are made via {@see CurlerInterface} implementations,
@@ -94,7 +108,7 @@ public function logOutput(?string $name = null, ?bool $debug = null);
      * @return $this
      * @throws LogicException if HTTP requests are already being recorded.
      */
-    public function exportHar(
+    public function recordHar(
         ?string $name = null,
         ?string $creatorName = null,
         ?string $creatorVersion = null,
@@ -104,20 +118,27 @@ public function exportHar(
     /**
      * Get the name of the application's HTTP Archive (HAR) file if it exists
      *
-     * Returns `null` if {@see exportHar()} has been called but no HTTP requests
+     * Returns `null` if {@see recordHar()} has been called but no HTTP requests
      * have been made.
      *
      * @throws LogicException if HTTP requests are not being recorded.
      */
     public function getHarFilename(): ?string;
 
+    /**
+     * Check if a cache has been started for the application
+     */
+    public function hasCache(): bool;
+
     /**
      * Start a cache for the application and make it the global cache
      *
      * If the cache is filesystem-backed, it is started in the application's
      * cache directory.
      *
      * @return $this
+     * @throws LogicException if a cache has already been started for the
+     * application.
      */
     public function startCache();
 
@@ -128,6 +149,11 @@ public function startCache();
      */
     public function stopCache();
 
+    /**
+     * Check if a sync entity store has been started for the application
+     */
+    public function hasSync(): bool;
+
     /**
      * Start a sync entity store for the application and make it the global sync
      * entity store
@@ -136,6 +162,8 @@ public function stopCache();
      * application's data directory.
      *
      * @return $this
+     * @throws LogicException if a sync entity store has already been started
+     * for the application.
      */
     public function startSync();
 

src/Toolkit/Sync/Command/AbstractSyncCommand.php

@@ -25,7 +25,7 @@
  */
 abstract class AbstractSyncCommand extends CliCommand
 {
-    protected bool $ExportHar = false;
+    protected bool $RecordHar = false;
 
     // --
 
@@ -147,17 +147,17 @@ protected function getGlobalOptionList(): iterable
             CliOption::build()
                 ->long('har')
                 ->short('H')
-                ->description('Export HTTP requests to an HTTP Archive file in the log directory')
-                ->bindTo($this->ExportHar),
+                ->description('Record HTTP requests to an HTTP Archive file in the log directory')
+                ->bindTo($this->RecordHar),
         ];
     }
 
     protected function startRun(): void
     {
         Console::registerStderrTarget();
 
-        if ($this->ExportHar) {
-            $this->App->exportHar();
+        if ($this->RecordHar) {
+            $this->App->recordHar();
         }
     }