prisma-php 0.0.1

package/dist/docs/01-getting-started/prisma-php-orm.md

@@ -0,0 +1,374 @@
+---
+title: Prisma PHP ORM
+description: Learn how Prisma PHP ORM works, how to configure it, how to migrate your database, and how to generate the PHP ORM classes correctly.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP ORM docs before generating code or running ORM commands.
+  links:
+    - /docs/orm-get-started
+    - /docs/config-file
+    - /docs/prisma-cli
+    - /docs/find-many
+---
+
+Prisma PHP ORM gives Prisma PHP applications a schema-first, Prisma-style data layer for PHP projects.
+
+It uses your Prisma schema, Prisma migrations, and generated PHP classes so your application can query the database through the documented Prisma PHP API.
+
+## ORM result shape rule
+
+Prisma PHP ORM query results should be treated as model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
+
+For normal reads, do not assume query results need defensive serializer layers just to become usable in PHP. Prisma ORM is already the source of truth for the requested model shape.
+
+Only add a presentation mapper when you intentionally need to:
+
+- flatten included relations for the frontend
+- hide sensitive fields before returning data to the browser
+- format dates or values for display
+- produce a custom client-facing response shape
+
+Use `PP\Validator` for inbound payload validation, sanitization, casting, and rule-based checks. Do not use output serialization as a substitute for backend validation.
+
+## Backend validation rule
+
+For Prisma PHP pages, exposed functions, and route handlers, backend validation should default to `PP\Validator`, which is part of the Prisma PHP core files and lives in:
+
+```txt
+vendor/tsnc/prisma-php/src/Validator.php
+```
+
+`Validator` is the server-side validation layer for user input. It is not the ORM result layer.
+
+Use this split:
+
+- Prisma ORM for model-shaped query results
+- `PP\Validator` for request validation and normalization
+- optional presentation mapping only when the UI needs a deliberate response shape
+
+## AI agent rule: read the ORM docs first
+
+When a task involves any of the following:
+
+- `schema.prisma`
+- database provider selection
+- migrations
+- generated Prisma PHP classes
+- `Prisma::getInstance()`
+- `findMany`, `findFirst`, `create`, `update`, `delete`
+- `prisma.config.ts`
+- `npx prisma ...`
+- `npx ppo generate`
+
+read the ORM docs first before deciding what command to run or what code to generate.
+
+Use this order:
+
+1. Read `prisma-php.json`
+2. Read the installed Prisma PHP ORM docs
+3. Read `schema.prisma`
+4. Confirm the database provider
+5. Then decide the correct ORM workflow
+
+## Where AI should look
+
+For Prisma PHP ORM tasks, AI should read:
+
+- `06-prisma-php-orm.md`
+- the official Prisma PHP ORM docs for the installed version
+- `schema.prisma`
+- `prisma.config.ts`
+- `.env` when the datasource uses `env("DATABASE_URL")`
+
+Do not use general Prisma TypeScript habits alone. Prisma PHP has a PHP-specific workflow and generated PHP classes that must match the actual database state.
+
+## Important separation of responsibilities
+
+There are three different workflows that AI must not confuse.
+
+### 1. Framework or project update workflow
+
+Use this only when the task is about updating the full Prisma PHP project, syncing framework files, installing enabled features, or refreshing dependencies:
+
+```bash
+npx pp update project -y
+```
+
+This is a project/framework update command.
+
+It is **not** the normal Prisma ORM schema migration workflow.
+
+### 2. Prisma ORM database migration workflow
+
+Use this when the database must be initialized or when `schema.prisma` changes and the database structure must be updated.
+
+Typical development workflow:
+
+```bash
+npx prisma migrate dev
+```
+
+This is the migration step.
+
+### 3. Prisma PHP class generation workflow
+
+Use this after migration succeeds, so the generated PHP ORM classes match the updated schema:
+
+```bash
+npx ppo generate
+```
+
+This is the PHP class generation step.
+
+## Required AI workflow for ORM tasks
+
+Whenever a task depends on Prisma ORM, AI should follow this order:
+
+1. Confirm which database provider the project uses.
+2. Confirm whether the task is working against SQLite, MySQL, PostgreSQL, or another user-requested provider.
+3. Inspect `schema.prisma`.
+4. Inspect `prisma.config.ts`.
+5. If the datasource uses `env("DATABASE_URL")`, inspect `.env`.
+6. Decide whether migration is required before generation.
+7. Run migration first when required.
+8. After migration succeeds, run `npx ppo generate`.
+9. Only then generate or update PHP code that depends on the Prisma PHP classes.
+
+## Critical rule
+
+`npx ppo generate` only generates or refreshes the PHP ORM classes.
+
+It does **not** prove that the database migration ran.
+
+It does **not** update the database schema by itself.
+
+If the migration output is missing, failed, or was never executed, AI must say that clearly.
+
+Correct wording:
+
+- migration not confirmed
+- generated PHP classes may exist
+- database schema may still be out of sync
+
+Incorrect wording:
+
+- migration completed, if only `npx ppo generate` ran
+- database is synced, if there is no confirmed migration output
+
+## Confirm the database provider first
+
+Before running migration or generation commands, inspect the Prisma schema and determine the active provider.
+
+Typical provider examples include:
+
+- `sqlite`
+- `mysql`
+- `postgresql`
+
+AI should not assume the provider.
+
+It should read the datasource block in `schema.prisma` or follow the user’s explicit database request.
+
+Example:
+
+```prisma
+// prisma/schema.prisma
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+```
+
+## SQLite workflow
+
+When the provider is `sqlite`, AI must do more than just read the provider name.
+
+It must also verify the SQLite connection target.
+
+Use this flow:
+
+1. read `schema.prisma`
+2. read `.env` if the datasource URL comes from `env("DATABASE_URL")`
+3. confirm that `DATABASE_URL` exists
+4. resolve the SQLite file path from `DATABASE_URL`
+5. confirm the path is valid for the project
+6. if the SQLite database file is missing, invalid, or not initialized yet, run:
+
+```bash
+npx prisma migrate dev
+```
+
+7. after migration succeeds, run:
+
+```bash
+npx ppo generate
+```
+
+Important SQLite rule:
+
+- if Prisma PHP reports that the SQLite database file was not found or could not be created, AI must not stop at `npx ppo generate`
+- in that situation, the database initialization or migration step is still required
+
+## MySQL and PostgreSQL workflow
+
+When the provider is `mysql` or `postgresql`, use this flow:
+
+1. confirm the provider in `schema.prisma`
+2. confirm the environment connection values
+3. run `npx prisma migrate dev` on first setup
+4. run `npx prisma migrate dev` whenever `schema.prisma` changes
+5. after migration succeeds, run `npx ppo generate`
+
+This keeps the database structure and generated PHP classes aligned.
+
+## `prisma.config.ts`
+
+Prisma PHP ORM also uses `prisma.config.ts` at the project root.
+
+This file is part of the ORM configuration workflow and should be reviewed when the task involves Prisma ORM setup, migrations, or generation.
+
+AI should treat it as part of the ORM source of truth alongside `schema.prisma`.
+
+## Example ORM workflow for AI
+
+Use this pattern when the user asks to update models or add ORM-backed features.
+
+### Correct sequence
+
+1. Read `schema.prisma`
+2. Confirm database provider
+3. Read `.env` if needed for `DATABASE_URL`
+4. Decide whether the database must be initialized or migrated
+5. Run migration
+6. Run PHP class generation
+7. Then write route, page, or server logic
+
+Example:
+
+```bash
+npx prisma migrate dev
+npx ppo generate
+```
+
+### Incorrect sequence
+
+```bash
+npx pp update project -y
+npx ppo generate
+```
+
+That sequence may refresh framework files and generate classes, but it does not by itself prove the database schema was migrated.
+
+## Development vs prototype note
+
+Prisma CLI also documents `db push` for prototype-style workflows.
+
+AI should not treat `db push` as the default migration flow when the intended workflow is migration-based development.
+
+For normal tracked schema changes, prefer the documented migration flow first, then class generation.
+
+## First-time generation rule
+
+`npx ppo generate` should be executed:
+
+- the first time generated PHP ORM classes are needed
+- whenever `schema.prisma` changes
+- after the database migration or initialization step succeeds
+
+Do not run generation alone and describe the database as ready unless the migration step was also confirmed.
+
+## Using Prisma PHP in application code
+
+After the ORM classes are generated, Prisma PHP code should use the documented PHP access pattern.
+
+Example:
+
+```php
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+
+$prisma = Prisma::getInstance();
+
+$users = $prisma->user->findMany();
+```
+
+Do not invent TypeScript-style Prisma usage in PHP files.
+
+For normal application code, read ORM results directly as Prisma PHP model-shaped objects. Do not describe a manual serializer as required unless the code is intentionally shaping a frontend-facing response.
+
+## `findMany` example
+
+Prisma PHP queries are written with PHP arrays.
+
+Example:
+
+```php
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+
+$prisma = Prisma::getInstance();
+
+$users = $prisma->user->findMany([
+    'where' => [
+        'active' => true,
+    ],
+    'orderBy' => [
+        'createdAt' => 'desc',
+    ],
+    'take' => 10,
+    'skip' => 0,
+]);
+```
+
+Common query options include:
+
+- `where`
+- `select`
+- `include`
+- `orderBy`
+- `take`
+- `skip`
+
+## AI warnings for ORM tasks
+
+When working with Prisma PHP ORM, follow these rules:
+
+- do not use `npx pp update project -y` as the ORM sync command
+- do not claim migration ran unless command output confirms it
+- do not treat `npx ppo generate` as a migration step
+- do not assume SQLite unless the schema or user request confirms it
+- do not skip `.env` and `DATABASE_URL` checks when SQLite is used
+- do not write raw guessed ORM wrappers if the documented generation workflow should be used
+- do not copy Prisma JavaScript or TypeScript examples directly into PHP
+
+## Best-practice AI wording
+
+When migration succeeded and generation succeeded, AI may say:
+
+- the database migration completed successfully
+- the Prisma PHP classes were generated successfully
+
+When only generation succeeded, AI should say:
+
+- `npx ppo generate` completed
+- generated PHP ORM classes are present
+- database migration was not confirmed
+
+When SQLite is configured but the file is missing or unusable, AI should say:
+
+- SQLite `DATABASE_URL` was checked
+- the SQLite database file is missing, invalid, or not initialized
+- `npx prisma migrate dev` is required before relying on generated PHP ORM classes
+
+## Summary rule
+
+For Prisma PHP ORM tasks, the correct mental model is:
+
+- confirm provider first
+- inspect `.env` when `DATABASE_URL` is used
+- for SQLite, verify the database file path and initialize or migrate when needed
+- for MySQL and PostgreSQL, migrate on first setup and after schema changes
+- generate PHP classes after migration
+- only use `npx pp update project -y` for full project/framework updates

package/dist/docs/01-getting-started/project-structure.md

@@ -0,0 +1,328 @@
+---
+title: Project structure and organization
+nav_title: Project Structure
+description: Learn the folder and file conventions in Prisma PHP, and how to organize your project.
+---
+
+This page provides an overview of the folder and file conventions in **Prisma PHP**, and recommendations for organizing your project. It follows the Prisma PHP routing model and mirrors the mental model of a Next.js App Router style project structure, adapted to how Prisma PHP actually works.
+
+## Folder and file conventions
+
+### Top-level folders
+
+Top-level folders are used to organize your application's source code, configuration, database schema, and public assets.
+
+| Folder     | Purpose                                                                       |
+| ---------- | ----------------------------------------------------------------------------- |
+| `src/app`  | File-system based routing, pages, layouts, loading states, and route handlers |
+| `src/Lib`  | Application libraries, generated Prisma classes, auth, middleware, utilities  |
+| `public`   | Public web root, static files, CSS, JS, favicon, and public entry point       |
+| `prisma`   | Prisma schema, migrations, and seed scripts                                   |
+| `settings` | Project configuration such as paths, BrowserSync, and related setup           |
+
+### Top-level files
+
+These files are typically used to configure the app, manage dependencies, and define environment values.
+
+| File                   | Purpose                                                        |
+| ---------------------- | -------------------------------------------------------------- |
+| `composer.json`        | PHP dependencies and autoloading                               |
+| `package.json`         | Frontend tooling and development scripts when used             |
+| `.env`                 | Environment variables                                          |
+| `prisma/schema.prisma` | Main Prisma schema file                                        |
+| `public/index.php`     | Public entry point                                             |
+| `bootstrap.php`        | Application bootstrap and middleware registration when present |
+| `prisma-php.json`      | Project capability manifest and local Prisma PHP configuration |
+
+### `prisma-php.json`
+
+Prisma PHP projects should place `prisma-php.json` in the **repository root**.
+
+This file is the best place to declare enabled project features and local environment metadata because it is easy for tools, scripts, and AI agents to discover next to the rest of the top-level project configuration.
+
+Typical values include:
+
+- `tailwindcss`
+- `backendOnly`
+- `swaggerDocs`
+- `websocket`
+- `mcp`
+- `prisma`
+- `typescript`
+- BrowserSync target configuration
+- PHP executable path
+- component scan directories
+
+If an AI agent is working on the project, it should inspect `prisma-php.json` before deciding whether Tailwind CSS, TypeScript, Prisma ORM, Swagger docs, MCP, or websocket-related code should be generated.
+
+### Full-stack vs backend-only routing decision
+
+One of the most important capability flags is `backendOnly`.
+
+- When `backendOnly` is `false`, the project is a **full-stack Prisma PHP app**. In that mode, normal route UI should be implemented with `index.php`.
+- When `backendOnly` is `true`, the project is a **backend-only Prisma PHP app**. In that mode, route behavior will usually center on direct handlers such as `route.php`.
+- If a `route.php` file exists at a route segment, it acts as the direct handler entry point for that route and should be treated as the API-style or no-view path for that segment.
+- In full-stack projects, if the user asks for a normal route or page, prefer `index.php`. If the user asks for an API route, JSON endpoint, form-processing endpoint, AJAX endpoint, or direct handler, prefer `route.php`.
+
+This helps AI and contributors choose the correct file without guessing based on other frameworks.
+
+### Framework-managed generated files
+
+Some files in a Prisma PHP project are framework-managed and should not be manually maintained as part of normal route work.
+
+#### `files-list.json`
+
+Prisma PHP automatically generates the route list in `files-list.json`.
+
+Do **not** create routes by editing this file. Do **not** manually add, remove, reorder, or “sync” entries in it.
+
+Instead, create or update the correct folders and route files in `src/app`, then let Prisma PHP regenerate `files-list.json` automatically.
+
+When an AI agent is asked to create a route, the correct change is in the route tree itself, not in `files-list.json`.
+
+## Routing files
+
+Prisma PHP uses file-system based routing. Folders define route segments, and special files define how those segments behave.
+
+Routes are defined by the route tree under `src/app`. Prisma PHP then derives route metadata from those files. Because of that, AI agents should never treat `files-list.json` as the place where routes are declared.
+
+| File            | Purpose                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `index.php`     | Public page entry point for a route and rendered UI                  |
+| `layout.php`    | Shared layout for a route subtree                                    |
+| `loading.php`   | Loading UI for a route or subtree                                    |
+| `route.php`     | Direct route handler for APIs, JSON, forms, and logic without a view |
+| `not-found.php` | Not found UI                                                         |
+| `error.php`     | Error handling UI                                                    |
+
+## Nested routes
+
+Folders define URL segments. Nesting folders nests segments. A route becomes publicly accessible when an `index.php` file exists inside that route folder.
+
+| Path                             | URL pattern     | Notes                                                 |
+| -------------------------------- | --------------- | ----------------------------------------------------- |
+| `src/app/layout.php`             | —               | Root layout wraps the application                     |
+| `src/app/index.php`              | `/`             | Public home route                                     |
+| `src/app/blog/index.php`         | `/blog`         | Public nested route                                   |
+| `src/app/blog/authors/index.php` | `/blog/authors` | Public deeply nested route                            |
+| `src/app/blog/route.php`         | `/blog` handler | Direct handler for API-style or programmatic requests |
+
+## Dynamic routes
+
+Dynamic segments are created with square brackets and are available through `Request::$dynamicParams` in `layout.php`, `index.php`, and `route.php`.
+
+| Path                                 | URL pattern                | Notes                  |
+| ------------------------------------ | -------------------------- | ---------------------- |
+| `src/app/blog/[slug]/index.php`      | `/blog/my-first-post`      | Single dynamic segment |
+| `src/app/shop/[id]/index.php`        | `/shop/42`                 | Single param by id     |
+| `src/app/docs/[...slug]/index.php`   | `/docs/a/b/c`              | Catch-all route        |
+| `src/app/users/[username]/route.php` | `/users/jefferson` handler | Dynamic route handler  |
+
+## Route groups and private folders
+
+Prisma PHP supports route groups and private folders to help you organize code without exposing everything as a route.
+
+| Path                                  | URL pattern | Notes                              |
+| ------------------------------------- | ----------- | ---------------------------------- |
+| `src/app/(marketing)/about/index.php` | `/about`    | Route group omitted from URL       |
+| `src/app/(dashboard)/users/index.php` | `/users`    | Grouping without changing URL      |
+| `src/app/blog/_components/Card.php`   | —           | Private implementation detail      |
+| `src/app/blog/_lib/helpers.php`       | —           | Non-routable colocated helper code |
+
+## Middleware
+
+Middleware in Prisma PHP is convention-based. Middleware classes live in `Lib/Middleware` and are registered in `bootstrap.php`.
+
+| Location                                | Purpose                                             |
+| --------------------------------------- | --------------------------------------------------- |
+| `src/Lib/Middleware/AuthMiddleware.php` | Route protection and auth checks                    |
+| `bootstrap.php`                         | Register and invoke middleware                      |
+| Route matching logic                    | Apply middleware based on pathname or request rules |
+
+## Redirects
+
+Redirects are handled with `Request::redirect()`, which sends an HTTP `Location` header and stops execution.
+
+| Pattern                       | Purpose                                       |
+| ----------------------------- | --------------------------------------------- |
+| `Request::redirect('/home')`  | Temporary redirect after an action            |
+| `Request::redirect('/login')` | Redirect unauthenticated users                |
+| Redirect with 3xx semantics   | Standard browser navigation via HTTP redirect |
+
+## Example project structure
+
+```txt
+prisma-php-project/
+├── prisma/
+│   ├── migrations/
+│   ├── schema.prisma
+│   └── seed.ts
+├── public/
+│   ├── assets/
+│   ├── css/
+│   ├── js/
+│   ├── favicon.ico
+│   └── index.php
+├── settings/
+│   ├── bs-config.ts
+│   ├── paths.php
+│   └── restart-websocket.ts
+├── src/
+│   ├── app/
+│   │   ├── layout.php
+│   │   ├── index.php
+│   │   ├── loading.php
+│   │   ├── not-found.php
+│   │   ├── error.php
+│   │   ├── (marketing)/
+│   │   │   ├── layout.php
+│   │   │   └── about/
+│   │   │       └── index.php
+│   │   ├── dashboard/
+│   │   │   ├── layout.php
+│   │   │   ├── index.php
+│   │   │   ├── users/
+│   │   │   │   ├── index.php
+│   │   │   │   └── [id]/
+│   │   │   │       └── index.php
+│   │   │   ├── reports/
+│   │   │   │   └── route.php
+│   │   │   └── _components/
+│   │   │       └── StatsCard.php
+│   │   └── blog/
+│   │       ├── index.php
+│   │       └── [slug]/
+│   │           └── index.php
+│   └── Lib/
+│       ├── Middleware/
+│       │   └── AuthMiddleware.php
+│       ├── Prisma/
+│       └── Auth/
+├── bootstrap.php
+├── composer.json
+├── package.json
+├── prisma-php.json
+└── .env
+```
+
+## Organizing your project
+
+Prisma PHP is flexible about how you organize your project files, but its routing system gives you a clear structure for colocating route-specific code.
+
+### Component hierarchy
+
+In practice, Prisma PHP route rendering usually follows this hierarchy for a given request:
+
+- root `layout.php`
+- nested `layout.php`
+- `loading.php` when applicable
+- `error.php` when applicable
+- `not-found.php` when applicable
+- route `index.php` or `route.php`
+
+Nested layouts wrap their child segments, so layouts compose naturally as you go deeper in the route tree.
+
+### Colocation
+
+Because routing is based on special files such as `index.php` and `route.php`, you can safely colocate route-specific code inside route folders as long as those files are not themselves routable entry files.
+
+This makes it practical to keep related files close together:
+
+- components near the route that uses them
+- helpers near the route logic
+- route-specific services or validators in private folders
+
+### Private folders
+
+Private folders are prefixed with an underscore, such as `_components` or `_lib`.
+
+Use them when you want to:
+
+- separate UI logic from route entry files
+- keep helper code close to a route
+- avoid accidental routing
+- keep naming conventions consistent across a project
+
+### Route groups
+
+Route groups use parentheses, such as `(marketing)` or `(dashboard)`.
+
+Use them when you want to:
+
+- organize routes by section, team, or concern
+- apply a layout to a subset of routes
+- keep the URL clean while improving folder organization
+
+Be careful not to create two grouped routes that resolve to the same final URL.
+
+### Suggested organization patterns
+
+#### Keep routing in `src/app`, shared code in `src/Lib`
+
+This is the clearest default for most Prisma PHP applications:
+
+- `src/app` handles pages, layouts, route handlers, and route-local files
+- `src/Lib` handles framework-level helpers, auth, middleware, and shared utilities
+
+#### Split route-specific code by feature
+
+For large applications, keep shared code near the route that owns it:
+
+```txt
+src/app/dashboard/
+├── layout.php
+├── index.php
+├── users/
+│   ├── index.php
+│   ├── [id]/
+│   │   └── index.php
+│   └── _components/
+│       └── UserTable.php
+└── _lib/
+    └── dashboard-helpers.php
+```
+
+#### Use groups for multiple application sections
+
+This is useful when marketing pages and app pages need different layouts:
+
+```txt
+src/app/
+├── (marketing)/
+│   ├── layout.php
+│   ├── index.php
+│   └── about/
+│       └── index.php
+└── (app)/
+    ├── layout.php
+    ├── dashboard/
+    │   └── index.php
+    └── settings/
+        └── index.php
+```
+
+## Prisma PHP mental model for Next.js App Router users
+
+If you are coming from Next.js App Router, this is the closest mapping:
+
+| Next.js concept | Prisma PHP concept |
+| --------------- | ------------------ |
+| `app/`          | `src/app/`         |
+| `page.tsx`      | `index.php`        |
+| `layout.tsx`    | `layout.php`       |
+| `loading.tsx`   | `loading.php`      |
+| `route.ts`      | `route.php`        |
+| `not-found.tsx` | `not-found.php`    |
+| `error.tsx`     | `error.php`        |
+| `(group)`       | `(group)`          |
+| `_folder`       | `_folder`          |
+| `[slug]`        | `[slug]`           |
+| `[...slug]`     | `[...slug]`        |
+
+The main difference is that Prisma PHP uses PHP entry files and server-rendered route handling instead of React component files, but the route-tree organization model is intentionally very similar.
+
+For route choice, remember this practical rule:
+
+- use `index.php` for normal full-stack pages and route UI
+- use `route.php` for API-style, JSON, AJAX, webhook, or no-view handlers
+- if a segment has a `route.php`, treat it as the direct handler entry point for that route