Feature/2.12

manual/includes/_session.md

@@ -8,16 +8,37 @@ Session variables keep information about one single user, and are available to a
 
 ```yaml
 session:
-  name: MUSICPRODUCTIONMANAGER
-  max_life_time: 86400
-  save_handler: files
-  save_path: /tmp/sessions
+  name: ${SESSION_NAME}
+  max_life_time: ${SESSION_MAX_LIFE_TIME}
+  save_handler: ${SESSION_SAVE_HANDLER}
+  save_path: ${SESSION_SAVE_PATH}
+  cookie_lifetime: ${SESSION_COOKIE_LIFETIME}
+  cookie_path: ${SESSION_COOKIE_PATH}
+  cookie_secure: ${SESSION_COOKIE_SECURE}
+  cookie_httponly: ${SESSION_COOKIE_HTTPONLY}
+  cookie_domain: ${SESSION_COOKIE_DOMAIN}
 ```
 
-- `name`: Name of the session.
-- `max_life_time`: Maximum lifetime of the session in seconds (e.g., 86400 seconds = 24 hours).
-- `save_handler`: Specifies the session storage mechanism (in this case, files).
-- `save_path`: Directory where session files are stored.
+### Explanation:
+
+-   **name**: Specifies the name of the session. The value `${SESSION_NAME}` refers to an environment variable or a parameter that should be defined elsewhere in the application or server environment. It determines the session's name identifier.
+
+-   **max_life_time**: Defines the maximum lifetime of the session in seconds. The value `${SESSION_MAX_LIFE_TIME}` is expected to come from an environment variable or configuration setting, controlling how long the session will last before it expires.
+
+-   **save_handler**: Specifies the handler used to save session data. In this case, `${SESSION_SAVE_HANDLER}` likely refers to the session handler, such as `redis`, `files`, or `database`, depending on the server configuration.
+
+-   **save_path**: Defines the path where session data will be stored. The value `${SESSION_SAVE_PATH}` is an environment variable or configuration parameter, which could specify a directory or Redis connection string (if `redis` is used as the save handler).
+
+-   **cookie_lifetime**: Specifies the lifetime of the session cookie in seconds, which controls how long the cookie will persist in the user's browser. `${SESSION_COOKIE_LIFETIME}` is the environment variable or configuration value that sets this duration.
+
+-   **cookie_path**: The path on the server where the session cookie is valid. `${SESSION_COOKIE_PATH}` determines the directory or URL prefix for which the session cookie is set.
+
+-   **cookie_secure**: A boolean flag that determines whether the session cookie should be transmitted over HTTPS only. If `${SESSION_COOKIE_SECURE}` is set to `true`, the cookie will only be sent over secure connections.
+
+-   **cookie_httponly**: A boolean flag that indicates whether the session cookie is accessible only through the HTTP protocol (i.e., not accessible via JavaScript). If `${SESSION_COOKIE_HTTPONLY}` is `true`, it increases security by preventing client-side access to the cookie.
+
+-   **cookie_domain**: Specifies the domain to which the session cookie is valid. `${SESSION_COOKIE_DOMAIN}` can define the domain for which the session cookie should be sent, allowing cross-subdomain access to the session.
+
 
 **PHP Script**
 
@@ -68,10 +89,15 @@ For example:
 
 ```yaml
 session:
-  name: MUSICPRODUCTIONMANAGER
-  max_life_time: 86400
-  save_handler: redis
+  name: ${SESSION_NAME}
+  max_life_time: ${SESSION_MAX_LIFE_TIME}
+  save_handler: ${SESSION_SAVE_HANDLER}
   save_path: ${SESSION_SAVE_PATH}
+  cookie_lifetime: ${SESSION_COOKIE_LIFETIME}
+  cookie_path: ${SESSION_COOKIE_PATH}
+  cookie_secure: ${SESSION_COOKIE_SECURE}
+  cookie_httponly: ${SESSION_COOKIE_HTTPONLY}
+  cookie_domain: ${SESSION_COOKIE_DOMAIN}
 ```
 
 `${SESSION_SAVE_PATH}` contains entire of `save_path` that encrypted with you secure key.

manual/index.html

@@ -1989,15 +1989,44 @@ <h2>Session</h2>
 <h3>Session with File</h3>
 <p><strong>Yaml File</strong></p>
 <pre><code class="language-yaml">session:
-  name: MUSICPRODUCTIONMANAGER
-  max_life_time: 86400
-  save_handler: files
-  save_path: /tmp/sessions</code></pre>
+  name: ${SESSION_NAME}
+  max_life_time: ${SESSION_MAX_LIFE_TIME}
+  save_handler: ${SESSION_SAVE_HANDLER}
+  save_path: ${SESSION_SAVE_PATH}
+  cookie_lifetime: ${SESSION_COOKIE_LIFETIME}
+  cookie_path: ${SESSION_COOKIE_PATH}
+  cookie_secure: ${SESSION_COOKIE_SECURE}
+  cookie_httponly: ${SESSION_COOKIE_HTTPONLY}
+  cookie_domain: ${SESSION_COOKIE_DOMAIN}</code></pre>
+<h3>Explanation:</h3>
 <ul>
-<li><code>name</code>: Name of the session.</li>
-<li><code>max_life_time</code>: Maximum lifetime of the session in seconds (e.g., 86400 seconds = 24 hours).</li>
-<li><code>save_handler</code>: Specifies the session storage mechanism (in this case, files).</li>
-<li><code>save_path</code>: Directory where session files are stored.</li>
+<li>
+<p><strong>name</strong>: Specifies the name of the session. The value <code>${SESSION_NAME}</code> refers to an environment variable or a parameter that should be defined elsewhere in the application or server environment. It determines the session's name identifier.</p>
+</li>
+<li>
+<p><strong>max_life_time</strong>: Defines the maximum lifetime of the session in seconds. The value <code>${SESSION_MAX_LIFE_TIME}</code> is expected to come from an environment variable or configuration setting, controlling how long the session will last before it expires.</p>
+</li>
+<li>
+<p><strong>save_handler</strong>: Specifies the handler used to save session data. In this case, <code>${SESSION_SAVE_HANDLER}</code> likely refers to the session handler, such as <code>redis</code>, <code>files</code>, or <code>database</code>, depending on the server configuration.</p>
+</li>
+<li>
+<p><strong>save_path</strong>: Defines the path where session data will be stored. The value <code>${SESSION_SAVE_PATH}</code> is an environment variable or configuration parameter, which could specify a directory or Redis connection string (if <code>redis</code> is used as the save handler).</p>
+</li>
+<li>
+<p><strong>cookie_lifetime</strong>: Specifies the lifetime of the session cookie in seconds, which controls how long the cookie will persist in the user's browser. <code>${SESSION_COOKIE_LIFETIME}</code> is the environment variable or configuration value that sets this duration.</p>
+</li>
+<li>
+<p><strong>cookie_path</strong>: The path on the server where the session cookie is valid. <code>${SESSION_COOKIE_PATH}</code> determines the directory or URL prefix for which the session cookie is set.</p>
+</li>
+<li>
+<p><strong>cookie_secure</strong>: A boolean flag that determines whether the session cookie should be transmitted over HTTPS only. If <code>${SESSION_COOKIE_SECURE}</code> is set to <code>true</code>, the cookie will only be sent over secure connections.</p>
+</li>
+<li>
+<p><strong>cookie_httponly</strong>: A boolean flag that indicates whether the session cookie is accessible only through the HTTP protocol (i.e., not accessible via JavaScript). If <code>${SESSION_COOKIE_HTTPONLY}</code> is <code>true</code>, it increases security by preventing client-side access to the cookie.</p>
+</li>
+<li>
+<p><strong>cookie_domain</strong>: Specifies the domain to which the session cookie is valid. <code>${SESSION_COOKIE_DOMAIN}</code> can define the domain for which the session cookie should be sent, allowing cross-subdomain access to the session.</p>
+</li>
 </ul>
 <p><strong>PHP Script</strong></p>
 <pre><code class="language-php">&lt;?php
@@ -2031,10 +2060,15 @@ <h3>Session with Redis</h3>
 <p>You can not encrypt the <code>${REDIS_AUTH}</code> value. If you want to secure the config, encrypt entire <code>save_path</code> instead.</p>
 <p>For example:</p>
 <pre><code class="language-yaml">session:
-  name: MUSICPRODUCTIONMANAGER
-  max_life_time: 86400
-  save_handler: redis
-  save_path: ${SESSION_SAVE_PATH}</code></pre>
+  name: ${SESSION_NAME}
+  max_life_time: ${SESSION_MAX_LIFE_TIME}
+  save_handler: ${SESSION_SAVE_HANDLER}
+  save_path: ${SESSION_SAVE_PATH}
+  cookie_lifetime: ${SESSION_COOKIE_LIFETIME}
+  cookie_path: ${SESSION_COOKIE_PATH}
+  cookie_secure: ${SESSION_COOKIE_SECURE}
+  cookie_httponly: ${SESSION_COOKIE_HTTPONLY}
+  cookie_domain: ${SESSION_COOKIE_DOMAIN}</code></pre>
 <p><code>${SESSION_SAVE_PATH}</code> contains entire of <code>save_path</code> that encrypted with you secure key.</p>
 <p><strong>PHP Script</strong></p>
 <pre><code class="language-php">&lt;?php

src/Database/PicoDatabase.php

@@ -1056,6 +1056,33 @@ public function getDatabaseType()
         return $this->databaseType;
     }
 
+    /**
+     * Retrieves the time zone used by the database.
+     *
+     * This function calls the `getTimeZone()` method from the `databaseCredentials`
+     * object to fetch the time zone configured for the database connection.
+     *
+     * @return string The time zone of the database (e.g., "UTC", "America/New_York").
+     */
+    public function getDatabaseTimeZone()
+    {
+        return $this->databaseCredentials->getTimeZone();
+    }
+
+    /**
+     * Retrieves the time zone offset of the database connection.
+     *
+     * This function retrieves the time zone offset by calling the static method
+     * `getTimeZoneOffset()` with the `databaseConnection` as an argument.
+     * The offset is returned in seconds from UTC.
+     *
+     * @return string The time zone offset, typically in hours and minutes (e.g., "+02:00").
+     */
+    public function getDatabaseTimeZoneOffset()
+    {
+        return self::getTimeZoneOffset($this->databaseConnection);
+    }
+
     /**
      * Convert the object to a JSON string representation for debugging.
      *

src/Session/PicoSession.php

@@ -195,26 +195,29 @@ public function destroy()
     }
 
     /**
-     * Sets cookie parameters for the session.
+     * Sets the session cookie parameters, including lifetime, path, domain, security attributes, and SameSite settings.
      *
-     * This method sets parameters for the session cookie, including lifetime,
-     * security attributes, and SameSite settings.
+     * This method configures the session cookie parameters such as maximum lifetime, path, domain, and security settings
+     * like whether the cookie should be accessible only over HTTPS or only via HTTP. It also sets the SameSite attribute
+     * for compatibility with different browsers and PHP versions.
      *
-     * @param int $maxlifetime Maximum lifetime of the session cookie.
+     * @param int $maxlifetime Maximum lifetime of the session cookie in seconds.
+     * @param string $path The path where the cookie will be available on the server.
+     * @param string $domain The domain to which the cookie is available.
      * @param bool $secure Indicates if the cookie should only be transmitted over a secure HTTPS connection.
-     * @param bool $httponly Indicates if the cookie is accessible only through the HTTP protocol.
-     * @param string $samesite The SameSite attribute of the cookie (Lax, Strict, None).
+     * @param bool $httponly Indicates if the cookie should be accessible only through the HTTP protocol.
+     * @param string $samesite The SameSite attribute of the cookie (Lax, Strict, None). Default is 'Strict'.
      * @return self Returns the current instance for method chaining.
      */
-    public function setSessionCookieParams($maxlifetime, $secure, $httponly, $samesite = self::SAME_SITE_STRICT)
+    public function setSessionCookieParams($maxlifetime, $path, $domain, $secure, $httponly, $samesite = self::SAME_SITE_STRICT)
     {
         if (PHP_VERSION_ID < 70300) {
-            session_set_cookie_params($maxlifetime, '/; samesite=' . $samesite, $_SERVER['HTTP_HOST'], $secure, $httponly);
+            session_set_cookie_params($maxlifetime, $path.'; samesite=' . $samesite, $domain, $secure, $httponly);
         } else {
             session_set_cookie_params(array(
                 'lifetime' => $maxlifetime,
-                'path' => '/',
-                'domain' => $_SERVER['HTTP_HOST'],
+                'path' => $path,
+                'domain' => $domain,
                 'secure' => $secure,
                 'httponly' => $httponly,
                 'samesite' => $samesite
@@ -224,18 +227,19 @@ public function setSessionCookieParams($maxlifetime, $secure, $httponly, $samesi
     }
 
     /**
-     * Sets a cookie with SameSite attribute support for different PHP versions.
+     * Sets a cookie with the SameSite attribute, supporting both older and newer PHP versions.
      *
-     * This method sets a cookie with the specified SameSite attribute, supporting both older and newer PHP versions.
+     * This method sets a cookie with a specified SameSite attribute, ensuring compatibility with both PHP versions
+     * prior to and after PHP 7.3. It supports cookies with the 'Lax', 'Strict', or 'None' SameSite attributes.
      *
      * @param string $name The name of the cookie.
      * @param string $value The value of the cookie.
-     * @param int $expire The expiration time of the cookie.
-     * @param string $path The path on the server in which the cookie will be available.
-     * @param string $domain The domain that the cookie is available to.
+     * @param int $expire The expiration time of the cookie as a Unix timestamp.
+     * @param string $path The path on the server where the cookie is available.
+     * @param string $domain The domain to which the cookie is available.
      * @param bool $secure Indicates if the cookie should only be transmitted over a secure HTTPS connection.
      * @param bool $httponly Indicates if the cookie is accessible only through the HTTP protocol.
-     * @param string $samesite The SameSite attribute of the cookie (Lax, Strict, None).
+     * @param string $samesite The SameSite attribute of the cookie (Lax, Strict, None). Default is 'Strict'.
      * @return self Returns the current instance for method chaining.
      */
     public function setSessionCookieSameSite($name, $value, $expire, $path, $domain, $secure, $httponly, $samesite = self::SAME_SITE_STRICT) // NOSONAR
@@ -355,4 +359,18 @@ public function setSessionId($id)
         @session_id($id);
         return $this;
     }
+
+    /**
+     * Converts the session data to a string representation.
+     *
+     * This method returns the session data as a JSON-encoded string, which can be useful for debugging
+     * or logging the contents of the session. It encodes the global `$_SESSION` array into a JSON string.
+     *
+     * @return string The JSON-encoded string representation of the session data.
+     */
+    public function __toString()
+    {
+        return json_encode($_SESSION);
+    }
+
 }