prisma-php 0.0.1

package/dist/docs/01-getting-started/file-manager.md

@@ -0,0 +1,307 @@
+---
+title: File Manager
+description: Learn how Prisma PHP file uploads and file management work so AI agents can build upload forms, manage storage safely, and use the documented UploadFile workflow instead of inventing custom file-handling patterns.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP File Manager docs before generating or editing upload and file-management code.
+  links:
+    - /docs/get-started-file
+    - /docs/php-validator
+    - /docs/route-php
+    - /docs/index-php
+    - /docs/pages-and-layouts
+---
+
+Prisma PHP file handling should follow the documented **File Manager** model and standard PHP upload rules, not assumptions copied from Laravel storage disks, Symfony upload abstractions, Livewire temporary uploads, or custom Node-style multipart pipelines.
+
+If a task involves file uploads, upload forms, `$_FILES`, upload size limits, allowed file types, renaming, deleting, replacing files, or building a file manager UI, AI agents should read the relevant Prisma PHP File Manager docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the File Manager docs first
+
+Before generating, editing, or reviewing file upload or file-management 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 `file-manager.md` file.
+4. Inspect the current route tree under `src/app`.
+5. Inspect the current upload destination and folder structure.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's storage abstraction applies directly.
+
+## Read this doc when you need
+
+- **basic upload form setup, `multipart/form-data`, or raw `$_FILES` behavior** → official `get-started-file`
+- **upload validation and normalization for names or request values** → official `php-validator` plus local validation guidance in `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
+- **a rendered upload page or full-stack file manager screen** → `index.php` plus `layouts-and-pages.md`
+- **a standalone upload endpoint, webhook-like file receiver, or direct JSON upload handler** → `route.php` plus `route-handlers.md`
+- **local dev reload issues caused by uploaded files changing on disk** → inspect `./settings/bs-config.ts` and exclude the upload directory from BrowserSync tracking
+
+## Core File Manager model AI should follow
+
+The official Prisma PHP File Manager docs describe file uploads around standard PHP uploads plus a Prisma PHP helper class:
+
+- browser upload forms must use `enctype="multipart/form-data"`
+- uploaded file metadata is available through `$_FILES`
+- multiple uploads use `multiple` plus a `name` ending in `[]`
+- temporary uploads should be moved securely into the destination directory
+- Prisma PHP provides `PP\FileManager\UploadFile` to simplify upload handling, validation, and file operations
+
+AI should preserve that model instead of replacing it with undocumented storage helpers.
+
+## Required upload form rules
+
+For a normal file upload form, Prisma PHP follows standard PHP upload behavior.
+
+A correct upload form should:
+
+1. use `method="post"`
+2. use `enctype="multipart/form-data"`
+3. include a file input such as `name="file"`
+4. use `name="files[]"` together with `multiple` for multi-file uploads
+
+Example pattern:
+
+```php filename="src/app/file-manager/index.php"
+<form action="/file-manager" method="post" enctype="multipart/form-data">
+    <input type="file" name="file" />
+    <button>Upload</button>
+</form>
+```
+
+Multiple upload pattern:
+
+```php filename="src/app/file-manager/index.php"
+<form action="/file-manager" method="post" enctype="multipart/form-data">
+    <input type="file" name="files[]" multiple="true" />
+    <button>Upload</button>
+</form>
+```
+
+## Understanding `$_FILES`
+
+The File Manager docs use PHP's native `$_FILES` array as the base upload payload.
+
+A single uploaded file typically includes values such as:
+
+- `name`
+- `full_path`
+- `type`
+- `tmp_name`
+- `error`
+- `size`
+
+AI should treat `$_FILES` as the primary raw upload source before any helper class wraps it.
+
+## Common upload error codes
+
+The documented File Manager page highlights these common PHP upload outcomes:
+
+| Code | Meaning                                    |
+| ---- | ------------------------------------------ |
+| `0`  | Success                                    |
+| `1`  | Exceeds `upload_max_filesize` in `php.ini` |
+| `2`  | Exceeds `MAX_FILE_SIZE` in the HTML form   |
+| `3`  | File partially uploaded                    |
+| `4`  | No file uploaded                           |
+| `6`  | Missing temporary folder                   |
+| `7`  | Failed to write to disk                    |
+
+When an upload fails for one of these expected reasons, return a structured message instead of treating it like an unexplained crash.
+
+## Size and server configuration
+
+The official docs show two important layers of upload limits.
+
+### HTML-side size hint
+
+You can provide a `MAX_FILE_SIZE` hidden input before the file field.
+
+```php
+<input type="hidden" name="MAX_FILE_SIZE" value="51200" />
+<input type="file" name="file" />
+```
+
+### PHP configuration limits
+
+The docs call out these key `php.ini` directives:
+
+- `file_uploads`
+- `upload_max_filesize`
+- `post_max_size`
+- `max_file_uploads`
+
+AI should remember that HTML limits do not replace server limits. If upload behavior is failing, inspect `php.ini` constraints as part of the diagnosis.
+
+## Secure destination handling
+
+Uploaded files first land in temporary storage and must then be moved into the intended destination.
+
+The base PHP pattern is:
+
+```php
+move_uploaded_file(
+    $_FILES['file']['tmp_name'],
+    DOCUMENT_PATH . '/uploads/' . $_FILES['file']['name']
+);
+```
+
+Do not leave files in temporary storage or assume the browser upload itself completed the final save.
+
+## The `UploadFile` class
+
+The Prisma PHP File Manager docs describe a dedicated helper class for uploads:
+
+```php
+use PP\FileManager\UploadFile;
+
+$upload = new UploadFile(DOCUMENT_PATH . '/uploads/');
+```
+
+This class is the documented Prisma PHP abstraction AI should prefer when the task is specifically about file uploads and management.
+
+## Exact core file location
+
+The Prisma PHP core `UploadFile` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/FileManager/UploadFile.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer a File Manager task, this is the exact core file to review.
+
+## Documented `UploadFile` capabilities
+
+The official docs describe these responsibilities for `UploadFile`:
+
+- built-in size validation
+- secure type restriction
+- filename cleanup and sanitization
+- automatic handling of multiple uploads
+
+This makes `UploadFile` the preferred documented tool for ordinary file-manager flows rather than manually reimplementing every upload rule.
+
+## Public methods AI should know
+
+The File Manager docs list these public methods:
+
+- `upload(bool $renameDuplicates = true): void`
+- `update(array $file, string $oldFilename): bool`
+- `setMaxSize(int $bytes): void`
+- `setPermittedTypes(array $mimeTypes): void`
+- `allowAllTypes(?string $suffix = null): void`
+- `rename(string $oldName, string $newName): bool`
+- `delete(string $filename): bool`
+- `getMessages(): array`
+- `getErrorCode(): array`
+- `getSuccessfulUploads(): array`
+- `static convertToBytes(string $val): int`
+- `static convertFromBytes(int $bytes): string`
+
+AI should not invent undocumented methods when these already cover the common workflow.
+
+## Validation boundary
+
+For file manager pages and upload-related actions, keep these concerns separate:
+
+- use **`UploadFile`** for upload operations and file handling
+- use **`PP\Validator`** for validating user-provided values such as rename targets, labels, or other request fields
+- use structured return values for expected validation failures
+- use route pages or route handlers according to the documented `index.php` versus `route.php` split
+
+Do not use filename cleanup as a substitute for validating other request data.
+
+## Organization guidance
+
+The official docs include a practical storage rule:
+
+- keep uploaded files outside `src/app`, because `src/app` is route and application logic
+- use a destination like `/uploads` at the root or `src/uploads` when that matches the project structure
+
+AI should avoid placing user-uploaded files inside the route tree.
+
+## Local development reload rule
+
+When uploaded files are saved into a watched local directory, BrowserSync or the local dev server may reload on every file change. For File Manager workflows, that can create noisy refresh loops during upload, rename, replace, or delete actions.
+
+To avoid tracking file storage changes during local development, exclude the upload directory in:
+
+```txt
+./settings/bs-config.ts
+```
+
+Prisma PHP projects can use:
+
+```ts
+const PUBLIC_IGNORE_DIRS = [""];
+```
+
+For local file uploads, add the upload directory path there so BrowserSync ignores storage mutations.
+
+Example pattern:
+
+```ts
+const PUBLIC_IGNORE_DIRS = ["uploads"];
+```
+
+If the project stores files in another public directory, exclude that directory instead. AI should not leave upload directories watched when the local server reload behavior becomes disruptive.
+
+## Full-stack file manager pattern
+
+The official File Manager example shows a normal Prisma PHP page route such as:
+
+```txt
+src/app/file-manager/index.php
+```
+
+The example combines these building blocks in one route:
+
+- `PP\FileManager\UploadFile`
+- `PP\Validator`
+- `PP\StateManager`
+- a standard multipart upload form
+- upload status messages
+- file listing
+- rename action
+- delete action
+
+That means a normal File Manager screen in Prisma PHP can be built as a full-stack route page without inventing a separate frontend framework.
+
+## Recommended AI workflow for file-manager tasks
+
+When the user asks for upload or file-manager functionality, AI should usually follow this order:
+
+1. read `prisma-php.json`
+2. read the official File Manager docs
+3. decide whether the task is a rendered page (`index.php`) or a direct handler (`route.php`)
+4. choose the upload destination directory
+5. if local reload becomes noisy, exclude the upload directory in `./settings/bs-config.ts`
+6. use `UploadFile` for upload, rename, update, and delete operations when it fits the documented workflow
+7. use `PP\Validator` for rename fields or other non-file request values
+8. return structured messages for expected failures
+9. inspect Prisma PHP internals only if the docs and local project usage are not enough
+
+## AI rules for file uploads and file management
+
+- read the official File Manager docs before generating upload code
+- do not guess file-upload behavior from Laravel Storage, Symfony UploadedFile, Livewire, or Node middleware
+- do not omit `enctype="multipart/form-data"` on upload forms
+- do not forget the `[]` suffix when generating multiple-file inputs
+- do not assume HTML size hints replace `php.ini` limits
+- do not write uploaded files into `src/app`
+- do not trust browser-only checks as the final validation layer
+- do not invent undocumented File Manager helper methods
+- use `UploadFile` when the task matches the documented Prisma PHP upload workflow
+- use `PP\Validator` for auxiliary request validation such as rename input validation
+- remember that the core `UploadFile` implementation lives in `vendor/tsnc/prisma-php/src/FileManager/UploadFile.php`
+- when local uploads cause dev-server refresh noise, exclude the upload directory from BrowserSync tracking in `./settings/bs-config.ts`
+
+## Suggested file name
+
+Use this file name:
+
+```txt
+file-manager.md
+```
+
+It is clear, consistent with the existing local docs set, and easy for AI agents to discover alongside files such as `authentication.md`, `components.md`, and `route-handlers.md`.

package/dist/docs/01-getting-started/index.md

@@ -0,0 +1,142 @@
+---
+title: Prisma PHP Docs
+description: Welcome to the Prisma PHP Documentation.
+related:
+  title: Next Steps
+  description: Create your first Prisma PHP application and learn the core framework features.
+  links:
+    - /docs/get-started
+---
+
+{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `fetching-data.md`, `error-handling.md`, and `route-handlers.md`, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
+
+Welcome to the Prisma PHP documentation!
+
+## What is Prisma PHP?
+
+Prisma PHP is a full-stack PHP framework for building modern, reactive web applications.
+
+You use native PHP to build your application, Prisma ORM for type-safe data access, and PulsePoint to add reactive browser state without the usual API glue or hydration-heavy workflow.
+
+It is designed to give you a server-first development model with modern UI interactivity, reusable PHPX components, Next.js-style routing concepts adapted for Prisma PHP, and CLI tooling.
+
+Whether you're building an internal dashboard, a content-rich platform, or a custom product, Prisma PHP helps you move fast while keeping your stack cohesive and expressive.
+
+## AI quick start
+
+If you are using AI-assisted development, do not guess framework behavior from other ecosystems.
+
+Use this order:
+
+1. Read `./prisma-php.json` first.
+2. Read the relevant local docs in `node_modules/prisma-php/dist/docs`.
+3. Inspect local project files.
+4. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
+
+### Read this doc when you need
+
+- **project setup or file placement** → `project-structure.md`
+- **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
+- **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
+- **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
+- **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
+- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
+- **cache behavior and `CacheHandler`** → `caching.md`
+- **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
+- **error handling, `error.php`, `not-found.php`, expected validation errors** → `error-handling.md`
+- **metadata, title, description, favicon, icons** → `metadata-and-og-images.md`
+- **API-style endpoints, `route.php`, request validation with `Validator`** → `route-handlers.md`
+- **PulsePoint runtime APIs such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-ref`, `pp-spread`** → `pulsepoint.md`
+- **updating the project or enabling features** → `upgrading.md`
+- **first-time project creation** → `installation.md`
+
+### Important AI rules
+
+- treat `node_modules/prisma-php/dist/docs` as the primary documentation source for the installed version
+- do not assume Laravel, Symfony, React, Vue, Alpine, Livewire, or Next.js behavior maps directly
+- do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
+- create routes by adding folders and route files under `src/app`
+- do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
+- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
+- when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
+- when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
+- when building reusable PHPX components, read `components.md` first
+- when building file-upload flows, file listings, rename/delete actions, or a file manager screen, read `file-manager.md` first and keep the implementation aligned with Prisma PHP’s documented File Manager model
+- when building auth flows, protection rules, or login/register pages, read `authentication.md` first and keep the implementation aligned with Prisma PHP’s documented auth model
+
+## File Manager
+
+Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.
+
+Use `file-manager.md` as the local AI-awareness guide for:
+
+- upload forms with `multipart/form-data`
+- `$_FILES` handling
+- `PP\FileManager\UploadFile`
+- upload size and type restrictions
+- rename, replace, and delete flows
+- choosing between a rendered upload page and a direct upload handler
+- validating non-file request values with `PP\Validator`
+
+After reading `file-manager.md`, verify the matching official docs at:
+
+1. `get-started-file`
+2. `php-validator` when auxiliary request validation is needed
+3. `route-php` or `pages-and-layouts` depending on whether the task is a direct handler or a full-stack page
+
+## Authentication
+
+Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.
+
+Use `authentication.md` as the local AI-awareness guide for:
+
+- `AuthConfig.php`
+- public-default vs private-default route strategy
+- `Auth::signIn(...)`
+- `Auth::signOut(...)`
+- `refreshUserSession(...)`
+- route-level RBAC
+- function-level protection with `#[Exposed(allowedRoles: [...])]`
+- credential authentication
+- social authentication
+
+After reading `authentication.md`, verify the matching official docs in this order:
+
+1. `auth-get-started`
+2. `credentials`
+3. `state-manager-auth`
+
+## Routing and file conventions
+
+Prisma PHP uses file-based routing.
+
+Important files include:
+
+- `index.php`
+- `layout.php`
+- `loading.php`
+- `route.php`
+- `not-found.php`
+- `error.php`
+- metadata files and icons
+
+Routes are created from the `src/app` folder structure and route files. AI agents should not try to register routes manually in framework-generated route list files.
+
+If you are changing route behavior or navigation patterns, read the routing documentation first.
+
+## Data and reactivity
+
+One of Prisma PHP’s core ideas is keeping data flow simple across the stack:
+
+- Query data with Prisma ORM in PHP
+- Render full-stack UI directly from route files
+- Use PulsePoint for frontend reactivity
+- Use `pp.fetchFunction(...)` for reactive frontend-to-server calls
+- Expose callable PHP functions with `#[Exposed]`
+- Validate incoming request data with `PP\Validator`
+
+This makes it easier to build interactive applications without maintaining separate DTO layers, excessive transformation code, or client-heavy hydration logic.
+
+When Prisma ORM data is loaded in `index.php`, treat normal query results as the model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
+
+Do not introduce defensive serializer layers by default just to make normal ORM results usable. Use `PP\Validator` for incoming payload validation, sanitization, casting, and rule-based checks. Only add a presentation mapper when you intentionally need a client-facing shape, such as flattening included relations, hiding sensitive fields, or formatting values for display.

package/dist/docs/01-getting-started/installation.md

@@ -0,0 +1,18 @@
+---
+title: Installation
+description: Learn how to create a new Prisma PHP application with the `create-prisma-php-app` CLI and start building locally.
+---
+
+Create a new Prisma PHP app and run it locally.
+
+## Quick start
+
+1. Create a new Prisma PHP app.
+2. Change into the project directory.
+3. Start the local development environment.
+
+```bash package="npm"
+npx create-prisma-php-app@latest
+cd my-app
+npm run dev
+```