prisma-php 0.0.10 → 0.0.11

package/.github/copilot-instructions.md

@@ -5,6 +5,7 @@
 - Treat `dist/docs/index.md` as the entry point for Prisma PHP guidance in this repo.
 - Read the matching doc in `dist/docs` before generating or editing framework-specific Prisma PHP code.
 - When updating AI guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned.
+- Keep every `dist/docs/*.md` page AI-discoverable on its own: the frontmatter description and opening section should clearly say when agents should read that file and which adjacent docs to consult next.
 
 ## Route File Conventions
 
@@ -22,15 +23,20 @@
 ## Relevant Docs
 
 - Project structure and feature placement: `dist/docs/project-structure.md`
+- CLI project creation and update commands: `dist/docs/commands.md`
+- Backend-only API usage and `backendOnly`: `dist/docs/backend-only.md`
 - Route and layout structure: `dist/docs/layouts-and-pages.md`
+- AI integration, provider-backed chat, streaming, and MCP boundary: `dist/docs/get-started-ia.md`
 - Data loading, `#[Exposed]`, and SSE streaming: `dist/docs/fetching-data.md`
 - PulsePoint runtime rules: `dist/docs/pulsepoint.md`
 - Component and `ImportComponent` rules: `dist/docs/components.md`
 - Validation rules: `dist/docs/validator.md`
+- Environment variables and `PP\Env` usage: `dist/docs/env.md`
 - File uploads and file manager behavior: `dist/docs/file-manager.md`
 - Email and SMTP workflows: `dist/docs/email.md`
 - WebSocket and realtime behavior: `dist/docs/websocket.md`
 - MCP server and tool rules: `dist/docs/mcp.md`
 - Authentication: `dist/docs/authentication.md`
 - Metadata and icons: `dist/docs/metadata-and-og-images.md`
-- API-style handlers and webhooks: `dist/docs/route-handlers.md`
+- API-style handlers and webhooks: `dist/docs/route-handlers.md`
+- Swagger/OpenAPI generation and `swaggerDocs`: `dist/docs/swagger-docs.md`

package/dist/docs/backend-only.md

@@ -0,0 +1,204 @@
+---
+title: Backend-only API usage
+nav_title: Backend-only APIs
+description: Learn how Prisma PHP backend-only apps work so AI agents can choose route.php-first API patterns, connect separate clients safely, and keep backendOnly workflows aligned with the framework.
+related:
+  title: API Reference
+  description: Read the official Prisma PHP API and Swagger docs alongside the local backend-only guidance.
+  links:
+    - /docs/api-get-started
+    - /docs/route-php
+    - /docs/php-validator
+    - /docs/swagger-docs-api
+---
+
+## Backend-only Prisma PHP
+
+Prisma PHP can run as a backend-only application when the project is intended to serve JSON endpoints, webhooks, mobile clients, or a separate frontend instead of rendering route UI with `index.php`.
+
+In that mode, the main project-level flag is `backendOnly` in `prisma-php.json`.
+
+If a task involves API-first Prisma PHP usage, separate frontend consumers, CORS, webhooks, or machine-facing endpoints, AI agents should read this page first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the backend-only docs first
+
+Before generating backend-only Prisma PHP code, use this order:
+
+1. Read `prisma-php.json`.
+2. Confirm that `backendOnly` is enabled or that the user explicitly wants API-first behavior.
+3. Read this `backend-only.md` page.
+4. Use `route-handlers.md`, `validator.md`, and `swagger-docs.md` for handler, validation, and contract workflow details.
+5. Inspect the current route tree before inventing extra API structure.
+
+```json filename="prisma-php.json"
+{
+  "backendOnly": true,
+  "swaggerDocs": true
+}
+```
+
+When `backendOnly` is `true`, the routing mental model changes:
+
+- use `route.php` as the default route entry for normal application behavior
+- treat `src/app/route.php` as the root handler for `/`
+- create nested folders under `src/app` and place `route.php` inside them for additional endpoints
+- do not default to `index.php` unless the project is intentionally mixing in rendered UI
+
+This is different from the normal full-stack Prisma PHP flow, where route UI lives in `index.php` and PulsePoint usually drives interactivity.
+
+## When backend-only is the right fit
+
+Backend-only Prisma PHP is the better fit when you want:
+
+- a separate frontend such as React, Vue, Angular, Flutter, or a mobile app
+- API-first development where routes return JSON instead of HTML
+- webhook handlers, service-to-service endpoints, or integration APIs
+- OpenAPI-driven client generation for external consumers
+
+If the project is primarily a rendered Prisma PHP app with route-local interactivity, prefer the full-stack `index.php` plus PulsePoint model instead.
+
+## Route structure
+
+Backend-only projects still use Prisma PHP's file-system routing under `src/app`.
+
+Typical shapes look like this:
+
+```txt
+src/
+  app/
+    route.php
+    products/
+      route.php
+    users/
+      route.php
+```
+
+That creates handler-style routes such as:
+
+- `/`
+- `/products`
+- `/users`
+
+Use nested folders when the URL needs nested segments. Do not create routes by editing `files-list.json`; Prisma PHP manages route metadata automatically.
+
+## Basic route handler pattern
+
+For backend-only apps, the default route file should stay explicit and small:
+
+1. guard the HTTP method
+2. read values from `Request::$params`
+3. sanitize and validate input with `PP\Validator`
+4. query Prisma or run server logic
+5. return JSON with `echo json_encode(...)`
+
+```php filename="src/app/products/route.php"
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+use PP\Header\Boom;
+use PP\Request;
+
+if (!Request::$isGet) {
+    Boom::methodNotAllowed()->toResponse();
+    exit;
+}
+
+$prisma = Prisma::getInstance();
+
+$products = $prisma->product->findMany();
+
+echo json_encode($products);
+```
+
+For validation-heavy handlers, use `validator.md` together with `route-handlers.md`.
+
+## Request data in backend-only routes
+
+Prisma PHP exposes unified request data through `Request::$params`, so you do not need to manually switch between `$_GET`, `$_POST`, and JSON body parsing for ordinary handler work.
+
+```php filename="src/app/products/search/route.php"
+<?php
+
+use Lib\Prisma\Classes\Prisma;
+use PP\Request;
+use PP\Validator;
+
+$prisma = Prisma::getInstance();
+
+$productName = Validator::string(Request::$params['productName'] ?? '');
+
+$products = $prisma->product->findMany([
+    'where' => [
+        'name' => [
+            'contains' => $productName,
+        ],
+    ],
+]);
+
+echo json_encode($products);
+```
+
+For expected input failures, prefer structured JSON error payloads or `Boom` responses instead of uncaught exceptions.
+
+## CORS for separate frontends
+
+If a separate frontend will call the API directly, configure CORS in `.env`.
+
+Typical settings include:
+
+```env
+CORS_ALLOWED_ORIGINS=[]
+CORS_ALLOW_CREDENTIALS="true"
+CORS_ALLOWED_METHODS="GET,POST,PUT,PATCH,DELETE,OPTIONS"
+CORS_ALLOWED_HEADERS="Content-Type,Authorization,X-Requested-With"
+CORS_EXPOSE_HEADERS=""
+CORS_MAX_AGE="86400"
+```
+
+If you are using a local frontend such as Vite, add that frontend URL to `CORS_ALLOWED_ORIGINS`.
+
+## OpenAPI and Swagger in backend-only projects
+
+If the project also enables Swagger docs, Prisma PHP can generate an OpenAPI 3 document that external clients can consume.
+
+The generated JSON lives at:
+
+```txt
+./src/app/swagger-docs/apis/pphp-swagger.json
+```
+
+This makes backend-only Prisma PHP projects easier to connect to:
+
+- React or TypeScript clients
+- Angular or Vue applications
+- mobile SDK generation workflows
+- language-specific OpenAPI generators
+
+For the generation workflow itself, read `swagger-docs.md`.
+
+## Example frontend client workflow
+
+One practical backend-only pattern is to generate a client from the Swagger JSON and validate responses in the consuming app.
+
+For example, a TypeScript client can use tools such as `openapi-zod-client`, `openapi-typescript`, `orval`, or other OpenAPI generators.
+
+```bash package="npm"
+npm i -D openapi-zod-client
+npx openapi-zod-client --input http://localhost:3000/swagger-docs/apis/pphp-swagger.json --output ./client/src/api/pphp.ts
+```
+
+The important idea is that Prisma PHP becomes the API backend, while the consuming frontend treats the generated OpenAPI document as the contract.
+
+## Decision guide
+
+Use this page when the task is about:
+
+- `backendOnly` in `prisma-php.json`
+- API-first Prisma PHP apps
+- separate frontend consumption
+- CORS for external clients
+- choosing `route.php` as the default route file in the project
+
+Use `route-handlers.md` when the task is specifically about request handling behavior inside a handler.
+
+Use `swagger-docs.md` when the task is specifically about generating or customizing the OpenAPI document.

package/dist/docs/commands.md

@@ -0,0 +1,453 @@
+---
+title: Commands
+description: Learn the core Prisma PHP CLI commands so AI agents can choose the right create, update, and non-interactive project workflows.
+related:
+  title: Related docs
+  description: Use installation for first-time setup and upgrading for feature refreshes on existing apps.
+  links:
+    - /docs/installation
+    - /docs/upgrading
+---
+
+This guide explains what each Prisma PHP CLI command does, when to use it, and how the create and update workflows fit together.
+
+If a task involves CLI project creation, starter kits, feature flags, or refreshing an existing Prisma PHP app, AI agents should read this page first and keep project creation separate from existing-project updates.
+
+## AI rule: read the commands docs first
+
+Before generating Prisma PHP CLI commands, use this order:
+
+1. Decide whether the task is for a brand-new app or an existing project.
+2. Use `create-prisma-php-app` only for new projects.
+3. Use `npx pp update project` only for existing projects that already have `prisma-php.json`.
+4. For AI-driven or scripted workflows, prefer the documented non-interactive `-y` flag.
+5. Read `prisma-php-orm.md` before suggesting ORM migration or generation commands.
+
+## Main idea
+
+Prisma PHP has two main command groups:
+
+- `create-prisma-php-app` creates a new project
+- `pp update project` refreshes an existing project from the saved `prisma-php.json` configuration
+
+Use `create` when you are starting a new project.
+
+Use `update` when the project already exists and you want to re-apply the saved project configuration, enable newly saved features, or refresh framework-managed files.
+
+## Command reference
+
+### Create a new project
+
+```bash package="npm"
+npx create-prisma-php-app@<version> <project-name> [feature flags] [-y]
+```
+
+If you omit `@<version>`, `npx` uses the default published package resolution.
+
+### Update an existing project
+
+```bash package="npm"
+npx pp update project [@version-or-tag] [-y]
+```
+
+Run this inside an existing Prisma PHP project that already has `prisma-php.json`.
+
+## Create project command
+
+### `npx create-prisma-php-app <project-name>`
+
+This is the main Prisma PHP project generator.
+
+It creates a new project, installs the selected feature set, writes the initial configuration, creates the folder structure, and prepares the app for local development.
+
+During project creation, the selected feature flags are written into `prisma-php.json`. Those saved values are what later allow `npx pp update project` to refresh the project without re-entering every option manually.
+
+### Use this when
+
+- creating a brand-new Prisma PHP project
+- starting from a starter kit
+- scaffolding a project with selected features already enabled
+- automating project creation in scripts or CI
+
+### Basic examples
+
+```bash package="npm"
+npx create-prisma-php-app my-app
+npx create-prisma-php-app my-app -y
+npx create-prisma-php-app my-app --backend-only --prisma --swagger-docs
+npx create-prisma-php-app my-app --tailwindcss --typescript --prisma
+npx create-prisma-php-app my-app --tailwindcss --typescript --websocket --mcp --prisma --swagger-docs
+npx create-prisma-php-app my-app --starter-kit=basic
+npx create-prisma-php-app my-app --starter-kit=fullstack --typescript -y
+npx create-prisma-php-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo --prisma --tailwindcss
+npx create-prisma-php-app --list-starter-kits
+```
+
+## Non-interactive mode
+
+### `-y`
+
+This flag enables non-interactive mode.
+
+Instead of stopping for terminal prompts, the CLI proceeds with the provided flags and default values.
+
+### Use this when
+
+- running automation or CI
+- scaffolding quickly without prompts
+- generating predictable output from scripts
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app -y
+```
+
+## Create command feature flags
+
+### `--backend-only`
+
+Creates a backend-only project.
+
+This is appropriate for API-first or server-only applications where the project should center on handler-style routes instead of the usual full-stack page flow.
+
+### Use this when
+
+- building REST APIs
+- creating server-only services
+- building a backend for a separate frontend client
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --backend-only
+```
+
+### `--swagger-docs`
+
+Enables Swagger and OpenAPI documentation support.
+
+This prepares the project for API schema generation and API documentation workflows.
+
+### Use this when
+
+- documenting API endpoints
+- sharing API contracts with frontend or third-party consumers
+- generating OpenAPI-based tooling from the project
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --backend-only --swagger-docs
+```
+
+### `--tailwindcss`
+
+Enables Tailwind CSS support.
+
+This prepares frontend styling with Tailwind-related files and scripts.
+
+### Use this when
+
+- building dashboards or admin panels
+- creating a styled full-stack UI
+- starting a project that should use utility-first CSS from day one
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --tailwindcss
+```
+
+### `--typescript`
+
+Enables TypeScript support for the frontend toolchain.
+
+### Use this when
+
+- you want typed frontend code
+- you want stronger editor tooling for frontend work
+- your project will include frontend TypeScript assets
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --typescript
+```
+
+### `--websocket`
+
+Enables WebSocket support.
+
+This prepares the project for real-time server and client workflows.
+
+### Use this when
+
+- building chat systems
+- creating live dashboards
+- sending notifications or push-style realtime updates
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --websocket
+```
+
+### `--mcp`
+
+Enables MCP support.
+
+This prepares the project for Model Context Protocol server and tool workflows.
+
+### Use this when
+
+- integrating AI tooling
+- exposing tools through MCP
+- building model-connected workflows
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --mcp
+```
+
+### `--prisma`
+
+Enables Prisma ORM support.
+
+This prepares the project for database-backed development and ORM generation workflows.
+
+### Use this when
+
+- your project needs a database
+- you want Prisma ORM available from the start
+- you are building CRUD apps, APIs, dashboards, or content systems
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --prisma
+```
+
+## Starter kits
+
+### `--list-starter-kits`
+
+Shows the starter kits available in the installed CLI version.
+
+Use this before choosing a starter if you want to inspect the currently supported templates.
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app --list-starter-kits
+```
+
+### `--starter-kit=<kit>`
+
+Creates the project from a starter kit.
+
+Starter kits provide opinionated starting points so you do not have to assemble every feature combination manually.
+
+The exact built-in starter kit names depend on the installed CLI version, so `--list-starter-kits` is the safest way to confirm the current list.
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --starter-kit=basic
+```
+
+### `--starter-kit-source=<url>`
+
+Uses a custom external starter kit source.
+
+This is intended for custom or team-managed boilerplates and is typically paired with `--starter-kit=custom`.
+
+### Example
+
+```bash package="npm"
+npx create-prisma-php-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo
+```
+
+## Combining create flags
+
+You can combine multiple feature flags during project creation.
+
+### Example: full-stack app
+
+```bash package="npm"
+npx create-prisma-php-app my-app --tailwindcss --typescript --prisma
+```
+
+### Example: realtime app
+
+```bash package="npm"
+npx create-prisma-php-app my-app --tailwindcss --typescript --websocket --mcp --prisma --swagger-docs
+```
+
+### Example: backend API
+
+```bash package="npm"
+npx create-prisma-php-app my-app --backend-only --prisma --swagger-docs
+```
+
+### Example: automated generation
+
+```bash package="npm"
+npx create-prisma-php-app my-app --starter-kit=fullstack --typescript -y
+```
+
+## Update command
+
+### `npx pp update project`
+
+This is the dedicated updater for an existing Prisma PHP project.
+
+It reads the saved project configuration from `prisma-php.json`, then refreshes the project using those saved values instead of asking you to pass the full feature set again.
+
+Use this when the project already exists and you want to regenerate or refresh framework-managed files.
+
+If you are enabling or changing features on an existing project, update `prisma-php.json` first, then run `npx pp update project`.
+
+### Example
+
+```bash package="npm"
+npx pp update project
+```
+
+### `npx pp update project @latest`
+
+Refreshes the current project using the latest published version of `create-prisma-php-app`.
+
+### Example
+
+```bash package="npm"
+npx pp update project @latest
+```
+
+### `npx pp update project @v5-alpha`
+
+Refreshes the project using a tagged prerelease such as an alpha build.
+
+### Use this when
+
+- testing prerelease framework changes
+- validating upcoming CLI behavior
+- trying an experimental version on an existing project
+
+### Example
+
+```bash package="npm"
+npx pp update project @v5-alpha
+```
+
+### `npx pp update project @1.2.3`
+
+Refreshes the project using a fixed package version.
+
+### Use this when
+
+- you need reproducible updates
+- you want to stay on a known working version
+- you want strict version control over generator behavior
+
+### Example
+
+```bash package="npm"
+npx pp update project @1.2.3
+```
+
+### `npx pp update project -y`
+
+Runs the update in non-interactive mode.
+
+This skips the confirmation prompt and proceeds directly.
+
+### Use this when
+
+- running scripted updates
+- using CI or automation
+- updating from AI-driven workflows
+
+### Example
+
+```bash package="npm"
+npx pp update project -y
+```
+
+### Combined update examples
+
+```bash package="npm"
+npx pp update project
+npx pp update project -y
+npx pp update project @latest
+npx pp update project @v5-alpha
+npx pp update project @1.2.3
+npx pp update project @latest -y
+npx pp update project @v5-alpha -y
+npx pp update project @1.2.3 -y
+```
+
+## Important update clarification
+
+`npx pp update project` is a project scaffolding and refresh command.
+
+It is not a substitute for Prisma ORM schema migration commands.
+
+If your database schema changed, use the Prisma ORM workflow documented in `prisma-php-orm.md` and `upgrading.md`.
+
+## Recommended mental model
+
+### Use create when
+
+- starting a new project
+- selecting a starter kit for the first time
+- choosing feature flags for initial scaffolding
+- generating a project structure from scratch
+
+### Use update when
+
+- the project already has `prisma-php.json`
+- you want to refresh default project files
+- you want to keep the saved feature set
+- you want to move the project to a newer or pinned generator version
+
+## Quick summary table
+
+| Command                               | What it does                          | Best use case                           |
+| ------------------------------------- | ------------------------------------- | --------------------------------------- |
+| `npx create-prisma-php-app my-app`    | Creates a new project                 | Starting fresh                          |
+| `npx create-prisma-php-app my-app -y` | Creates a new project without prompts | Automation or CI                        |
+| `--backend-only`                      | Creates a server-only setup           | APIs or services                        |
+| `--swagger-docs`                      | Enables API docs                      | Documented APIs                         |
+| `--tailwindcss`                       | Enables Tailwind styling              | UI projects                             |
+| `--typescript`                        | Enables TypeScript support            | Typed frontend work                     |
+| `--websocket`                         | Enables realtime support              | Chat or live updates                    |
+| `--mcp`                               | Enables MCP support                   | AI or tool workflows                    |
+| `--prisma`                            | Enables Prisma ORM support            | Database-backed projects                |
+| `--list-starter-kits`                 | Lists starter templates               | Inspect available starters              |
+| `--starter-kit=<kit>`                 | Creates a project from a starter kit  | Opinionated bootstrapping               |
+| `--starter-kit-source=<url>`          | Uses a custom external starter kit    | Team or company boilerplates            |
+| `npx pp update project`               | Refreshes an existing project         | Existing Prisma PHP apps                |
+| `npx pp update project @latest`       | Uses the latest generator version     | Upgrade to the newest published version |
+| `npx pp update project @v5-alpha`     | Uses a prerelease tag                 | Testing alpha behavior                  |
+| `npx pp update project @1.2.3`        | Uses a fixed version                  | Reproducible updates                    |
+| `npx pp update project -y`            | Updates without prompts               | Automation or CI                        |
+
+## Final recommendation
+
+For most users, start with:
+
+```bash package="npm"
+npx create-prisma-php-app my-app
+```
+
+Then add only the flags you actually need.
+
+Later, use:
+
+```bash package="npm"
+npx pp update project
+```
+
+when you want to refresh an existing project with its saved Prisma PHP configuration.