prisma-php 0.0.10 → 0.0.12

package/dist/docs/error-handling.md

@@ -1,6 +1,6 @@
 ---
 title: Error Handling
-description: Learn how to handle expected errors and uncaught exceptions in Prisma PHP.
+description: Learn how Prisma PHP handles expected errors and uncaught exceptions so AI agents can keep validation failures separate from crashes.
 related:
   title: API Reference
   description: Learn more about the features mentioned on this page by reading the Prisma PHP docs.
@@ -17,7 +17,19 @@ Errors in Prisma PHP can be thought of in two broad categories:
 1. **Expected errors** — validation failures, missing records, failed form submissions, or known request problems
 2. **Unexpected errors** — uncaught exceptions, fatal errors, parse errors, or framework-level failures
 
-Prisma PHP’s documented error model is centered around the `ErrorHandler` class, which acts as the application safety net. It captures exceptions, fatal errors, and parse errors, then converts them into structured responses depending on the request context. For AJAX-style requests it can return JSON; for browser rendering it can show a richer diagnostic UI. citeturn0view0
+Prisma PHP’s documented error model is centered around the `ErrorHandler` class, which acts as the application safety net. It captures exceptions, fatal errors, and parse errors, then converts them into structured responses depending on the request context. For AJAX-style requests it can return JSON; for browser rendering it can show a richer diagnostic UI.
+
+If a task involves expected validation failures, missing records, `Boom` responses, `error.php`, `not-found.php`, or uncaught exceptions, AI agents should read this page first and keep routine failures separate from true crashes.
+
+## AI rule: read the error-handling docs first
+
+Before generating Prisma PHP error flows, use this order:
+
+1. Decide whether the failure is expected or unexpected.
+2. Use `PP\Validator` and structured return values for expected input problems.
+3. Use `Boom`, `error.php`, `not-found.php`, or `ErrorHandler` for request and app-level error behavior.
+4. Keep `route.php`, `pp.fetchFunction(...)`, and form responses explicit instead of turning routine validation into exceptions.
+5. Read `validator.md` and `route-handlers.md` when the error starts from request validation.
 
 ## Handling expected errors
 
@@ -197,7 +209,7 @@ The docs describe `ErrorHandler` as the safety net for the application. It captu
 
 - exceptions
 - fatal errors
-- parse errors citeturn0view0
+- parse errors
 
 This makes it the Prisma PHP equivalent of a central application error boundary, but implemented at the PHP framework level rather than with React client components.
 
@@ -206,13 +218,13 @@ This makes it the Prisma PHP equivalent of a central application error boundary,
 Prisma PHP’s `ErrorHandler` automatically detects the request context and chooses the appropriate output format. The docs explicitly say it can return:
 
 - a JSON payload for AJAX requests
-- a rich diagnostic UI for browser requests citeturn0view0
+- a rich diagnostic UI for browser requests
 
 This is one of the biggest differences from Next.js. Instead of defining client-side error boundaries with `error.js`, Prisma PHP handles failures centrally on the server and formats the response according to the request type.
 
 ## Rich diagnostics
 
-The Prisma PHP docs emphasize that `ErrorHandler` does more than show a generic PHP crash page. It can generate context-aware diagnostics for framework-specific failures. citeturn0view0
+The Prisma PHP docs emphasize that `ErrorHandler` does more than show a generic PHP crash page. It can generate context-aware diagnostics for framework-specific failures.
 
 ### Component validation diagnostics
 
@@ -221,7 +233,7 @@ When a component receives invalid props, the docs say the error UI can show:
 - the specific component name
 - the invalid property
 - quick fixes such as adding a missing public property
-- a list of currently available props citeturn0view0
+- a list of currently available props
 
 ### Template compilation diagnostics
 
@@ -229,7 +241,7 @@ When the template engine fails to parse a file, the docs say the error UI can:
 
 - identify syntax errors in PulsePoint-specific tags
 - highlight the specific line in the view file
-- provide suggestions on how to correct the syntax citeturn0view0
+- provide suggestions on how to correct the syntax
 
 This means Prisma PHP’s error page is intended to be an actionable developer tool, not only a fallback screen.
 
@@ -241,7 +253,7 @@ Prisma PHP allows you to override the default error output by creating:
 APP_PATH . '/error.php'
 ```
 
-The docs state that if this file exists, `ErrorHandler` will render it inside your main layout wrapper instead of using the default output. citeturn0view0
+The docs state that if this file exists, `ErrorHandler` will render it inside your main layout wrapper instead of using the default output.
 
 That makes `error.php` the main file convention for customizing browser-visible application errors.
 
@@ -256,9 +268,9 @@ Example:
 
 ## Output buffering behavior
 
-The docs note an important implementation detail: when a fatal error occurs, the handler calls `ob_end_clean()` to remove any partial HTML that was generated before the crash. This prevents broken layouts or incomplete output from being rendered. citeturn0view0
+The docs note an important implementation detail: when a fatal error occurs, the handler calls `ob_end_clean()` to remove any partial HTML that was generated before the crash. This prevents broken layouts or incomplete output from being rendered.
 
-The docs also mention that if you are debugging with `echo` or `var_dump` immediately before a crash, you may need to temporarily disable this buffer cleaning in `modifyOutputLayoutForError` in order to see that debug output. citeturn0view0
+The docs also mention that if you are debugging with `echo` or `var_dump` immediately before a crash, you may need to temporarily disable this buffer cleaning in `modifyOutputLayoutForError` in order to see that debug output.
 
 ## Key methods
 
@@ -272,15 +284,15 @@ Registers:
 - `register_shutdown_function`
 - `set_error_handler`
 
-The docs say this is usually called in `bootstrap.php`. citeturn0view0
+The docs say this is usually called in `bootstrap.php`.
 
 ### `checkFatalError(): void`
 
-Manually checks `error_get_last()`. The docs describe this as useful for catching shutdown-time errors that are not regular exceptions. citeturn0view0
+Manually checks `error_get_last()`. The docs describe this as useful for catching shutdown-time errors that are not regular exceptions.
 
 ### `formatExceptionForDisplay(Throwable $e): string`
 
-Formats an exception into the rich HTML diagnostic output. The docs say it determines whether the error is a standard PHP exception or a specific PulsePoint framework error. citeturn0view0
+Formats an exception into the rich HTML diagnostic output. The docs say it determines whether the error is a standard PHP exception or a specific PulsePoint framework error.
 
 ## Bootstrap registration
 
@@ -315,7 +327,7 @@ try {
 }
 ```
 
-This is useful when you want to catch an exception yourself but still use the framework’s standard rich diagnostic output. citeturn0view0
+This is useful when you want to catch an exception yourself but still use the framework’s standard rich diagnostic output.
 
 ## `index.php` vs `route.php` error handling
 
@@ -323,7 +335,7 @@ Error handling in Prisma PHP still follows the route model:
 
 - in `index.php`, errors usually affect rendered page output
 - in `route.php`, errors usually affect JSON or direct handler responses
-- the `ErrorHandler` adapts the response format based on request context citeturn0view0
+- the `ErrorHandler` adapts the response format based on request context
 
 For full-stack projects, expected user-facing problems should usually be handled gracefully in `index.php` or in direct function responses. For API-style routes, structured JSON error responses are usually the right choice for expected failures. Uncaught exceptions should be left to the framework-level `ErrorHandler`.
 
@@ -343,14 +355,14 @@ The main difference is that Prisma PHP’s documented error handling is server-d
 
 ## Good to know
 
-- Prisma PHP’s documented error system is `ErrorHandler`. citeturn0view0
-- It captures exceptions, fatal errors, and parse errors. citeturn0view0
-- It automatically switches output based on request context. citeturn0view0
-- AJAX-style requests can receive JSON errors. citeturn0view0
-- Browser requests can receive a rich diagnostic UI. citeturn0view0
-- You can override the default error view with `APP_PATH . '/error.php'`. citeturn0view0
-- Fatal-error handling clears partial output with `ob_end_clean()`. citeturn0view0
-- `registerHandlers()` is usually called in `bootstrap.php`. citeturn0view0
+- Prisma PHP’s documented error system is `ErrorHandler`.
+- It captures exceptions, fatal errors, and parse errors.
+- It automatically switches output based on request context.
+- AJAX-style requests can receive JSON errors.
+- Browser requests can receive a rich diagnostic UI.
+- You can override the default error view with `APP_PATH . '/error.php'`.
+- Fatal-error handling clears partial output with `ob_end_clean()`.
+- `registerHandlers()` is usually called in `bootstrap.php`.
 
 ## Validation vs unexpected failures
 

package/dist/docs/fetching-data.md

@@ -1,6 +1,6 @@
 ---
 title: Fetching Data
-description: Learn how to fetch and stream data in Prisma PHP using `pp.fetchFunction`, `#[Exposed]`, page handlers, SSE responses, and route handlers.
+description: Learn how AI agents should fetch and stream data in Prisma PHP using `pp.fetchFunction`, `#[Exposed]`, page handlers, SSE responses, and route handlers.
 related:
   title: API Reference
   description: Learn more about the features mentioned in this page by reading the Prisma PHP docs.
@@ -14,6 +14,8 @@ related:
 
 This page will walk you through how you can fetch and stream data in Prisma PHP, when to use `pp.fetchFunction(...)`, when to use `index.php`, when to use `route.php`, and how to validate incoming data correctly on the PHP side.
 
+If a task involves page-local interactivity, exposed PHP functions, streamed responses, or deciding between `index.php` and `route.php`, AI agents should read this page first and keep the interaction model aligned with Prisma PHP.
+
 Prisma PHP has a different mental model from Next.js. Instead of focusing on React Server Components, Suspense-driven HTML streaming, and client data libraries, Prisma PHP gives you direct function invocation from the frontend to PHP, plus file-based routing for page UI and direct route handlers.
 
 When using `pp.fetchFunction(...)`, the PHP function must be explicitly exposed with `#[Exposed]`. Functions are private by default, so a non-exposed function cannot be called from the client.

package/dist/docs/get-started-ia.md

@@ -0,0 +1,482 @@
+---
+title: AI Integration
+description: Build chat, assistant, and streamed AI features in Prisma PHP with PulsePoint, pp.fetchFunction(...), PP\Validator, and MCP when you need agent-facing tools.
+related:
+  title: Related docs
+  description: Read the core Prisma PHP docs that support provider-backed AI UIs, streaming, and agent tooling.
+  links:
+    - /docs/env
+    - /docs/fetch-function
+    - /docs/php-validator
+    - /docs/pulsepoint
+    - /docs/prisma-php-ai-mcp
+    - /docs/websocket-chat-app
+---
+
+Prisma PHP is a good fit for AI features, but the right Prisma PHP pattern depends on what you are actually building.
+
+If a task involves provider-backed chat, prompt forms, streamed output, assistant panels, or deciding between page-local AI, websocket, and MCP, AI agents should read this page first and keep the implementation aligned with the installed Prisma PHP docs.
+
+For a normal user-facing chat box, assistant panel, prompt form, streamed summary, or similar page-local AI feature, the recommended Prisma PHP approach is:
+
+1. render the UI in `index.php`
+2. keep browser-side interactivity in **PulsePoint**
+3. call backend PHP with **`pp.fetchFunction(...)`**
+4. mark callable PHP functions with **`#[Exposed]`**
+5. validate and normalize incoming data with **`PP\Validator`**
+6. stream incremental output by **yielding** from PHP when the provider supports streaming
+
+That keeps the **frontend reactive** while keeping the **AI call, validation, secrets, and business logic on the PHP side**.
+
+Do **not** default to `route.php` for page-local chat or assistant UI just because AI is involved. In Prisma PHP, `route.php` is still useful, but it is the better fit for standalone APIs, webhooks, third-party integrations, or endpoints that must exist independently of the current page.
+
+If the real goal is to expose **agent-callable tools** instead of a user chat interface, read `mcp.md` and the official `prisma-php-ai-mcp` docs. MCP is about serving tools to agents; it is not the default answer for a page-local chat box.
+
+## The default AI architecture in Prisma PHP
+
+When the user is building a normal AI feature inside a Prisma PHP app, AI should usually prefer this stack:
+
+1. `index.php` for the route UI
+2. PulsePoint for browser-side state
+3. `pp.fetchFunction(...)` for frontend-to-PHP RPC
+4. `#[Exposed]` for callable PHP functions
+5. `PP\Validator` for server-side validation
+6. streamed `yield` responses for incremental assistant output
+
+This is the right default for:
+
+- single-user chat pages
+- assistant sidebars
+- prompt forms
+- streamed summaries
+- content generation tools
+- classification or extraction actions
+- AI-backed search or suggestion panels
+- route-local progress logs
+
+Reserve `route.php` for cases where the endpoint must be called without the page, and reserve websocket-based transport for cases where you need true server push, multi-user realtime chat, or presence-style features.
+
+## Pick the right AI surface
+
+Prisma PHP has three different AI-related surfaces, and they should not be mixed up.
+
+### 1. User-facing AI in a page
+
+Use this when a human is interacting with a Prisma PHP page.
+
+Default stack:
+
+- `index.php`
+- PulsePoint
+- `pp.fetchFunction(...)`
+- `#[Exposed]`
+- `PP\Validator`
+
+This is the default for chat, prompt forms, streamed output, inline assistants, or route-local AI actions.
+
+### 2. Standalone AI endpoint
+
+Use `route.php` when the request should exist independently of the rendered page.
+
+Examples:
+
+- webhooks
+- provider callbacks
+- public JSON APIs
+- integration endpoints
+- non-UI automation calls
+
+### 3. Agent-facing tools
+
+Use MCP when an external agent should call business actions in your app.
+
+Read:
+
+- `mcp.md`
+- official `prisma-php-ai-mcp`
+- official `ai-tools`
+
+### Quick rule of thumb
+
+- user chat box on a page -> `index.php` + PulsePoint + `pp.fetchFunction(...)`
+- endpoint with no page dependency -> `route.php`
+- tools for agents -> MCP
+
+## Install an AI client
+
+Prisma PHP is intentionally unopinionated about AI providers. You can use OpenAI, Anthropic, Groq, or another PHP SDK that fits your application.
+
+For OpenAI-compatible providers, a common starting point is:
+
+```bash package="composer"
+composer require openai-php/client
+```
+
+Use the provider package that matches your model host, but keep the Prisma PHP architecture the same: the browser calls PHP, and PHP talks to the model provider.
+
+## Configure secrets in `.env`
+
+Keep provider secrets on the server side.
+
+Example:
+
+```dotenv
+OPENAI_API_KEY="sk-..."
+OPENAI_MODEL="gpt-4o-mini"
+```
+
+Do **not** push provider API keys into PulsePoint state or browser-side JavaScript.
+When reading these values in PHP, prefer `PP\Env` over raw `getenv()` so defaults and typed access stay consistent with Prisma PHP's env helper.
+
+## Recommended non-streaming chat pattern
+
+For a simple AI response, keep the entire route in `index.php`, expose one PHP function, validate the prompt on the PHP side, and call the provider there.
+
+```php filename="src/app/chat/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Env;
+use PP\MainLayout;
+use PP\Rule;
+use PP\Validator;
+
+MainLayout::$title = 'AI Chat';
+MainLayout::$description = 'Chat with a provider from Prisma PHP using PulsePoint and pp.fetchFunction(...).';
+
+#[Exposed]
+function sendChatMessage($data)
+{
+    $message = Validator::string($data->message ?? '');
+    $result = Validator::withRules(
+        $message,
+        Rule::required()->min(1)->max(4000)
+    );
+
+    if ($result !== true) {
+        return [
+            'success' => false,
+            'errors' => [
+                'message' => $result,
+            ],
+        ];
+    }
+
+    $client = \OpenAI::client(Env::string('OPENAI_API_KEY', ''));
+    $model = Env::string('OPENAI_MODEL', 'gpt-4o-mini');
+
+    $response = $client->chat()->create([
+        'model' => $model,
+        'messages' => [
+            ['role' => 'system', 'content' => 'You are a helpful Prisma PHP assistant.'],
+            ['role' => 'user', 'content' => $message],
+        ],
+    ]);
+
+    return [
+        'success' => true,
+        'errors' => [],
+        'assistant' => [
+            'role' => 'assistant',
+            'content' => trim($response->choices[0]->message->content ?? ''),
+        ],
+    ];
+}
+?>
+
+<section pp-component="chat-page">
+    <header>
+        <h1>AI Chat</h1>
+        <p>Send a prompt from PulsePoint and keep the provider call in PHP.</p>
+    </header>
+
+    <div>
+        <template pp-for="(item, index) in messages">
+            <article key="{`${item.role}-${index}`}">
+                <strong>{item.role}</strong>
+                <p>{item.content}</p>
+            </article>
+        </template>
+    </div>
+
+    <form onsubmit="event.preventDefault(); submitMessage()">
+        <textarea value="{draft}" oninput="setDraft(event.target.value)"></textarea>
+        <p hidden="{!error}">{error}</p>
+        <button type="submit" disabled="{loading}">Send</button>
+    </form>
+
+    <script>
+        const [draft, setDraft] = pp.state('');
+        const [messages, setMessages] = pp.state([]);
+        const [error, setError] = pp.state('');
+        const [loading, setLoading] = pp.state(false);
+
+        async function submitMessage() {
+            const text = draft.trim();
+
+            if (!text || loading) {
+                return;
+            }
+
+            setError('');
+            setDraft('');
+            setMessages((current) => [...current, { role: 'user', content: text }]);
+            setLoading(true);
+
+            try {
+                const response = await pp.fetchFunction('sendChatMessage', { message: text });
+
+                if (!response.success) {
+                    setError(response.errors?.message ?? 'Message failed.');
+                    return;
+                }
+
+                setMessages((current) => [...current, response.assistant]);
+            } catch (error) {
+                setError(error.message || 'Request failed.');
+            } finally {
+                setLoading(false);
+            }
+        }
+    </script>
+</section>
+```
+
+Why this pattern is preferred:
+
+- the route UI stays in `index.php`
+- PulsePoint owns the browser state
+- the provider call stays in PHP
+- secrets stay on the server
+- `Validator` remains the authoritative validation layer
+- the route avoids extra endpoint boilerplate when the action belongs to the page
+
+## Recommended streaming chat pattern
+
+For streamed assistant output, keep the same architecture and change only the backend response shape: make the exposed PHP function **yield** chunks.
+
+That gives you incremental SSE delivery through `pp.fetchFunction(...)` without hand-writing a separate transport layer for normal assistant output.
+
+```php filename="src/app/chat/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Env;
+use PP\Rule;
+use PP\Validator;
+
+#[Exposed]
+function streamChatMessage($data)
+{
+    $message = Validator::string($data->message ?? '');
+    $result = Validator::withRules(
+        $message,
+        Rule::required()->min(1)->max(4000)
+    );
+
+    if ($result !== true) {
+        yield [
+            'type' => 'error',
+            'message' => $result,
+        ];
+        return;
+    }
+
+    $client = \OpenAI::client(Env::string('OPENAI_API_KEY', ''));
+    $model = Env::string('OPENAI_MODEL', 'gpt-4o-mini');
+
+    $stream = $client->chat()->createStreamed([
+        'model' => $model,
+        'messages' => [
+            ['role' => 'system', 'content' => 'You are a helpful Prisma PHP assistant.'],
+            ['role' => 'user', 'content' => $message],
+        ],
+    ]);
+
+    foreach ($stream as $response) {
+        $delta = $response->choices[0]->delta->content ?? '';
+
+        if ($delta !== '') {
+            yield [
+                'type' => 'chunk',
+                'chunk' => $delta,
+            ];
+        }
+    }
+}
+```
+
+If your provider uses a different streaming API, keep the Prisma PHP shape the same:
+
+1. validate in PHP first
+2. start the provider stream in PHP
+3. loop over provider deltas
+4. yield strings or arrays back to the client
+
+### Client-side streaming with PulsePoint
+
+```html
+<script>
+    const [draft, setDraft] = pp.state('');
+    const [messages, setMessages] = pp.state([]);
+    const [error, setError] = pp.state('');
+    const [streaming, setStreaming] = pp.state(false);
+
+    async function sendStream() {
+        const text = draft.trim();
+
+        if (!text || streaming) {
+            return;
+        }
+
+        setError('');
+        setDraft('');
+        setStreaming(true);
+        setMessages((current) => [
+            ...current,
+            { role: 'user', content: text },
+            { role: 'assistant', content: '' },
+        ]);
+
+        try {
+            await pp.fetchFunction(
+                'streamChatMessage',
+                { message: text },
+                {
+                    onStream(data) {
+                        if (data.type === 'error') {
+                            setError(data.message || 'Invalid message.');
+                            return;
+                        }
+
+                        const delta = data.chunk || '';
+
+                        if (delta === '') {
+                            return;
+                        }
+
+                        setMessages((current) => {
+                            if (current.length === 0) {
+                                return current;
+                            }
+
+                            const next = current.slice();
+                            const last = next[next.length - 1];
+
+                            next[next.length - 1] = {
+                                ...last,
+                                content: `${last.content}${delta}`,
+                            };
+
+                            return next;
+                        });
+                    },
+                    onStreamError(error) {
+                        setError(error.message || 'Stream failed.');
+                    },
+                }
+            );
+        } finally {
+            setStreaming(false);
+        }
+    }
+</script>
+```
+
+Important streaming rule:
+
+- do not wait for one final JSON object to render the reply
+- update the UI from `onStream`
+- use `onStreamError` and `onStreamComplete` for stream lifecycle handling
+
+For the current SSE behavior and low-level streaming helpers, read `fetching-data.md`.
+
+## Validate everything on the PHP side
+
+When building AI features, do not trust browser-side checks as the final source of truth.
+
+Use this split:
+
+- PulsePoint for local UX state
+- `pp.fetchFunction(...)` for calling PHP
+- `PP\Validator` for sanitization and casting
+- `Validator::withRules(...)` for business rules
+- structured return values for expected validation failures
+
+Good server-side validation targets include:
+
+- prompt text
+- prompt length
+- selected model name
+- message arrays or prior history
+- temperature or option values
+- tool selection input
+- database IDs tied to retrieval or conversation threads
+
+If you are sending prior messages or advanced options back to PHP, validate those values before they are stored, queried against the database, or forwarded to the provider.
+
+## Conversation state and persistence
+
+For small page-local chat flows, PulsePoint can hold the visible message list while PHP handles the provider call.
+
+When you need durable chat history or retrieval-backed context:
+
+- load and store conversation records on the PHP side
+- use Prisma ORM from PHP, not from the browser
+- validate inbound message payloads before persistence
+- shape the final provider request in PHP, not in client-side JavaScript
+
+That keeps the conversation contract authoritative on the server.
+
+## SSE vs websocket vs MCP
+
+These three features solve different problems.
+
+### Use streamed `pp.fetchFunction(...)` when
+
+- the user triggered a request from the current page
+- the assistant response should appear incrementally
+- the page owns the request lifecycle
+- normal request-response semantics are still correct
+
+This is the default for AI text streaming.
+
+### Use websocket when
+
+- the server must push updates without a fresh page request
+- multiple users must see shared realtime changes
+- you need presence, rooms, or bidirectional messaging
+
+Read `websocket.md` when that is the actual requirement.
+
+### Use MCP when
+
+- an external agent needs callable tools
+- the goal is tool exposure, not page-local chat UI
+- you want agent workflows to query your app or database
+
+Read `mcp.md` when that is the actual requirement.
+
+## When `route.php` is still correct
+
+`route.php` still makes sense for AI-related work when:
+
+- the endpoint must be called from outside the current page
+- the request is an integration or webhook
+- you are exposing a standalone API
+- the response is not part of a page-local interactive workflow
+
+For example, provider webhooks, background callbacks, or public machine-facing AI endpoints are reasonable `route.php` use cases.
+
+What should change is the **default assumption**: a chat screen inside a Prisma PHP page should usually start with `index.php` + PulsePoint + `pp.fetchFunction(...)`, not with a separate endpoint first.
+
+## Good to know
+
+- Prisma PHP is unopinionated about AI SDK choice.
+- For page-local AI UI, keep the browser reactive and keep the provider call in PHP.
+- Use `#[Exposed]` for any PHP function called from `pp.fetchFunction(...)`.
+- Use `PP\Validator` as the default validation layer for AI request payloads.
+- Stream assistant replies by yielding from PHP and consuming chunks with `onStream`.
+- Prefer `route.php` only when the endpoint must exist independently of the page.
+- Use websocket for true server push or multi-user realtime behavior.
+- Use MCP for agent-facing tools, not as the default transport for a page-local chat box.