prisma-php 0.0.1

package/dist/docs/01-getting-started/authentication.md

@@ -0,0 +1,280 @@
+---
+title: Authentication
+description: Learn how Prisma PHP authentication works so AI agents can generate route protection, sessions, RBAC, credentials auth, and social auth code using the documented framework model.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP authentication docs before generating or editing auth code.
+  links:
+    - /docs/auth-get-started
+    - /docs/credentials
+    - /docs/state-manager-auth
+    - /docs/fetch-function
+    - /docs/route-php
+    - /docs/php-validator
+---
+
+Prisma PHP authentication should be implemented from the documented Prisma PHP auth model, not from assumptions copied from Laravel guards, NextAuth, Passport, Sanctum, or generic custom JWT middleware.
+
+If a task involves login, registration, route protection, role checks, route privacy defaults, session payload updates, credentials auth, OAuth providers, or auth-aware frontend interactions, AI agents should read the relevant auth docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the auth docs first
+
+Before generating, editing, or reviewing auth-related code, use this order:
+
+1. Read `./prisma-php.json`.
+2. Read the installed local auth docs in `node_modules/prisma-php/dist/docs`.
+3. Read this `authentication.md` file.
+4. Inspect `src/Lib/Auth/AuthConfig.php` when present.
+5. Inspect the current auth-related route tree under `src/app`.
+6. Inspect the Prisma schema and generated ORM classes if the auth flow reads or writes users.
+7. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework’s auth abstractions apply directly.
+
+## Read this doc when you need
+
+- **route privacy defaults, `AuthConfig.php`, JWT session lifecycle, `Auth::signIn(...)`, `Auth::signOut(...)`, `refreshUserSession(...)`, route RBAC, or provider overview** → official `auth-get-started`
+- **email/password registration, login, password hashing, CSRF-aware credential flow, or user/role schema design** → official `credentials`
+- **social login, provider credentials, callback route handling, account linking, or OAuth account schema** → official `state-manager-auth`
+
+## Core auth model AI should follow
+
+Prisma PHP documents authentication around a central auth configuration plus framework-managed session handling.
+
+The official docs describe these major concepts:
+
+- `AuthConfig.php` is the central place for defining route protection strategy and role-based route rules
+- sessions are managed through Prisma PHP auth helpers rather than ad hoc cookie code
+- `Auth::signIn(...)` creates the session payload
+- `Auth::signOut(...)` ends the session and can redirect
+- `refreshUserSession(...)` updates the active session payload when user permissions or profile data change
+- route-level RBAC and function-level access control are separate but complementary concerns
+
+## Security strategy
+
+Prisma PHP supports two top-level route privacy strategies in `src/Lib/Auth/AuthConfig.php`.
+
+### 1. Opt-in privacy (public by default)
+
+Use this model when most routes are public and only a few pages should require login.
+
+Typical fit:
+
+- marketing sites
+- blogs
+- public directories with a small private dashboard
+
+Mental model:
+
+- routes are public by default
+- specific private routes are listed explicitly
+
+### 2. Opt-out privacy (private by default)
+
+Use this model when most routes should require authentication and only a few entry points are public.
+
+Typical fit:
+
+- SaaS dashboards
+- admin panels
+- internal applications
+
+Mental model:
+
+- routes are private by default
+- specific public routes are whitelisted explicitly
+
+## Auth lifecycle
+
+### Sign in
+
+Use `Auth::signIn(...)` after credentials or provider identity are validated.
+
+The session payload should contain the user data your app needs for identity and authorization decisions, commonly including:
+
+- `id`
+- `role`
+
+Do not invent a separate session writer when the framework already documents `Auth::signIn(...)`.
+
+### Sign out
+
+Use `Auth::signOut(...)` to destroy the session and invalidate the client cookie.
+
+When the flow needs a post-logout redirect, use the documented redirect argument instead of custom manual cookie clearing.
+
+### Live session refresh
+
+Use `refreshUserSession(...)` when a currently signed-in user’s auth payload must change immediately, such as:
+
+- role promotion or demotion
+- profile data updates included in the auth payload
+- account status changes that should take effect without forcing a new login
+
+Do not force logout/login loops for cases the framework already handles with a silent session refresh.
+
+## Access control model
+
+Prisma PHP has at least two auth protection layers that AI should keep separate.
+
+### Route-level protection
+
+Use auth config to protect entire routes or route groups.
+
+This is the right place for:
+
+- dashboard-only pages
+- admin sections
+- authenticated profile/account pages
+- public route allowlists in private-default apps
+
+### Function-level protection
+
+Use `#[Exposed(allowedRoles: [...])]` when frontend code calls PHP functions directly and specific roles must be enforced at the function boundary.
+
+This is the right place for:
+
+- destructive admin-only actions
+- privileged inline mutations
+- page-local operations triggered from PulsePoint UIs
+
+Do not rely only on frontend hiding or route visibility when a backend callable function still needs authorization.
+
+## Role model
+
+The official auth docs describe roles as type-safe and defined in auth configuration.
+
+AI should preserve the project’s existing role vocabulary and avoid inventing mixed casing or alternate role names unless the user explicitly asks for them.
+
+Examples commonly shown in docs:
+
+- `Admin`
+- `User`
+
+When backend functions are protected with `#[Exposed(allowedRoles: [...])]`, keep those role names aligned with the same project role model.
+
+## Credentials authentication
+
+The credentials docs describe the classic email/password flow as a full-stack Prisma PHP pattern where backend logic and form UI can live together in route files.
+
+### Schema expectations
+
+For credentials auth, the docs show a user model with fields such as:
+
+- `email`
+- `password`
+- `emailVerified`
+- role relation fields
+
+The example also includes a `UserRole` model so role names can support RBAC-oriented auth flows.
+
+### Registration pattern
+
+The documented registration flow uses:
+
+- a route such as `src/app/auth/register/index.php`
+- `#[Exposed]` to allow the frontend to call the PHP function directly
+- validation and normalization before persistence
+- password hashing before storing the user
+- a redirect to the login page after successful registration
+
+### Login pattern
+
+The documented login flow uses:
+
+- a route such as `src/app/auth/login/index.php`
+- a user lookup through Prisma ORM
+- `password_verify(...)` for password comparison
+- `Auth::signIn(...)` with the session payload
+- a redirect after successful sign-in
+
+### Validation rule
+
+When generating credentials auth, do not trust raw request data.
+
+For backend validation and normalization, default to Prisma PHP’s validation layer rather than browser-only checks. In this docs set, that means using the documented validation guidance alongside `PP\Validator`-style server validation patterns from the rest of the local docs.
+
+## Social authentication
+
+The social auth docs describe provider-based authentication using framework helpers and provider classes.
+
+### Schema expectations
+
+For provider auth, the docs show:
+
+- a `User` model
+- an `Account` model that stores provider identity and tokens
+- a unique provider/provider-account pairing
+
+This means AI should not generate social auth code without also checking whether the schema already supports provider accounts.
+
+### Environment credentials
+
+Provider credentials belong in `.env` using provider-specific auth keys.
+
+Do not hardcode provider secrets in route files.
+
+### Callback route pattern
+
+The docs describe a dynamic auth handler route that handles both login redirection and callback processing.
+
+Keep the documented route pattern instead of inventing custom callback plumbing.
+
+## Prisma ORM workflow for auth tasks
+
+When the task involves auth schema updates, do not confuse ORM changes with project updates.
+
+Use this order:
+
+1. update `prisma/schema.prisma` as needed
+2. run `npx prisma migrate dev` when the schema changes and the database must be updated
+3. run `npx ppo generate` so generated PHP ORM classes match the schema
+4. then implement the PHP auth flow that depends on those classes
+
+Do **not** use `npx pp update project -y` as the default response to auth schema changes.
+
+## Route placement guidance
+
+Common auth route examples from the official docs include:
+
+- `src/app/auth/register/index.php`
+- `src/app/auth/login/index.php`
+- a dynamic provider callback route under an auth-related segment
+
+If the user asks for a normal auth page, prefer `index.php`.
+
+If the user asks for a direct callback or handler-only route, use the documented dynamic auth handler pattern.
+
+## PulsePoint and auth
+
+When auth UI is interactive, Prisma PHP’s normal full-stack pattern still applies:
+
+- use PulsePoint for local reactive state and UI feedback
+- use `pp.fetchFunction(...)` when the page should call PHP directly
+- expose callable PHP functions with `#[Exposed]`
+- enforce final validation and authorization on the PHP side
+
+Do not replace the documented Prisma PHP auth flow with a custom SPA-only auth architecture unless the user explicitly wants a different design.
+
+## AI rules for auth tasks
+
+- read the auth docs before generating auth code
+- do not invent custom middleware layers when `AuthConfig.php` already defines route protection strategy
+- do not invent alternate session storage when the framework already provides documented auth helpers
+- do not skip schema review for credentials or provider-based auth
+- do not hardcode provider secrets in source code
+- do not rely on frontend checks as the final authorization layer
+- keep route-level protection and function-level protection distinct
+- keep role names aligned with the project’s actual role model
+- when using `#[Exposed]`, add role restrictions for privileged actions when required
+- when schema changes are required, migrate first and generate PHP classes second
+
+## Suggested file name
+
+Use this file name:
+
+```txt
+authentication.md
+```
+
+It is clear, predictable, and consistent with the existing local docs such as `components.md`, `fetching-data.md`, and `route-handlers.md`.

package/dist/docs/01-getting-started/caching.md

@@ -0,0 +1,346 @@
+---
+title: Caching
+description: Learn how to cache pages and responses in Prisma PHP with `CacheHandler`, when to invalidate cached output, and when AI agents should inspect the core cache class for framework-level decisions.
+related:
+  title: Next Steps
+  description: Learn more about the Prisma PHP cache APIs and route-level cache control.
+  links:
+    - /docs/cache-handler
+    - /docs/index-php
+    - /docs/route-php
+    - /docs/pages-and-layouts
+---
+
+Caching is a technique for storing the result of work so that future requests can be served faster without repeating the same database queries and rendering logic.
+
+In Prisma PHP, caching is documented around **`CacheHandler`**, which provides a **file-based cache layer** that can serve **static HTML snapshots** to reduce TTFB (Time To First Byte). Unlike Next.js Cache Components, Prisma PHP’s documented cache model is not based on `use cache`, Suspense streaming, or partial prerendering. It is based on environment settings, route-level overrides, and explicit cache invalidation.
+
+## AI rule: read the cache docs first
+
+Before generating, editing, or reviewing Prisma PHP cache-related code, use this order:
+
+1. Read `./prisma-php.json`.
+2. Read the installed local docs in `node_modules/prisma-php/dist/docs`.
+3. Read this `caching.md` file.
+4. Inspect the current route tree under `src/app`.
+5. Inspect nearby mutation flows that may need cache invalidation.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task clearly.
+
+Do not assume Next.js, Laravel response cache packages, Symfony HTTP cache, or generic PSR cache habits map directly to Prisma PHP.
+
+## Where the core cache file lives
+
+The Prisma PHP cache core file lives in:
+
+```txt
+vendor/tsnc/prisma-php/src/CacheHandler.php
+```
+
+This file is useful when AI needs to make a **more detailed framework-level decision** that is not already answered by the installed docs.
+
+Examples:
+
+- confirming the exact available methods and property names
+- verifying how TTL fallback is resolved internally
+- checking how cache files are named or mapped to URIs
+- understanding how route invalidation is normalized
+- verifying write behavior, locking, and file-system assumptions
+- debugging framework-level cache behavior that looks inconsistent with the docs
+
+For normal app work, prefer the docs first and inspect `CacheHandler.php` only when the task depends on internal behavior.
+
+## Cache decision flow for AI agents
+
+When a task mentions caching, use this decision flow:
+
+1. identify whether the route is a rendered page or a direct handler
+2. decide whether the output is stable enough to cache safely
+3. check whether the task needs a global default or a route-level override
+4. identify which writes or mutations should invalidate cached routes
+5. inspect `CacheHandler.php` only if the docs and current project code still leave important behavior unclear
+
+This keeps AI aligned with documented Prisma PHP behavior instead of inventing cache abstractions from other ecosystems.
+
+## How Prisma PHP caching works
+
+Prisma PHP determines whether to cache a route using the interaction between:
+
+- global `.env` settings
+- route-level `CacheHandler` overrides
+
+The docs describe this as a caching logic matrix:
+
+- if `CACHE_ENABLED="false"` and no route override is set, the route is not cached
+- if `CACHE_ENABLED="false"` and `CacheHandler::$isCacheable = true`, caching is forced for that route
+- if `CACHE_ENABLED="true"` and no route override is set, caching applies by default
+- if `CACHE_ENABLED="true"` and `CacheHandler::$isCacheable = false`, that route is skipped from caching
+
+This means Prisma PHP gives you both a **global cache default** and a **per-route escape hatch**.
+
+## Global configuration
+
+Prisma PHP documents cache defaults through your `.env` file.
+
+```env filename=".env"
+# Enable system-wide caching
+CACHE_ENABLED="true"
+
+# Default TTL (600 = 10 minutes)
+CACHE_TTL="600"
+```
+
+According to the docs, `CACHE_ENABLED` controls whether caching is enabled by default, and `CACHE_TTL` sets the default TTL in seconds.
+
+## Route-level overrides
+
+You can override cache behavior for a specific route in the route entry file or controller logic.
+
+```php filename="src/app/blog/index.php"
+<?php
+
+use PP\CacheHandler;
+
+// Force cache this specific page
+CacheHandler::$isCacheable = true;
+
+// Set a custom TTL in seconds
+CacheHandler::$ttl = 10;
+?>
+```
+
+The docs show `CacheHandler::$isCacheable` for opting a route into or out of caching and `CacheHandler::$ttl` for overriding the default TTL for that route.
+
+## What gets cached
+
+The Prisma PHP docs describe `CacheHandler` as a way to **bypass database queries and view rendering logic by serving static HTML snapshots**. This means the primary documented cache target is the final rendered output for a route, stored as files on disk.
+
+This is the main Prisma PHP equivalent to route-level page caching.
+
+## Serving cached content
+
+The documented API includes:
+
+```php
+CacheHandler::serveCache(string $uri, int $defaultTtl = 600): void
+```
+
+According to the docs, this method attempts to serve a static file for the given URI. If a valid, non-expired cache file exists, it outputs the content and terminates script execution. The docs also note that it checks route-specific TTL first, falls back to the default TTL if no route config exists, and appends an HTML comment showing when the cached copy was generated.
+
+## Basic page-caching example
+
+A typical Prisma PHP page-caching pattern looks like this:
+
+```php filename="src/app/blog/index.php"
+<?php
+
+use PP\CacheHandler;
+use Lib\Prisma\Classes\Prisma;
+
+// Mark this route as cacheable
+CacheHandler::$isCacheable = true;
+
+// Optional route-specific TTL
+CacheHandler::$ttl = 600;
+
+$prisma = Prisma::getInstance();
+
+$posts = $prisma->post->findMany([
+    'orderBy' => [
+        'createdAt' => 'desc',
+    ],
+]);
+
+?>
+
+<ul>
+    <?php foreach ($posts as $post): ?>
+        <li><?= htmlspecialchars($post['title']) ?></li>
+    <?php endforeach; ?>
+</ul>
+```
+
+This is the Prisma PHP equivalent of caching a page’s rendered result rather than caching a React component tree.
+
+## Invalidating cache by route
+
+Prisma PHP documents URI-based invalidation through:
+
+```php
+CacheHandler::invalidateByUri(string|array $uris): void
+```
+
+This method removes cache files for one or more specific routes. The docs note that it accepts leading slashes or plain paths.
+
+Example:
+
+```php filename="src/app/blog/_lib/save-post.php"
+<?php
+
+use PP\CacheHandler;
+
+// Invalidate one route
+CacheHandler::invalidateByUri('/blog');
+
+// Invalidate multiple routes
+CacheHandler::invalidateByUri([
+    '/',
+    '/blog',
+    '/dashboard',
+]);
+```
+
+This is the core Prisma PHP pattern for keeping cached pages fresh after content changes.
+
+## Resetting cache
+
+The docs also describe a lower-level clearing method:
+
+```php
+CacheHandler::resetCache(?string $uri = null): void
+```
+
+According to the docs:
+
+- passing `null` purges all files in the cache directory
+- passing a specific URI deletes the file for that route only
+
+Example:
+
+```php filename="src/app/admin/route.php"
+<?php
+
+use PP\CacheHandler;
+
+// Clear everything
+CacheHandler::resetCache();
+
+// Or clear one route
+CacheHandler::resetCache('/blog');
+```
+
+## Content update workflow
+
+The Prisma PHP docs explicitly recommend invalidating relevant routes after saving dynamic content so users immediately see fresh data.
+
+Their documented example follows this pattern:
+
+1. save to the database
+2. invalidate the related cache URIs
+
+Example:
+
+```php filename="src/app/blog/route.php"
+<?php
+
+use PP\CacheHandler;
+
+function savePost($data)
+{
+    // 1. Save post data
+    // ... database logic here ...
+
+    // 2. Invalidate affected routes
+    CacheHandler::invalidateByUri([
+        '/blog',
+        '/blog/recent',
+    ]);
+
+    return [
+        'success' => true,
+    ];
+}
+```
+
+This is the Prisma PHP equivalent of revalidation after mutation.
+
+## Concurrency and writes
+
+The docs state that `saveCache` uses `LOCK_EX` by default to prevent race conditions when two requests try to write the same cache file at the same time.
+
+That matters most on high-traffic pages where multiple requests may attempt to generate the same cached output simultaneously.
+
+## Cache storage location
+
+Prisma PHP documents cache storage at:
+
+```php
+DOCUMENT_PATH . '/caches'
+```
+
+The docs also note that this directory must be writable by the web server user.
+
+## `index.php` vs `route.php` and caching
+
+In Prisma PHP, your cache choice still follows the route model:
+
+- use `index.php` when caching rendered page output
+- use `route.php` when caching or controlling a direct handler route
+- invalidate by URI when content changes affect one or more routes
+
+For a full-stack project, page-oriented caching will most commonly apply to `index.php` routes, since those are the normal rendered UI entry points. API-style handlers in `route.php` may also use cache logic where appropriate, but their role is different from full page rendering. This route split aligns with Prisma PHP’s documented distinction between `index.php` as the UI entry point and `route.php` as the direct handler entry point.
+
+## Prisma PHP vs Next.js caching mental model
+
+If you are coming from Next.js, the closest mapping is:
+
+| Next.js idea                           | Prisma PHP equivalent                       |
+| -------------------------------------- | ------------------------------------------- |
+| `use cache` on a component or function | Route/page caching with `CacheHandler`      |
+| revalidation after mutation            | `CacheHandler::invalidateByUri(...)`        |
+| clearing cached output                 | `CacheHandler::resetCache(...)`             |
+| config-driven cache defaults           | `.env` with `CACHE_ENABLED` and `CACHE_TTL` |
+
+The biggest difference is that Prisma PHP’s documented model is file-based route output caching, not React component-level caching.
+
+## When to cache
+
+Prisma PHP caching is especially useful for routes where:
+
+- the rendered output is expensive to generate
+- the content does not change on every request
+- the same route is requested often
+- you want to reduce database and rendering work
+
+Examples:
+
+- blog index pages
+- marketing pages
+- dashboards with infrequently changing summaries
+- public landing pages
+- documentation-style content pages
+
+## When not to cache aggressively
+
+Be careful with caching routes that depend heavily on:
+
+- per-user personalization
+- rapidly changing data
+- request-specific conditions
+- authentication-sensitive output
+
+In those cases, route-specific overrides or targeted invalidation are usually safer than broad default caching.
+
+## Practical cache design guidance
+
+A good Prisma PHP cache decision usually looks like this:
+
+- cache public or mostly-static rendered output
+- keep TTL modest when content changes on a schedule
+- invalidate specific URIs after a successful mutation
+- avoid broad global resets unless the change is truly system-wide
+- avoid caching personalized pages unless you are certain the output is safe to share across requests
+
+When uncertain, prefer **targeted invalidation** over aggressive long-lived caching.
+
+## Good to know
+
+- Prisma PHP’s documented cache system is `CacheHandler`.
+- It is a file-based cache layer for serving static HTML snapshots.
+- Global defaults are configured with `.env` using `CACHE_ENABLED` and `CACHE_TTL`.
+- Per-route overrides use `CacheHandler::$isCacheable` and `CacheHandler::$ttl`.
+- Route invalidation uses `CacheHandler::invalidateByUri(...)`.
+- Full resets use `CacheHandler::resetCache(...)`.
+- Cache files are stored in `DOCUMENT_PATH . '/caches'`.
+- Cache writes use `LOCK_EX` for concurrency safety.
+- The core class lives in `vendor/tsnc/prisma-php/src/CacheHandler.php`.
+- Inspect the core file only when the installed docs and project code are not enough for a precise framework-level decision.