Added response methods (#95)

src/kernel/http/firehub.Response.php

@@ -18,10 +18,11 @@
 use FireHub\Core\Support\Str;
 use FireHub\Core\Support\Collection\Type\Indexed;
 use FireHub\Core\Support\Enums\HTTP\ {
-    CommonMimeType, StatusCode,
-    Authentication\Scheme, Cache\Response as CacheDirectives, Contracts\StatusCode as StatusCodeContract
+    CommonMimeType, ContentDisposition, SiteData, StatusCode,
+    Authentication\Scheme, Contracts\StatusCode as StatusCodeContract
 };
 use FireHub\Core\Support\Enums\Hash\Algorithm;
+use FireHub\Core\Support\Enums\String\Encoding;
 use FireHub\Core\Support\LowLevel\ {
     Hash, HTTP
 };
@@ -31,6 +32,8 @@
  *
  * Response holds all the information that needs to be sent back to the client from a given request.
  * @since 1.0.0
+ *
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class Response extends BaseResponse {
 
@@ -148,6 +151,88 @@ public function cache (Indexed $directives):self {
 
     }
 
+    /**
+     * ### Clears browsing data (cookies, storage, cache) associated with the requesting website
+     *
+     * The Clear-Site-Data header accepts one or more directives.
+     * If all types of data should be cleared, the wildcard directive (*) can be used.
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\Enums\HTTP\SiteData As parameter.
+     * @uses \FireHub\Core\Support\Str::from() To create string from SiteData enum.
+     * @uses \FireHub\Core\Support\Str::surround() To surround directives with double quotes.
+     * @uses \FireHub\Core\Kernel\HTTP\Response::replaceHeader() To send and replace a raw HTTP header.
+     *
+     * @param \FireHub\Core\Support\Enums\HTTP\SiteData ...$data <p>
+     * HTTP site data.
+     * </p>
+     *
+     * @return $this This response.
+     *
+     * @note This feature is available only in secure contexts (HTTPS).
+     */
+    public function clearData (SiteData ...$data):self {
+
+        $data = $data ?: ['*'];
+
+        $directives = [];
+        foreach ($data as $directive)
+            $directives[] = Str::from($directive instanceOf SiteData ? $directive->value : $directive)->surround('"');
+
+        $directives = Str::fromList($directives, ', ');
+
+        $this->replaceHeader('Clear-Site-Data: '.$directives);
+
+        return $this;
+
+    }
+
+    /**
+     * ### Indicate the original media type of the resource prior to any content encoding applied before transmission
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\Enums\HTTP\CommonMimeType As parameter.
+     * @uses \FireHub\Core\Support\Enums\String\Encoding As parameter.
+     * @uses \FireHub\Core\Kernel\HTTP\Response::replaceHeader() To send and replace a raw HTTP header.
+     *
+     * @param \FireHub\Core\Support\Enums\HTTP\CommonMimeType $type <p>
+     * HTTP common content media type.
+     * </p>
+     * @param null|\FireHub\Core\Support\Enums\String\Encoding $encoding [optional] <p>
+     * Character encodings enum.
+     * </p>
+     *
+     * @return $this This response.
+     */
+    public function contentType (CommonMimeType $type, ?Encoding $encoding = null):self {
+
+        $this->replaceHeader('Content-Type: '.$type->value.($encoding ? '; charset='.$encoding->value : ''));
+
+        return $this;
+
+    }
+
+    /**
+     * ### Indicate if the content is expected to be displayed inline or downloaded
+     * @since 1.0.0
+     *
+     * @uses \FireHub\Core\Support\Enums\HTTP\ContentDisposition As parameter.
+     * @uses \FireHub\Core\Kernel\HTTP\Response::replaceHeader() To send and replace a raw HTTP header.
+     *
+     * @param \FireHub\Core\Support\Enums\HTTP\ContentDisposition $disposition <p>
+     * HTTP content disposition.
+     * </p>
+     *
+     * @return $this This response.
+     */
+    public function contentDisposition (ContentDisposition $disposition, ?string $filename = null):self {
+
+        $this->replaceHeader('Content-Disposition: '.$disposition->value.($filename ? '; '.$filename : ''));
+
+        return $this;
+
+    }
+
     /**
      * ### Send a raw HTTP header
      * @since 1.0.0

src/support/bags/firehub.ResponseHeaders.php

@@ -94,8 +94,7 @@ final class ResponseHeaders extends Bag {
     public string $content_encoding = '';
 
     /**
-     * ### Describes the language intended for the audience, so users can differentiate it according to their own
-     * preferred language
+     * ### Describes the language intended for the audience, so users can differentiate it according to their own preferred language
      * @since 1.0.0
      *
      * @var string

src/support/enums/http/firehub.CommonMimeType.php

@@ -43,6 +43,12 @@ enum CommonMimeType:string implements InitBackedEnum {
      */
     case BIN = 'application/octet-stream';
 
+    /**
+     * ### JSON content
+     * @since 1.0.0
+     */
+    case JSON = 'application/json';
+
     /**
      * ### XML content
      * @since 1.0.0

src/support/enums/http/firehub.ContentDisposition.php

@@ -0,0 +1,45 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of FireHub Web Application Framework package
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2024 FireHub Web Application Framework
+ * @license <https://opensource.org/licenses/OSL-3.0> OSL Open Source License version 3
+ *
+ * @package Core\Support
+ *
+ * @version GIT: $Id$ Blob checksum.
+ */
+
+namespace FireHub\Core\Support\Enums\HTTP;
+
+use FireHub\Core\Base\ {
+    InitBackedEnum, Trait\ConcreteBackedEnum
+};
+
+/**
+ * ### HTTP content disposition
+ * @since 1.0.0
+ */
+enum ContentDisposition:string implements InitBackedEnum {
+
+    /**
+     * ### FireHub initial concrete-backed enum trait
+     * @since 1.0.0
+     */
+    use ConcreteBackedEnum;
+
+    /**
+     * ### AES-GCM encryption with a 128-bit content encryption key
+     * @since 1.0.0
+     */
+    case INLINE = 'inline';
+
+    /**
+     * ### AES-GCM encryption with a 128-bit content encryption key
+     * @since 1.0.0
+     */
+    case ATTACHMENT = 'attachment';
+
+}

src/support/enums/http/firehub.SiteData.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types = 1);
+
+/**
+ * This file is part of FireHub Web Application Framework package
+ *
+ * @author Danijel Galić <danijel.galic@outlook.com>
+ * @copyright 2024 FireHub Web Application Framework
+ * @license <https://opensource.org/licenses/OSL-3.0> OSL Open Source License version 3
+ *
+ * @package Core\Support
+ *
+ * @version GIT: $Id$ Blob checksum.
+ */
+
+namespace FireHub\Core\Support\Enums\HTTP;
+
+use FireHub\Core\Base\ {
+    InitBackedEnum, Trait\ConcreteBackedEnum
+};
+
+/**
+ * ### HTTP site data
+ * @since 1.0.0
+ */
+enum SiteData:string implements InitBackedEnum {
+
+    /**
+     * ### FireHub initial concrete-backed enum trait
+     * @since 1.0.0
+     */
+    use ConcreteBackedEnum;
+
+    /**
+     * ### Cookies for the origin of the response URL
+     * @since 1.0.0
+     */
+    case COOKIES = 'cookies';
+
+    /**
+     * ### DOM storage for the origin of the response URL
+     *
+     * localStorage, sessionStorage, IndexedDB, Service worker registrations, and so on.
+     * @since 1.0.0
+     */
+    case STORAGE = 'storage';
+
+}