Add comprehensive documentation for JwtSession including getting started guide, configuration options, API reference, RSA keys usage, security best practices, and internal implementation details.

Author: byjg

README.md

@@ -6,9 +6,18 @@
 [![GitHub license](https://img.shields.io/github/license/byjg/jwt-session.svg)](https://opensource.byjg.com/opensource/licensing.html) 
 [![GitHub release](https://img.shields.io/github/release/byjg/jwt-session.svg)](https://github.com/byjg/jwt-session/releases/)
 
-JwtSession is a PHP session replacement. Instead of use FileSystem, just use JWT TOKEN. 
+JwtSession is a PHP session replacement. Instead of use FileSystem, just use JWT TOKEN.
 The implementation following the SessionHandlerInterface.
 
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - Installation, basic usage, and motivation
+- [Configuration](docs/configuration.md) - Session timeout, contexts, cookies, and all configuration options
+- [RSA Keys](docs/rsa-keys.md) - Using RSA private/public keys for enhanced security
+- [How It Works](docs/how-it-works.md) - Architecture and internal implementation details
+- [Security](docs/security.md) - Security considerations and best practices
+- [API Reference](docs/api-reference.md) - Complete API documentation for all classes and methods
+
 # How to use:
 
 Before the session_start() use the command: 
@@ -24,38 +33,19 @@ session_set_save_handler($handler, true);
 
 Now, all your `$_SESSION` variable will be saved directly to a JWT Token!!
 
-## Secret key
-Make sure that you are providing a base64url encoded key.
- 
-# Motivation
-
-The default PHP Session does not work in different servers using round robin or other algorithms.
-This occurs because PHP Session are saved by default in the file system. 
-
-There are implementations can save the session to REDIS or MEMCACHED, for example. 
-But this requires to you create a new server to store this session and creates a single point of failure. 
-To avoid this you have to create REDIS/MEMCACHED clusters. 
-
-But if you save the session into JWT Token you do not need to create a new server.
-Just to use. 
-
-You can read more in this Codementor's article: 
-[Using JSON Web Token (JWT) as a PHP Session](https://www.codementor.io/byjg/using-json-web-token-jwt-as-a-php-session-axeuqbg1m)
-
-# Security Information
+**Note:** Make sure that you are providing a base64url encoded key.
 
-The JWT Token cannot be changed, but it can be read. 
-This implementation save the JWT into a client cookie.  
-Because of this _**do not** store in the JWT Token sensible data like passwords_.
+For more details on motivation, security considerations, and best practices, see the [Documentation](#documentation) section above.
 
 # Install
 
 ```
 composer require "byjg/jwt-session"
 ```
 
- 
-# Setting the validity of JWT Token
+# Configuration Examples
+
+## Setting the validity of JWT Token
 
 ```php
 <?php
@@ -67,7 +57,7 @@ $handler = new \ByJG\Session\JwtSession($sessionConfig);
 session_set_save_handler($handler, true);
 ```
 
-# Setting the different Session Contexts
+## Setting different Session Contexts
 
 ```php
 <?php
@@ -79,30 +69,9 @@ $handler = new \ByJG\Session\JwtSession($sessionConfig);
 session_set_save_handler($handler, true);
 ```
 
-# Create the handler and replace the session handler
-
-```php
-<?php
-$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com'))
-    ->withSecret('your super base64url encoded secret key')
-    ->replaceSessionHandler();
-
-$handler = new \ByJG\Session\JwtSession($sessionConfig);
-```
-
-# Specify cookie domain 
-
-```php
-<?php
-$sessionConfig = (new \ByJG\Session\SessionConfig('your.domain.com'))
-    ->withSecret('your super base64url encoded secret key')
-    ->withCookie('.mydomain.com', '/')
-    ->replaceSessionHandler();
-
-$handler = new \ByJG\Session\JwtSession($sessionConfig);
-```
+For complete configuration options including cookie domains and automatic session handler replacement, see [Configuration](docs/configuration.md).
 
-# Uses RSA Private/Public Keys
+## Using RSA Private/Public Keys
 
 ```php
 <?php
@@ -155,14 +124,7 @@ $sessionConfig = (new \ByJG\Session\SessionConfig('example.com'))
 $handler = new \ByJG\Session\JwtSession($sessionConfig);
 ```
 
-If you want to know more details about how to create RSA Public/Private Keys access:
-https://github.com/byjg/jwt-wrapper 
-
-
-# How it works
-
-We store a cookie named `AUTH_BEARER_` followed by the context name with the session name. The PHPSESSID cookie is still created because
-PHP create it by default but we do not use it;
+For more details about RSA keys and how to generate them, see [RSA Keys](docs/rsa-keys.md) and https://github.com/byjg/jwt-wrapper
 
 
 ## Dependencies

docs/api-reference.md

@@ -0,0 +1,272 @@
+---
+sidebar_position: 6
+---
+
+# API Reference
+
+## Classes
+
+### `ByJG\Session\JwtSession`
+
+Implements PHP's `SessionHandlerInterface` to provide JWT-based session storage.
+
+#### Constants
+
+- **`COOKIE_PREFIX`** = `"AUTH_BEARER_"`
+  Prefix for the session cookie name.
+
+#### Constructor
+
+```php
+public function __construct(SessionConfig $sessionConfig)
+```
+
+**Parameters:**
+- `$sessionConfig` (SessionConfig): Configuration object for the JWT session
+
+**Throws:**
+- `JwtSessionException`: If SessionConfig instance is invalid or session already started
+
+#### SessionHandlerInterface Methods
+
+##### `open(string $path, string $name): bool`
+
+Initialize the session (no-op in JWT implementation).
+
+##### `close(): bool`
+
+Close the session (no-op in JWT implementation).
+
+##### `read(string $id): string`
+
+Read session data from JWT cookie.
+
+**Parameters:**
+- `$id` (string): Session ID (not used in JWT implementation)
+
+**Returns:** Serialized session data string, or empty string if no session exists
+
+##### `write(string $id, string $data): bool`
+
+Write session data to JWT cookie.
+
+**Parameters:**
+- `$id` (string): Session ID (not used in JWT implementation)
+- `$data` (string): Serialized session data from PHP
+
+**Returns:** true on success
+
+**Throws:**
+- `JwtWrapperException`: If JWT token generation fails
+
+##### `destroy(string $id): bool`
+
+Destroy the session by clearing the JWT cookie.
+
+**Parameters:**
+- `$id` (string): Session ID to destroy
+
+**Returns:** true on success
+
+##### `gc(int $max_lifetime): int|false`
+
+Garbage collection (no-op in JWT implementation as tokens are self-expiring).
+
+**Parameters:**
+- `$max_lifetime` (int): Maximum session lifetime
+
+**Returns:** true
+
+#### Public Helper Methods
+
+##### `serializeSessionData(array $array): string`
+
+Manually serialize session data into PHP session format.
+
+**Parameters:**
+- `$array` (array): Associative array of session data
+
+**Returns:** Serialized string in PHP session format
+
+##### `unSerializeSessionData(string $session_data): array`
+
+Parse PHP session serialized data back into an array.
+
+**Parameters:**
+- `$session_data` (string): Serialized session data
+
+**Returns:** Associative array of session variables
+
+**Throws:**
+- `JwtSessionException`: If session data format is invalid
+
+---
+
+### `ByJG\Session\SessionConfig`
+
+Configuration class for JWT sessions with fluent interface.
+
+#### Constructor
+
+```php
+public function __construct(string $serverName)
+```
+
+**Parameters:**
+- `$serverName` (string): Server name/domain for JWT token
+
+#### Configuration Methods
+
+##### `withSecret(string $secret): static`
+
+Set the secret key for JWT encoding/decoding.
+
+**Parameters:**
+- `$secret` (string): Base64url encoded secret key
+
+**Returns:** Self for method chaining
+
+##### `withRsaSecret(string $private, string $public): static`
+
+Use RSA private/public keys for JWT encoding/decoding.
+
+**Parameters:**
+- `$private` (string): RSA private key (PEM format)
+- `$public` (string): RSA public key (PEM format)
+
+**Returns:** Self for method chaining
+
+##### `withTimeoutMinutes(int $timeout): static`
+
+Set JWT token validity in minutes.
+
+**Parameters:**
+- `$timeout` (int): Timeout in minutes (default: 20)
+
+**Returns:** Self for method chaining
+
+##### `withTimeoutHours(int $timeout): static`
+
+Set JWT token validity in hours.
+
+**Parameters:**
+- `$timeout` (int): Timeout in hours
+
+**Returns:** Self for method chaining
+
+##### `withSessionContext(string $context): static`
+
+Set custom session context name.
+
+**Parameters:**
+- `$context` (string): Context name (default: 'default')
+
+**Returns:** Self for method chaining
+
+##### `withCookie(string $domain, string $path = '/'): static`
+
+Configure cookie domain and path.
+
+**Parameters:**
+- `$domain` (string): Cookie domain (e.g., '.example.com')
+- `$path` (string): Cookie path (default: '/')
+
+**Returns:** Self for method chaining
+
+##### `replaceSessionHandler(bool $startSession = true): static`
+
+Configure automatic session handler replacement.
+
+**Parameters:**
+- `$startSession` (bool): Whether to start session automatically (default: true)
+
+**Returns:** Self for method chaining
+
+#### Getter Methods
+
+##### `getServerName(): string`
+
+Get the configured server name.
+
+##### `getSessionContext(): string`
+
+Get the session context name.
+
+##### `getTimeoutMinutes(): int`
+
+Get the timeout in minutes.
+
+##### `getCookieDomain(): ?string`
+
+Get the cookie domain.
+
+##### `getCookiePath(): string`
+
+Get the cookie path.
+
+##### `getKey(): ?JwtKeyInterface`
+
+Get the JWT key interface instance.
+
+##### `isReplaceSession(): bool`
+
+Check if session handler replacement is configured.
+
+##### `isStartSession(): bool`
+
+Check if automatic session start is enabled.
+
+---
+
+### `ByJG\Session\JwtSessionException`
+
+Exception class for JWT session errors.
+
+**Extends:** `Exception`
+
+**Use cases:**
+- Invalid SessionConfig provided
+- Session already started
+- Invalid serialized session data
+
+## Example Usage
+
+### Basic Implementation
+
+```php
+<?php
+use ByJG\Session\SessionConfig;
+use ByJG\Session\JwtSession;
+
+try {
+    $config = (new SessionConfig('example.com'))
+        ->withSecret('your-base64url-encoded-secret')
+        ->withTimeoutMinutes(30)
+        ->withCookie('.example.com', '/');
+
+    $handler = new JwtSession($config);
+    session_set_save_handler($handler, true);
+    session_start();
+
+    // Use $_SESSION as normal
+    $_SESSION['user_id'] = 123;
+
+} catch (JwtSessionException $e) {
+    // Handle exception
+    error_log('Session error: ' . $e->getMessage());
+}
+```
+
+### With Automatic Handler Replacement
+
+```php
+<?php
+$config = (new SessionConfig('example.com'))
+    ->withSecret('your-base64url-encoded-secret')
+    ->replaceSessionHandler(true); // Automatically starts session
+
+$handler = new JwtSession($config);
+
+// Session is already started, use $_SESSION directly
+$_SESSION['user_id'] = 123;
+```