prisma-php 0.0.1

package/dist/docs/01-getting-started/error-handling.md

@@ -0,0 +1,359 @@
+---
+title: Error Handling
+description: Learn how to handle expected errors and uncaught exceptions in Prisma PHP.
+related:
+  title: API Reference
+  description: Learn more about the features mentioned on this page by reading the Prisma PHP docs.
+  links:
+    - /docs/error-handler
+    - /docs/route-php
+    - /docs/index-php
+    - /docs/pages-and-layouts
+---
+
+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
+
+## Handling expected errors
+
+## Validation errors are expected errors
+
+Most validation problems should not be treated as crashes.
+
+If the user submits invalid data, that is usually an **expected error**, not an exceptional failure. In those cases:
+
+- sanitize and cast values with `Validator`
+- apply rules with `Validator::withRules(...)`
+- return field-level errors or a structured message
+- only let truly unexpected failures bubble into `ErrorHandler`
+
+This distinction is especially important for:
+
+- `pp.fetchFunction(...)` handlers
+- form submissions
+- `route.php` JSON endpoints
+- inline validation flows in reactive UIs
+
+## Prefer returning validation results instead of throwing
+
+For normal user input, a response like this is usually better than an exception:
+
+```php
+[
+    'success' => false,
+    'errors' => [
+        'email' => 'A valid email address is required.',
+    ],
+]
+```
+
+That shape is easier for PulsePoint UIs, API consumers, and page handlers to render predictably.
+
+Expected errors should usually be handled explicitly in your route logic, function handlers, or forms.
+
+In Prisma PHP, the recommended pattern is generally:
+
+- validate input
+- prefer `PP\Validator` for sanitization, casting, and rule-based checks
+- return a structured response or message
+- avoid letting routine validation failures become fatal exceptions
+
+### Form or direct function example
+
+```php filename="src/app/contact/index.php"
+<?php
+
+use PP\Rule;
+use PP\Validator;
+
+function submitContact($data)
+{
+    $name = Validator::string($data->name ?? '');
+    $email = Validator::email($data->email ?? '');
+
+    $nameResult = Validator::withRules($name, Rule::required()->min(2)->max(80));
+
+    if ($nameResult !== true) {
+        return [
+            'success' => false,
+            'errors' => [
+                'name' => $nameResult,
+            ],
+        ];
+    }
+
+    if ($email === null) {
+        return [
+            'success' => false,
+            'errors' => [
+                'email' => 'A valid email address is required.',
+            ],
+        ];
+    }
+
+    return [
+        'success' => true,
+        'errors' => [],
+        'message' => 'Form submitted successfully.',
+    ];
+}
+```
+
+On the frontend, you can then show the returned message instead of throwing an exception.
+
+### Route handler example
+
+For API-style routes in `route.php`, expected failures can be returned as structured JSON responses.
+
+```php filename="src/app/users/route.php"
+<?php
+
+use PP\Request;
+use PP\Rule;
+use PP\Validator;
+
+$id = Validator::int(Request::$params['id'] ?? null);
+$result = Validator::withRules($id, Rule::required());
+
+if ($result !== true || $id === null) {
+    echo json_encode([
+        'success' => false,
+        'errors' => [
+            'id' => 'A valid user ID is required.',
+        ],
+    ]);
+    exit;
+}
+
+echo json_encode([
+    'success' => true,
+    'id' => $id,
+]);
+```
+
+This is the Prisma PHP equivalent of modeling expected failures as response values instead of uncaught exceptions.
+
+## Handling missing content
+
+For missing content, Prisma PHP provides a dedicated route-level file convention:
+
+- `not-found.php`
+
+Use it when a route or resource should render a not-found UI instead of crashing the application.
+
+Example route structure:
+
+```txt
+src/app/blog/
+├── index.php
+├── not-found.php
+└── [slug]/
+    └── index.php
+```
+
+Example page logic:
+
+```php filename="src/app/blog/[slug]/index.php"
+<?php
+
+use PP\Request;
+use Lib\Prisma\Classes\Prisma;
+
+$slug = Request::$dynamicParams['slug'] ?? null;
+
+$prisma = Prisma::getInstance();
+$post = $prisma->post->findFirst([
+    'where' => [
+        'slug' => $slug,
+    ],
+]);
+
+if (!$post) {
+    include APP_PATH . '/blog/not-found.php';
+    return;
+}
+
+echo "<h1>" . htmlspecialchars($post['title']) . "</h1>";
+```
+
+And the not-found view:
+
+```php filename="src/app/blog/not-found.php"
+<div>404 - Page Not Found</div>
+```
+
+## Handling uncaught exceptions
+
+Unexpected errors should not be silently ignored. Prisma PHP’s `ErrorHandler` is designed to catch these failures and render the right kind of response.
+
+The docs describe `ErrorHandler` as the safety net for the application. It captures:
+
+- exceptions
+- fatal errors
+- parse errors citeturn0view0
+
+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.
+
+## Request-context aware output
+
+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
+
+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
+
+### Component validation diagnostics
+
+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
+
+### Template compilation diagnostics
+
+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
+
+This means Prisma PHP’s error page is intended to be an actionable developer tool, not only a fallback screen.
+
+## Customizing the error view
+
+Prisma PHP allows you to override the default error output by creating:
+
+```php
+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
+
+That makes `error.php` the main file convention for customizing browser-visible application errors.
+
+Example:
+
+```php filename="src/app/error.php"
+<section class="container">
+    <h1>Something went wrong</h1>
+    <p>Please try again later.</p>
+</section>
+```
+
+## 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 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
+
+## Key methods
+
+The Prisma PHP docs call out several important `ErrorHandler` methods.
+
+### `registerHandlers(): void`
+
+Registers:
+
+- `set_exception_handler`
+- `register_shutdown_function`
+- `set_error_handler`
+
+The docs say this is usually called in `bootstrap.php`. citeturn0view0
+
+### `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
+
+### `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
+
+## Bootstrap registration
+
+Because `ErrorHandler` is typically framework-level, it is usually registered in the bootstrap process.
+
+```php filename="bootstrap.php"
+<?php
+
+use PP\ErrorHandler;
+
+ErrorHandler::registerHandlers();
+```
+
+This ensures the framework catches application failures consistently.
+
+## Manual usage in try/catch blocks
+
+The Prisma PHP docs also provide a manual usage pattern for custom try/catch flows. You can format the exception and output it through the standard error layout.
+
+```php filename="src/app/admin/index.php"
+<?php
+
+use PP\ErrorHandler;
+use PP\PHPX\Exceptions\ComponentValidationException;
+
+try {
+    // Some complex logic
+    throw new ComponentValidationException("Missing required prop 'id'", 500);
+} catch (Throwable $e) {
+    $html = ErrorHandler::formatExceptionForDisplay($e);
+    ErrorHandler::modifyOutputLayoutForError($html);
+}
+```
+
+This is useful when you want to catch an exception yourself but still use the framework’s standard rich diagnostic output. citeturn0view0
+
+## `index.php` vs `route.php` error handling
+
+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
+
+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`.
+
+## Prisma PHP vs Next.js mental model
+
+If you are coming from Next.js, the closest mapping is:
+
+| Next.js idea                                   | Prisma PHP equivalent                         |
+| ---------------------------------------------- | --------------------------------------------- |
+| `error.js` route boundary                      | central `ErrorHandler` + custom `error.php`   |
+| `not-found.js`                                 | `not-found.php`                               |
+| server-side returnable validation errors       | structured PHP return values or JSON payloads |
+| uncaught exceptions caught by React boundaries | uncaught exceptions trapped by `ErrorHandler` |
+| custom fallback error UI                       | `APP_PATH . '/error.php'`                     |
+
+The main difference is that Prisma PHP’s documented error handling is server-driven and centralized, rather than client-boundary driven.
+
+## 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
+
+## Validation vs unexpected failures
+
+A useful rule is:
+
+- invalid user input → handle it explicitly with `Validator` and return a normal response
+- broken database connection, parser failure, uncaught exception → let `ErrorHandler` handle it
+
+This keeps your app predictable for users and keeps the rich framework diagnostics focused on actual failures rather than routine form mistakes.