prisma-php 0.0.2 → 0.0.4

package/dist/docs/validator.md

@@ -0,0 +1,293 @@
+---
+title: Validator
+description: Learn how Prisma PHP validation works so AI agents can sanitize, cast, and validate request data with PP\Validator and the documented Rule workflow instead of inventing custom validation patterns.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP Validator docs before generating or editing validation code.
+  links:
+    - /docs/php-validator
+    - /docs/fetch-function
+    - /docs/route-php
+    - /docs/error-handler
+---
+
+Prisma PHP validation should follow the documented `PP\Validator` model, not assumptions copied from Laravel FormRequest, Symfony Validator, Joi, Yup, Zod, or ad hoc request-wrapper patterns.
+
+If a task involves sanitization, casting, validation rules, `Rule`, `Validator::withRules(...)`, request normalization, or expected validation failures, AI agents should read the relevant Prisma PHP Validator docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the Validator docs first
+
+Before generating, editing, or reviewing validation 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 `validator.md` file.
+4. Inspect the current `index.php`, `layout.php`, exposed function, or `route.php` that receives the data.
+5. Inspect the payload shape and expected response contract.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's validation lifecycle applies directly.
+
+## Read this doc when you need
+
+- **sanitization, casting, normalization, `PP\Validator`, `Rule`, or `Validator::withRules(...)`** → `validator.md`
+- **interactive validation with `pp.fetchFunction(...)` inside page routes** → `fetching-data.md` plus `validator.md`
+- **request validation in `route.php`** → `route-handlers.md` plus `validator.md`
+- **expected validation failures and response shaping** → `error-handling.md` plus `validator.md`
+- **credentials, registration, login, or auth form validation** → `authentication.md` plus `validator.md`
+- **rename fields, labels, or other non-file request values in upload flows** → `file-manager.md` plus `validator.md`
+
+## Core validation model AI should follow
+
+The official Prisma PHP Validator docs describe `PP\Validator` as the central server-side validation layer.
+
+Use this split:
+
+- use **PulsePoint** or browser-side logic for local UX only
+- use **`PP\Validator`** on the PHP side for authoritative sanitization, casting, and validation
+- use **`PP\Rule`** when business constraints must be checked declaratively
+- return structured failures for expected validation problems instead of treating them like crashes
+
+`Validator` is not the ORM result layer, not a frontend schema runtime, and not a replacement for route or function structure.
+
+## Exact core file location
+
+The Prisma PHP core `Validator` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/Validator.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer a validation task, this is the exact core file to review.
+
+## Identity and string helpers
+
+The official docs describe these common helpers:
+
+- `string($value, bool $escapeHtml = true): string`
+- `email($value): ?string`
+- `url($value): ?string`
+- `ip($value): ?string`
+- `uuid($value): ?string`
+- `ulid($value): ?string`
+- `cuid($value): ?string`
+- `cuid2($value): ?string`
+- `emojis(string $content): string`
+
+Use these helpers when the goal is to normalize or validate a single incoming value before applying additional rules.
+
+## Number and utility helpers
+
+The official docs also describe:
+
+- `int($value): ?int`
+- `float($value): ?float`
+- `bigInt($value): ?BigInteger`
+- `decimal($value, int $scale = 30): ?BigDecimal`
+- `bytes($value): ?string`
+- `boolean($value): ?bool`
+- `json($value): string`
+- `enum($value, array $allowed): bool`
+- `enumClass($value, string $class)`
+- `date($value, string $format = "Y-m-d"): ?string`
+- `dateTime($value, string $format = "Y-m-d H:i:s"): ?string`
+
+Important behavior to remember:
+
+- many helper methods return `null` when the value is invalid
+- `enum(...)` checks membership against a simple allowed array
+- `json(...)` accepts JSON strings or safely encodes arrays
+- `boolean(...)` performs smart casting for values such as `"true"`, `"1"`, `"on"`, and `"yes"`
+
+## Rule-based validation
+
+The main rule-based entry point is:
+
+```php
+Validator::withRules($value, string|Rule|array $rules, $confirm = null)
+```
+
+Return contract:
+
+- `true` when all rules pass
+- `string` when the first rule fails
+
+Always use a strict success check:
+
+```php
+if ($result === true) {
+    // valid
+}
+```
+
+## Recommended rule syntax
+
+The official docs support three rule styles.
+
+### 1. Rule builder, recommended
+
+This is the preferred style for most application code because it is easier to discover, safer to refactor, and clearer in reviews.
+
+```php
+use PP\Rule;
+
+$rules = Rule::required()
+    ->min(3)
+    ->max(50)
+    ->startsWith('J');
+```
+
+### 2. Pipe string syntax
+
+Useful for small inline rules or dynamic rules loaded from config.
+
+```php
+$rules = 'required|min:3|max:50';
+```
+
+### 3. Array syntax
+
+Useful when rules need to be appended conditionally.
+
+```php
+$rules = ['required', 'min:8'];
+$rules[] = 'confirmed';
+```
+
+## Common documented rules
+
+The official docs list rules such as:
+
+- `required`
+- `min:n`
+- `max:n`
+- `size:n`
+- `between:min,max`
+- `email`
+- `url`
+- `ip`
+- `uuid`
+- `ulid`
+- `cuid`
+- `int`
+- `float`
+- `boolean`
+- `startsWith:value`
+- `endsWith:value`
+- `confirmed`
+- `in:a,b,c`
+- `notIn:a,b,c`
+- `date:format`
+- `dateFormat:format`
+- `before:date`
+- `after:date`
+- `json`
+- `timezone`
+- `regex:pattern`
+- `digits:n`
+- `digitsBetween:min,max`
+- `extensions:jpg,png`
+- `mimes:image/jpeg,image/png`
+- `file`
+
+AI should not invent undocumented rule names when these already cover the common Prisma PHP validation workflow.
+
+## Recommended example patterns
+
+### Basic casting and validation
+
+```php
+<?php
+
+use PP\Validator;
+
+$name = Validator::string($_POST['name'] ?? '');
+$age = Validator::int($_POST['age'] ?? null);
+$email = Validator::email($_POST['email'] ?? '');
+
+if ($email === null) {
+    return [
+        'success' => false,
+        'errors' => [
+            'email' => 'A valid email address is required.',
+        ],
+    ];
+}
+```
+
+### Rule builder, recommended
+
+```php
+<?php
+
+use PP\Rule;
+use PP\Validator;
+
+$username = Validator::string($_POST['username'] ?? '');
+
+$result = Validator::withRules(
+    $username,
+    Rule::required()->min(3)->max(50)
+);
+
+if ($result !== true) {
+    return [
+        'success' => false,
+        'errors' => [
+            'username' => $result,
+        ],
+    ];
+}
+```
+
+### Confirmation rule
+
+```php
+<?php
+
+use PP\Validator;
+
+$password = Validator::string($_POST['password'] ?? '', false);
+$confirm = Validator::string($_POST['password_confirmation'] ?? '', false);
+
+$result = Validator::withRules($password, ['required', 'min:8', 'confirmed'], $confirm);
+```
+
+## Operational notes
+
+- use `=== true` when checking `Validator::withRules(...)`
+- use the third parameter for `confirmed` comparisons
+- pass full regex patterns with delimiters when using `regex`
+- use array syntax when rules depend on runtime conditions
+- apply validation before database writes, auth state changes, uploads, or other side effects
+
+## Validation boundary
+
+Keep these concerns separate:
+
+- use **browser-side checks** for immediate feedback only
+- use **`PP\Validator`** for authoritative backend validation
+- use **`error-handling.md`** patterns for expected validation failures
+- use **`fetching-data.md`** or **`route-handlers.md`** based on where the request enters PHP
+
+Do not treat browser validation, HTML attributes, or frontend checks as the final source of truth.
+
+## AI rules for validation work
+
+- read the official Validator docs before generating validation code
+- do not guess validation APIs from Laravel, Symfony, Joi, Yup, Zod, or other ecosystems
+- prefer `PP\Validator` for sanitization, casting, and helper-based validation
+- prefer the `Rule` builder for most rule-based validation
+- do not assume `Validator::withRules(...)` throws exceptions for normal failures
+- return structured validation results for expected user-input errors
+- inspect `vendor/tsnc/prisma-php/src/Validator.php` only when the docs and current code are not enough
+
+## Suggested file name
+
+Use this file name:
+
+```txt
+validator.md
+```
+
+It is clear, consistent with the existing local docs set, and easy for AI agents to discover alongside files such as `authentication.md`, `file-manager.md`, and `route-handlers.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-php",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Prisma PHP tooling",
   "main": "index.js",
   "scripts": {