prisma-php 0.0.1

package/dist/docs/01-getting-started/fetching-data.md

@@ -0,0 +1,637 @@
+---
+title: Fetching Data
+description: Learn how to fetch data in Prisma PHP using `pp.fetchFunction`, `#[Exposed]`, page handlers, and route handlers.
+related:
+  title: API Reference
+  description: Learn more about the features mentioned in this page by reading the Prisma PHP docs.
+  links:
+    - /docs/fetch-function
+    - /docs/index-php
+    - /docs/route-php
+    - /docs/pages-and-layouts
+---
+
+This page will walk you through how you can fetch 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.
+
+Prisma PHP has a different mental model from Next.js. Instead of focusing on React Server Components, Suspense 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.
+
+For validation, the default backend pattern should be **`PP\Validator`**. Use it to sanitize, cast, and validate values inside exposed functions and route handlers. This keeps the browser reactive while keeping the authoritative validation on the server.
+
+## Validation is a server concern
+
+In Prisma PHP, frontend interactivity and backend validation work together, but they are not the same thing.
+
+Use this split:
+
+- use **PulsePoint** for local input state, loading state, and reactive UI feedback
+- use **`pp.fetchFunction(...)`** to send data to PHP during interactive flows
+- use **`PP\Validator`** in PHP to sanitize, cast, and validate the incoming payload
+- return a **structured response** such as `success`, `errors`, and normalized values
+- do not trust browser-only validation as the final source of truth
+
+This makes `Validator` a natural fit for:
+
+- live field validation
+- inline availability checks
+- form submission validation
+- normalization before database writes
+- reusable backend validation for both page-local RPC and direct handlers
+
+## Recommended Validator pattern for `pp.fetchFunction(...)`
+
+For reactive UI work, the best Prisma PHP pattern is usually:
+
+1. keep the current field state in PulsePoint
+2. call an exposed PHP function with `pp.fetchFunction(...)`
+3. validate on the server with `Validator`
+4. return a structured object for the UI to render
+
+The official Validator docs recommend the **`Rule` builder** for most rule-based validation because it is easier to discover, easier to refactor, and less error-prone than raw pipe strings.
+
+## Recommended pattern for reactive Prisma PHP UIs
+
+For normal interactive UI work in Prisma PHP, the default approach should be:
+
+1. render the page with `index.php`
+2. manage browser-side reactivity with PulsePoint
+3. call PHP from the frontend with `pp.fetchFunction(...)`
+4. expose callable functions with `#[Exposed]`
+
+This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, and similar route-local interactions.
+
+Do **not** default to building extra `route.php` endpoints for every interactive action when `pp.fetchFunction(...)` is the better fit. Reserve `route.php` for explicit API-style endpoints, webhooks, JSON handlers, or routes that must be called independently of the page.
+
+## Fetching data in Prisma PHP
+
+There are three common ways to fetch or load data in Prisma PHP:
+
+1. **Load data directly in `index.php`** for full-stack page rendering
+2. **Call PHP functions from JavaScript with `pp.fetchFunction(...)`**
+3. **Use `route.php`** for API-style or direct JSON endpoints
+
+### Choosing the right approach
+
+Use this rule of thumb:
+
+- use `index.php` when the route should render page UI
+- use `pp.fetchFunction(...)` when frontend interactivity should call backend PHP directly without creating a dedicated route file
+- use `route.php` when you need a direct API-style endpoint, JSON handler, webhook, or no-view request path
+
+In a full-stack Prisma PHP project, normal page data is usually loaded in `index.php`, and interactive frontend updates are commonly handled with `pp.fetchFunction(...)`.
+
+## Fetching data in `index.php`
+
+For full-stack page routes, the most direct way to fetch data is inside `index.php`.
+
+Because `index.php` is the UI entry point for a route, it is the right place to query the database, prepare data, and render HTML or PHPX-based output.
+
+```php filename="src/app/blog/index.php"
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+
+$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 closest Prisma PHP equivalent to server-side page data loading.
+
+## Fetching data with `pp.fetchFunction(...)`
+
+One of Prisma PHP’s main frontend-to-backend patterns is **Direct Function Invocation** with `pp.fetchFunction(...)`.
+
+This allows you to call PHP functions directly from frontend JavaScript without creating route files, controllers, or custom API endpoints.
+
+### Basic example
+
+Before a PHP function can be called with `pp.fetchFunction(...)`, it must be marked with `#[Exposed]`.
+
+Functions and methods are private by default in this flow. `pp.fetchFunction(...)` will only work for functions that are intentionally exposed.
+
+```php filename="src/app/users/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Validator;
+
+#[Exposed]
+function validateUser($data)
+{
+    $id = Validator::int($data->id);
+
+    if ($id <= 0) {
+        return [
+            'success' => false,
+            'msg' => 'Invalid ID',
+        ];
+    }
+
+    return [
+        'success' => true,
+        'msg' => 'Valid ID',
+    ];
+}
+?>
+
+<script>
+    const [id, setId] = pp.state('');
+    const [msg, setMsg] = pp.state('');
+
+    async function checkId() {
+        const response = await pp.fetchFunction('validateUser', { id });
+
+        if (response.success) {
+            setMsg(response.msg);
+        } else {
+            setMsg(response.msg);
+        }
+    }
+</script>
+
+<input value="{id}" oninput="setId(val)" />
+<button onclick="checkId()">Check</button>
+<p>{msg}</p>
+```
+
+If `validateUser()` is not decorated with `#[Exposed]`, the client cannot invoke it through `pp.fetchFunction(...)`.
+Prisma PHP automatically serializes the request and parses the PHP return value back into JavaScript. If the response is JSON-compatible, the result is returned as a parsed object. If the backend returns non-JSON data, the result may be returned as a raw string.
+
+## Why `pp.fetchFunction(...)` is important
+
+`pp.fetchFunction(...)` is one of Prisma PHP’s biggest differences from other frameworks.
+
+It removes the need for:
+
+- controller boilerplate
+- custom route definitions
+- manual `fetch('/api/...')` setup for many interactions
+- repetitive JSON parsing code on both sides
+
+Instead, you define an exposed PHP function and call it directly.
+
+This makes it especially useful for:
+
+- form validation
+- search-as-you-type
+- quick data checks
+- lightweight mutations
+- UI-triggered backend actions
+- interactive dashboard behavior
+
+## Working with `Exposed`
+
+`#[Exposed]` is not just an optional enhancement for `pp.fetchFunction(...)`—it is the requirement that makes a PHP function callable from the client.
+
+Functions are private by default. To allow frontend access, you must explicitly opt in with the `Exposed` attribute. This keeps server logic locked down unless you intentionally expose it.
+
+```php filename="src/app/users/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Validator;
+
+#[Exposed]
+function validateUser($data)
+{
+    $id = Validator::int($data->id);
+
+    return [
+        'success' => $id > 0,
+    ];
+}
+
+#[Exposed(
+    requiresAuth: true,
+    allowedRoles: ['admin'],
+    limits: '20/min'
+)]
+function searchUsers($data)
+{
+    $query = Validator::string($data->query ?? '');
+
+    return [
+        'success' => true,
+        'query' => $query,
+    ];
+}
+```
+
+The `Exposed` attribute supports:
+
+- `requiresAuth`
+- `allowedRoles`
+- `limits`
+
+Based on the provided class definition, it can be applied to functions and methods and is designed for direct invocation with authentication, role checks, and rate limiting.
+
+### What each option does
+
+- `#[Exposed]` makes the function publicly callable from `pp.fetchFunction(...)`
+- `requiresAuth: true` restricts access to authenticated users
+- `allowedRoles: [...]` restricts access to specific roles
+- `limits` applies one or more rate limits such as `"5/minute"` or `["5/m", "100/d"]`
+
+### Private by default
+
+This is the key rule to remember:
+
+- `pp.fetchFunction('myFunction')` only works if `myFunction` is exposed
+- a normal PHP function without `#[Exposed]` remains private to the server context
+- use `#[Exposed]` whenever you want frontend JavaScript to call a PHP function directly
+
+## Parameters and automatic parsing
+
+`pp.fetchFunction(...)` accepts the function name, a payload object, and an optional third argument for request behavior.
+
+```ts
+fetchFunction<T = any>(
+  functionName: string,
+  data: Record<string, any> = {},
+  options: boolean | RpcOptions = false
+): Promise<T | void>
+```
+
+### Parameters
+
+- `functionName`: the exact PHP function name to call
+- `data`: an object containing the arguments to send
+- `options`: either `true`/`false` for simple abort behavior or an options object for advanced features
+
+### Common options
+
+- `abortPrevious`: cancel previous pending requests from the same caller
+- `onStream`: handle streamed SSE chunks
+- `onStreamError`: handle stream errors
+- `onStreamComplete`: run logic when streaming finishes
+- `onUploadProgress`: track real upload progress when sending `File` or `FileList`
+- `onUploadComplete`: run logic when the upload finishes
+
+This is useful for search inputs, streaming responses, uploads, and other rapid repeated interactions.
+
+```html
+<script>
+  async function onSearch(val) {
+    const response = await pp.fetchFunction(
+      "searchUsers",
+      { query: val },
+      { abortPrevious: true },
+    );
+
+    console.log(response);
+  }
+</script>
+```
+
+As with every `pp.fetchFunction(...)` call, `searchUsers` must be decorated with `#[Exposed]` on the PHP side.
+
+## File upload support
+
+Prisma PHP’s fetch function automatically switches to multipart handling when the payload contains a `File` or `FileList`.
+
+The upload handler still needs to be exposed with `#[Exposed]` if it is being called from `pp.fetchFunction(...)`.
+
+That means you do not need to manually build `FormData` for many common upload flows.
+
+```html
+<script>
+  async function uploadAvatar() {
+    const fileInput = document.getElementById("avatar");
+
+    const response = await pp.fetchFunction("uploadAvatar", {
+      image: fileInput.files[0],
+      userId: 12,
+    });
+
+    console.log(response);
+  }
+</script>
+
+<input id="avatar" type="file" />
+<button onclick="uploadAvatar()">Upload</button>
+```
+
+## Request cancellation
+
+For fast-changing inputs such as live search, Prisma PHP can automatically cancel stale requests by using `abortPrevious: true`.
+
+```html
+<script>
+  async function searchPosts(val) {
+    const response = await pp.fetchFunction(
+      "searchPosts",
+      { query: val },
+      { abortPrevious: true },
+    );
+
+    console.log(response);
+  }
+</script>
+```
+
+This helps prevent race conditions and outdated responses from overwriting newer UI state.
+
+## Transparent redirects
+
+If a PHP function returns a redirect instruction, or if authentication fails in a way that triggers redirect behavior, `pp.fetchFunction(...)` can automatically perform a client-side redirect through Prisma PHP’s navigation helpers.
+
+This makes interactive authenticated flows smoother without requiring extra frontend redirect wiring.
+
+## Using `Validator` inside exposed functions
+
+An exposed function should do more than simply accept the raw payload. It should:
+
+1. normalize incoming values
+2. validate the shape and business rules
+3. return predictable frontend-friendly output
+
+A practical pattern is:
+
+```php filename="src/app/settings/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Rule;
+use PP\Validator;
+
+#[Exposed]
+function saveProfile($data)
+{
+    $name = Validator::string($data->name ?? '');
+    $email = Validator::email($data->email ?? '');
+    $newsletter = Validator::boolean($data->newsletter ?? false);
+
+    $nameResult = Validator::withRules($name, Rule::required()->min(3)->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' => [],
+        'data' => [
+            'name' => $name,
+            'email' => $email,
+            'newsletter' => $newsletter ?? false,
+        ],
+    ];
+}
+```
+
+This pattern works well because the UI can render field errors immediately, while the backend still controls the final truth.
+
+## `Validator` helpers you will commonly use
+
+Some of the most useful helpers for reactive and backend validation include:
+
+- `Validator::string(...)` for sanitized strings
+- `Validator::email(...)` for email addresses
+- `Validator::int(...)` and `Validator::float(...)` for numeric casting
+- `Validator::boolean(...)` for smart boolean conversion
+- `Validator::json(...)` for JSON-safe validation or encoding
+- `Validator::date(...)` and `Validator::dateTime(...)` for normalized date values
+- `Validator::enum(...)` and `Validator::enumClass(...)` for allowed options
+- `Validator::withRules(...)` for rule-based validation
+
+Use primitive helpers for normalization first, then apply `withRules(...)` when the value has business constraints such as required, minimum length, confirmed fields, allowed lists, or date rules.
+
+## Using `route.php` for data fetching
+
+When you need an explicit endpoint instead of direct function invocation, use `route.php`.
+
+This is a better fit for:
+
+- external integrations
+- webhooks
+- standalone JSON endpoints
+- routes that should be called outside the current page context
+- API-style request handlers
+
+Example:
+
+```php filename="src/app/users/route.php"
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+use PP\Request;
+
+if (!Request::$isGet) {
+    exit;
+}
+
+$prisma = Prisma::getInstance();
+
+$users = $prisma->user->findMany();
+
+echo json_encode($users);
+```
+
+In Prisma PHP, `route.php` is the direct handler entry point for a route segment and is commonly used for API-style behavior.
+
+## `index.php` vs `route.php` for fetching data
+
+Use `index.php` when:
+
+- the route should render page UI
+- data belongs to the page render itself
+- the request is part of the normal full-stack page flow
+
+Use `route.php` when:
+
+- the route should act like an API endpoint
+- the response should bypass standard page rendering
+- the request needs a dedicated direct handler
+
+Use `pp.fetchFunction(...)` when:
+
+- you are inside an existing page
+- the frontend needs to call PHP directly
+- you want less boilerplate than a dedicated route file
+
+## Common Prisma PHP data-fetching patterns
+
+### Page loads in `index.php`
+
+```php filename="src/app/dashboard/index.php"
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+
+$prisma = Prisma::getInstance();
+
+$stats = $prisma->user->count();
+
+echo "<h1>Total users: " . (int) $stats . "</h1>";
+```
+
+### Interactive validation with `pp.fetchFunction(...)`
+
+```php filename="src/app/profile/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Rule;
+use PP\Validator;
+
+#[Exposed]
+function validateUsername($data)
+{
+    $username = Validator::string($data->username ?? '');
+
+    $result = Validator::withRules(
+        $username,
+        Rule::required()->min(3)->max(30)
+    );
+
+    if ($result !== true) {
+        return [
+            'success' => false,
+            'errors' => [
+                'username' => $result,
+            ],
+        ];
+    }
+
+    if ($username === 'admin') {
+        return [
+            'success' => false,
+            'errors' => [
+                'username' => 'This username is not available.',
+            ],
+        ];
+    }
+
+    return [
+        'success' => true,
+        'errors' => [],
+        'normalized' => [
+            'username' => $username,
+        ],
+    ];
+}
+?>
+
+<input
+    type="text"
+    value="{username}"
+    oninput="validateUsername(event.target.value)"
+/>
+<p hidden="{!usernameError}">{usernameError}</p>
+
+<script>
+    const [username, setUsername] = pp.state('');
+    const [usernameError, setUsernameError] = pp.state('');
+
+    async function validateUsername(val) {
+        setUsername(val);
+
+        const response = await pp.fetchFunction(
+            'validateUsername',
+            { username: val },
+            { abortPrevious: true }
+        );
+
+        setUsernameError(response.errors?.username ?? '');
+    }
+</script>
+```
+
+### Dedicated JSON endpoint with `route.php`
+
+```php filename="src/app/reports/route.php"
+<?php
+
+echo json_encode([
+    'success' => true,
+    'generatedAt' => date('c'),
+]);
+```
+
+## Loading states
+
+Unlike Next.js, Prisma PHP’s data-fetching story here is not centered on React Suspense or streaming server components.
+
+Instead, loading behavior is typically handled in the UI with:
+
+- local PulsePoint state
+- `pp-loading-content`
+- route-level `loading.php`
+- custom interactive state patterns
+
+For interactive fetches, you usually manage loading state yourself:
+
+```html
+<script>
+  const [loading, setLoading] = pp.state(false);
+  const [items, setItems] = pp.state([]);
+
+  async function loadItems() {
+    setLoading(true);
+
+    try {
+      const response = await pp.fetchFunction("getItems");
+      setItems(response.items ?? []);
+    } finally {
+      setLoading(false);
+    }
+  }
+</script>
+```
+
+## Security and backend rules
+
+When fetching data from Prisma PHP:
+
+- validate incoming values on the server
+- use `Validator` as the default PHP validation layer for interactive requests
+- prefer the `Rule` builder for rule-based validation
+- every function called through `pp.fetchFunction(...)` must use `#[Exposed]`
+- return structured validation results instead of relying on thrown exceptions for routine failures
+- use `Exposed` options to enforce auth, roles, or rate limits
+- prefer `route.php` for dedicated public or integration-facing endpoints
+- keep sensitive database access on the server side
+
+Because Prisma PHP runs the data logic in PHP, database credentials and internal query logic stay on the server.
+
+## Good to know
+
+- Prisma PHP’s primary interactive fetch model is `pp.fetchFunction(...)`.
+- `index.php` is the UI entry point for page rendering.
+- `route.php` is the direct handler entry point for API-style routes.
+- `pp.fetchFunction(...)` only works for functions that are explicitly marked with `#[Exposed]`.
+- `pp.fetchFunction(...)` automatically serializes and parses data.
+- `Validator` is the default PHP validation layer for reactive requests and backend handlers.
+- prefer `Validator::withRules(...)` with `Rule` for rule-based validation.
+- `abortPrevious: true` helps cancel stale requests.
+- file uploads can be handled automatically without manual `FormData` in many cases.
+- `Exposed` can be used to declare authentication, allowed roles, and rate limits for callable functions.
+- for full-stack routes, load page data in `index.php` and use direct function invocation for interactive updates.