prisma-php 0.0.10 → 0.0.11

package/dist/docs/email.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Read the official Prisma PHP email docs before generating or editing mail flows.
   links:
+    - /docs/env
     - /docs/email-get-started
     - /docs/env-file
     - /docs/php-validator
@@ -33,6 +34,7 @@ Do not assume another framework's mailer abstraction applies directly.
 ## Read this doc when you need
 
 - **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, `sendEmail`, HTML email, text email, `from`, `to`, `cc`, `bcc`, `replyTo`, or attachments** → official `email-get-started`
+- **custom runtime reads of SMTP values, mail feature flags, or `.env` loading boundaries** → `env.md` plus `email.md`
 - **contact forms or page-local email sends via PulsePoint** → `fetching-data.md` plus `email.md`
 - **direct POST handlers or handler-only email routes** → `route-handlers.md` plus `email.md`
 - **validation of recipient, sender, or contact-form input** → `validator.md` plus `email.md`
@@ -44,6 +46,8 @@ The Prisma PHP mailer is a PHPMailer wrapper with a fluent API.
 
 The constructor initializes a `PHPMailer` instance, forces `UTF-8`, configures SMTP transport from `.env`, and applies a default sender when `MAIL_FROM` is present and valid.
 
+When a task goes beyond the built-in mailer workflow and needs direct runtime config access, AI should route that part through `PP\Env` and `env.md` instead of adding ad hoc `getenv()` parsing.
+
 AI should preserve that model instead of replacing it with undocumented helpers or raw `mail()` calls.
 
 ## Exact core file location
@@ -82,6 +86,8 @@ Behavior notes:
 
 AI should update `.env` whenever email support is introduced and should not hardcode SMTP credentials in route files or components.
 
+If application code needs to read related mail settings directly, prefer `PP\Env` typed helpers so defaults and empty-value handling stay consistent with the Prisma PHP env implementation.
+
 ## Public fluent methods AI should know
 
 The current `Mailer` class exposes:

package/dist/docs/env.md

@@ -0,0 +1,224 @@
+---
+title: Env
+description: Learn how Prisma PHP reads environment values with PP\Env so AI agents can use typed env helpers, understand the .env loading boundary, and avoid ad hoc getenv parsing.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP env docs before generating or editing configuration access code.
+  links:
+    - /docs/env
+    - /docs/env-file
+    - /docs/project-structure
+    - /docs/prisma-php-ai-mcp
+    - /docs/websocket-get-started
+---
+
+Prisma PHP environment access should follow the documented `PP\Env` model, not ad hoc parsing copied from Laravel config helpers, Symfony parameter bags, or repeated raw `getenv()` checks scattered across the codebase.
+
+If a task involves `.env`, environment variables, feature flags, host and port values, timezones, API keys, numeric limits, or typed runtime configuration reads, AI agents should read the relevant Prisma PHP env docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the Env docs first
+
+Before generating, editing, or reviewing environment-related code, use this order:
+
+1. Read `./prisma-php.json` when the task is in a generated Prisma PHP app.
+2. Read the installed local docs in `node_modules/prisma-php/dist/docs`.
+3. Read this `env.md` file.
+4. Inspect the current `.env` file or deployment environment when the task depends on real values.
+5. Inspect the bootstrap or server entry file that loads or consumes environment variables.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's env loader or configuration container applies directly.
+
+## Read this doc when you need
+
+- **`.env`, environment variables, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, or `Env::int(...)`** -> official `env`
+- **`.env` file placement, runtime loading, or dotenv bootstrapping** -> official `env-file` plus `env.md`
+- **runtime settings for websocket or MCP servers** -> `websocket.md` or `mcp.md` plus `env.md`
+- **SMTP credentials, sender defaults, or provider secrets** -> `email.md` or `get-started-ia.md` plus `env.md`
+- **database connection strings and Prisma datasource config** -> `prisma-php-orm.md` plus `env.md`
+
+## Core Env model AI should follow
+
+Prisma PHP documents environment access around a lightweight helper class:
+
+- `PP\Env` reads values that already exist in the runtime
+- it provides raw access through `get()`
+- it provides typed helpers through `string()`, `bool()`, and `int()`
+- it centralizes default handling instead of repeating parsing logic in multiple files
+
+AI should preserve that model instead of re-implementing manual conversion everywhere.
+
+## Exact core file location
+
+The Prisma PHP core `Env` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/Env.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer an env task, this is the exact core file to review.
+
+## Resolution order and normalization
+
+The current `Env` implementation resolves values in this order:
+
+1. `getenv()`
+2. `$_ENV`
+3. `$_SERVER`
+
+Normalization behavior:
+
+- booleans become `'true'` or `'false'`
+- scalar values are cast to strings
+- unsupported types such as arrays or objects return `null`
+
+That means `Env` is safe for central configuration reads, but it is not a substitute for validating arbitrary request payloads.
+
+## Public methods AI should know
+
+The current `Env` class exposes:
+
+- `static get(string $key): ?string`
+- `static string(string $key, string $default = ''): string`
+- `static bool(string $key, bool $default = false): bool`
+- `static int(string $key, int $default = 0): int`
+
+Do not invent undocumented helper methods when this public surface already covers the common Prisma PHP configuration workflow.
+
+## Method behavior summary
+
+Use `get()` when you want the raw nullable string value and plan to handle parsing yourself.
+
+Use `string()` for values such as:
+
+- app names
+- timezones
+- URLs
+- API keys
+- driver names
+
+Behavior note:
+
+- `string()` returns the default when the value is missing or when it is an empty string
+
+Use `bool()` for values such as:
+
+- feature flags
+- verbose logging toggles
+- JSON response toggles
+- debug mode switches
+
+Accepted boolean-like values are case-insensitive:
+
+- `true` and `false`
+- `1` and `0`
+- `yes` and `no`
+- `on` and `off`
+
+Behavior note:
+
+- invalid boolean strings fall back to the provided default
+
+Use `int()` for values such as:
+
+- port numbers
+- timeouts
+- retry limits
+- upload limits
+- cache durations
+
+Behavior note:
+
+- `int()` only converts numeric values; otherwise it returns the default
+
+## Important `.env` boundary
+
+`PP\Env` does not parse a `.env` file by itself.
+
+It only reads values that are already present in the PHP runtime. When Prisma PHP needs to load `.env` values from disk first, the bootstrap or server entry typically does that explicitly, for example with `Dotenv::createImmutable(...)->safeLoad()`.
+
+AI should keep that boundary clear:
+
+- use dotenv loading when the runtime has not loaded `.env` yet
+- use `PP\Env` when reading values after the environment is available
+- do not describe `PP\Env` as a standalone dotenv parser
+
+## Recommended example patterns
+
+### Bootstrap runtime settings
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Dotenv\Dotenv;
+use PP\Env;
+
+if (file_exists(DOCUMENT_PATH . '/.env')) {
+    Dotenv::createImmutable(DOCUMENT_PATH)->safeLoad();
+}
+
+date_default_timezone_set(Env::string('APP_TIMEZONE', 'UTC'));
+
+$showErrors = Env::bool('SHOW_ERRORS', false);
+$appName = Env::string('APP_NAME', 'Prisma PHP App');
+$appPort = Env::int('APP_PORT', 3000);
+```
+
+### Fail early for required secrets
+
+```php
+<?php
+
+use PP\Env;
+
+$openAiKey = Env::string('OPENAI_API_KEY', '');
+
+if ($openAiKey === '') {
+    throw new Exception('OPENAI_API_KEY is missing.');
+}
+```
+
+### Inspect a raw value directly
+
+```php
+<?php
+
+use PP\Env;
+
+$driver = Env::get('DB_DRIVER');
+
+if ($driver === null) {
+    $driver = 'mysql';
+}
+```
+
+## Example environment values
+
+```dotenv
+APP_NAME="Prisma PHP"
+APP_TIMEZONE="UTC"
+APP_PORT=3000
+SHOW_ERRORS=true
+OPENAI_API_KEY="sk-..."
+DB_DRIVER="mysql"
+MAX_UPLOAD_MB=20
+```
+
+## Common patterns AI should preserve
+
+- prefer `string()`, `bool()`, and `int()` over repeated manual parsing
+- always provide a sensible default for optional settings
+- validate critical secrets explicitly and fail early when they are missing
+- keep configuration reads near bootstrap or server setup when possible
+- pass resolved configuration into the parts of the system that need it instead of re-reading the same keys everywhere
+
+## AI rules for env tasks
+
+- read `env.md` before generating environment-related Prisma PHP code
+- prefer `PP\Env` over ad hoc `getenv()` parsing when working inside documented Prisma PHP code paths
+- keep secrets and deployment values in `.env` or the runtime environment, not hardcoded in route files or components
+- remember that `PP\Env` reads already-loaded values and does not load `.env` on its own
+- use defaults for optional settings and explicit checks for required secrets
+- inspect `vendor/tsnc/prisma-php/src/Env.php` only when the docs and current app code do not answer the task

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.