prisma-php 0.0.10 → 0.0.12

package/.github/copilot-instructions.md

@@ -2,9 +2,11 @@
 
 ## Source Of Truth
 
-- 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.
+- For Prisma PHP applications, treat `node_modules/prisma-php/dist/docs/index.md` as the entry point for the installed framework version.
+- Read the matching doc in `node_modules/prisma-php/dist/docs` before generating or editing framework-specific Prisma PHP code.
+- Expect `AGENTS.md` in the project root and keep it aligned with the installed Prisma PHP docs contract.
+- When updating Prisma PHP package/docs sources in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
+- 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
 
@@ -16,21 +18,32 @@
 ## Component Boundary Rules
 
 - Distinguish PHPX class components from `ImportComponent` partials.
-- `ImportComponent` partials must output exactly one root element because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that root.
+- `ImportComponent` partials must output exactly one root element because Prisma PHP uses that root as the imported component boundary and serializes props there.
 - Do not manually add `pp-component` inside `ImportComponent` partial source; Prisma PHP injects it there. For normal PulsePoint-aware route files, add `pp-component` to the single root element yourself.
 
 ## Relevant Docs
 
 - Project structure and feature placement: `dist/docs/project-structure.md`
+- CLI project creation and update commands: `dist/docs/commands.md`
+- First-time project installation and local setup: `dist/docs/installation.md`
+- Existing-project upgrades and feature refreshes: `dist/docs/upgrading.md`
+- TypeScript frontend tooling, the `typescript` flag, and `ts/main.ts` registration: `dist/docs/typescript.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`
+- Cache behavior and `CacheHandler`: `dist/docs/caching.md`
 - Validation rules: `dist/docs/validator.md`
+- Prisma ORM schema, migrations, and generated PHP classes: `dist/docs/prisma-php-orm.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`
+- Error handling, expected failures, and route error files: `dist/docs/error-handling.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.