prisma-php 0.0.10 → 0.0.12

package/dist/docs/swagger-docs.md

@@ -0,0 +1,189 @@
+---
+title: Swagger docs for APIs
+nav_title: Swagger Docs
+description: Learn when Prisma PHP Swagger docs are worth enabling so AI agents can keep OpenAPI generation aligned with backendOnly and schema-driven workflows.
+related:
+  title: API Reference
+  description: Read the official Swagger and API docs together with the local Prisma PHP guidance.
+  links:
+    - /docs/swagger-docs-api
+    - /docs/api-get-started
+    - /docs/route-php
+    - /docs/orm-get-started
+---
+
+## Swagger docs in Prisma PHP
+
+Prisma PHP can generate Swagger-friendly OpenAPI documentation for API workflows.
+
+This is most useful when the project exposes endpoints for:
+
+- a separate frontend
+- mobile clients
+- public or partner APIs
+- SDK generation
+- API testing and contract review
+
+If the application is mainly a server-rendered Prisma PHP app that uses PulsePoint and `pp.fetchFunction(...)` for route-local interactions, Swagger docs may not be necessary.
+
+If a task involves OpenAPI generation, backend-only APIs, external client contracts, or schema-driven endpoint docs, AI agents should read this page first and keep the Swagger workflow aligned with `prisma-php.json`.
+
+## AI rule: read the Swagger docs first
+
+Before enabling or regenerating Swagger docs, use this order:
+
+1. Inspect `prisma-php.json` for `swaggerDocs` and `backendOnly`.
+2. Read `backend-only.md`, `route-handlers.md`, and `prisma-php-orm.md` as needed for the surrounding API workflow.
+3. Use `npm run create-swagger-docs` for the documented generation flow.
+4. Inspect `settings/prisma-schema-config.json` before changing output paths or generation modes.
+5. Do not treat Swagger generation as a substitute for ORM migrations or route implementation.
+
+## When Swagger docs are worth enabling
+
+Enable Swagger docs when you need a stable machine-readable contract for the API.
+
+Typical reasons include:
+
+- generating typed frontend clients
+- sharing endpoint definitions with other teams
+- reviewing request and response shapes outside the codebase
+- keeping backend-only or API-heavy projects documented as they evolve
+
+In Prisma PHP, the project-level feature flag is `swaggerDocs` in `prisma-php.json`.
+
+```json filename="prisma-php.json"
+{
+  "backendOnly": true,
+  "swaggerDocs": true
+}
+```
+
+If you enable the flag in an existing application, follow the documented project update flow from `upgrading.md`.
+
+## Generated OpenAPI JSON
+
+When Prisma PHP generates Swagger docs, the OpenAPI JSON file is created or updated at:
+
+```txt
+src/app/swagger-docs/apis/pphp-swagger.json
+```
+
+That JSON file is the handoff point for tools such as:
+
+- Swagger UI
+- OpenAPI Generator
+- `openapi-zod-client`
+- `openapi-typescript`
+- `orval`
+
+## Generation command
+
+Prisma PHP's Swagger workflow supports generating documentation for models from `schema.prisma`.
+
+```bash package="npm"
+npm run create-swagger-docs
+npm run create-swagger-docs Order
+npm run create-swagger-docs Order User Client
+```
+
+During generation, Prisma PHP prompts for three decisions:
+
+- whether to generate Swagger docs only
+- whether to generate endpoints
+- whether to generate PHP classes
+
+That makes the workflow flexible enough for:
+
+- docs-only regeneration
+- endpoint scaffolding together with docs
+- PHP class generation when the project needs it
+
+## Configuration file
+
+Swagger generation can be customized from:
+
+```txt
+settings/prisma-schema-config.json
+```
+
+Example configuration:
+
+```json filename="settings/prisma-schema-config.json"
+{
+  "swaggerDocsDir": "src/app/swagger-docs/apis",
+  "skipDefaultName": ["autoincrement", "cuid", "uuid", "now"],
+  "skipByPropertyValue": {
+    "isUpdatedAt": true
+  },
+  "skipFields": [],
+  "generateSwaggerDocsOnly": false,
+  "generateEndpoints": true,
+  "generatePhpClasses": true
+}
+```
+
+This file is where the Prisma PHP Swagger workflow decides:
+
+- where the JSON should be written
+- which schema defaults should be omitted from docs output
+- which fields should be skipped entirely
+- whether generation should include only docs, endpoints, PHP classes, or a combination
+
+## Recommended workflow
+
+For API-oriented Prisma PHP work, a practical Swagger workflow is:
+
+1. update `schema.prisma`
+2. run the normal ORM workflow when the schema changed
+3. regenerate Swagger docs
+4. inspect `src/app/swagger-docs/apis/pphp-swagger.json`
+5. regenerate external clients if the contract changed
+
+This keeps the API description aligned with the current schema and route generation output.
+
+## Backend-only projects and Swagger
+
+Swagger docs fit especially well with backend-only Prisma PHP projects because those apps usually center on `route.php` handlers and separate consumers.
+
+The common pairing is:
+
+- `backendOnly: true`
+- `swaggerDocs: true`
+
+That gives the project a clear API-first posture: handler routes in Prisma PHP, plus an OpenAPI file that frontend and external clients can consume.
+
+Read `backend-only.md` when the task is primarily about route structure, CORS, or the default API project shape.
+
+## React and TypeScript client generation
+
+One common use case is generating a typed client for a separate React or TypeScript application.
+
+```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
+```
+
+After generation, the consuming app can validate server responses against the generated schemas instead of relying on handwritten request types.
+
+## What Swagger does not replace
+
+Swagger docs help describe the API contract, but they do not replace:
+
+- request validation with `PP\Validator`
+- route-level method guards
+- ORM migration and client generation when `schema.prisma` changes
+- CORS configuration when external frontends call the API directly
+
+Keep those concerns aligned with `route-handlers.md`, `validator.md`, `prisma-php-orm.md`, and `backend-only.md`.
+
+## Decision guide
+
+Use this page when the task is about:
+
+- `swaggerDocs` in `prisma-php.json`
+- `pphp-swagger.json`
+- `npm run create-swagger-docs`
+- `settings/prisma-schema-config.json`
+- OpenAPI client generation from Prisma PHP
+
+Use `backend-only.md` when the main question is how a backend-only Prisma PHP app should be structured.

package/dist/docs/typescript.md

@@ -0,0 +1,195 @@
+---
+title: TypeScript & NPM
+nav_title: TypeScript
+description: Learn how Prisma PHP uses the `typescript` feature flag so AI agents can place TypeScript in `ts/`, register browser helpers from `ts/main.ts`, and use them safely from PulsePoint component roots.
+related:
+  title: Related docs
+  description: Read the Prisma PHP docs that define feature flags, project updates, and PulsePoint component boundaries before generating TypeScript-aware examples.
+  links:
+    - /docs/commands
+    - /docs/upgrading
+    - /docs/project-structure
+    - /docs/pulsepoint
+    - /docs/components
+---
+
+Prisma PHP TypeScript support should follow the framework's Vite-backed frontend workflow, not ad hoc inline module imports inside `index.php`, `layout.php`, or imported partials.
+
+If a task involves the `typescript` flag in `prisma-php.json`, the root `ts/` directory, `ts/main.ts`, frontend npm packages, or using registered browser helpers inside PulsePoint templates and scripts, AI agents should read this page first and keep the implementation aligned with Prisma PHP's component boundary rules.
+
+## AI rule: read the TypeScript docs first
+
+Before generating, editing, or reviewing TypeScript-related frontend code, use this order:
+
+1. Read `./prisma-php.json` in a generated Prisma PHP app and confirm whether `typescript` is enabled.
+2. For an existing app, enable `typescript` first, then run `npx pp update project -y`.
+3. Keep reusable frontend TypeScript modules in the root `ts/` directory.
+4. Use `ts/main.ts` as the entry file that registers browser helpers for runtime use.
+5. Use those registered globals from template expressions and PulsePoint component scripts.
+6. Keep inline route or partial `<script>` blocks as plain JavaScript. Do not place `import` or `export` inside them.
+
+Do not guess from React, Vue, Next.js, or generic Vite projects alone. Prisma PHP still follows its own PulsePoint component and route-file rules.
+
+## Read this doc when you need
+
+- **the `typescript` feature flag in `prisma-php.json` or the `--typescript` create flag** -> `commands.md`, `upgrading.md`, and `typescript.md`
+- **where TypeScript files should live in a Prisma PHP app** -> `project-structure.md` and `typescript.md`
+- **how to use registered browser helpers inside a normal PulsePoint route root** -> `layouts-and-pages.md`, `pulsepoint.md`, and `typescript.md`
+- **how to use the same helpers inside an imported single-root partial** -> `components.md` and `typescript.md`
+- **installing npm packages for frontend utilities** -> `typescript.md`
+
+## When TypeScript is enabled
+
+When `typescript` is enabled in `prisma-php.json`, Prisma PHP can use a Vite-powered frontend TypeScript workflow.
+
+The practical rules are:
+
+- keep browser-side TypeScript modules in `ts/`
+- use `ts/main.ts` as the registration entry file
+- install npm packages normally
+- expose the browser helpers you want to call from templates or PulsePoint scripts
+- keep inline PulsePoint scripts as plain JavaScript and call the registered globals from there
+
+## Enable TypeScript in a new or existing app
+
+### New project
+
+```bash package="npm"
+npx create-prisma-php-app my-app --typescript
+```
+
+### Existing project
+
+Enable the feature in `prisma-php.json`, then refresh the project files.
+
+```json filename="prisma-php.json"
+{
+  "projectName": "my-app",
+  "typescript": true
+}
+```
+
+```bash package="npm"
+npx pp update project -y
+```
+
+For broader project refresh guidance, read `upgrading.md`.
+
+## The `ts/` directory
+
+For organization and reuse, keep frontend TypeScript logic in the root `ts/` directory.
+
+This keeps module code out of route files and makes the frontend entry pipeline explicit.
+
+Example layout:
+
+```txt
+ts/
+├── date-utils.ts
+├── global-functions.ts
+├── main.ts
+└── to-money.ts
+```
+
+Example utility:
+
+```ts filename="ts/to-money.ts"
+export function toMoney(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+## Use any npm package
+
+Because this workflow is Vite-backed, you can install npm packages and import them directly into files under `ts/`.
+
+```bash package="npm"
+npm install date-fns
+```
+
+```ts filename="ts/date-utils.ts"
+import { format } from "date-fns";
+
+export function getToday(): string {
+  return format(new Date(), "yyyy-MM-dd");
+}
+```
+
+## Register helpers in `ts/main.ts`
+
+Use the TypeScript entry file to register the browser helpers you want available globally.
+
+```ts filename="ts/main.ts"
+import { createGlobalSingleton } from "./global-functions";
+import { getToday } from "./date-utils";
+import { toMoney } from "./to-money";
+
+createGlobalSingleton("getToday", getToday);
+createGlobalSingleton("toMoney", toMoney);
+```
+
+After registration, those helpers can be used from Prisma PHP template expressions and PulsePoint component scripts without adding `import` statements inside the route file itself.
+
+## Important PulsePoint boundary
+
+Prisma PHP inline component scripts are plain JavaScript, not module files.
+
+That means the right split is:
+
+- write reusable module logic in `ts/`
+- register the pieces you need from `ts/main.ts`
+- call those registered helpers from the inline PulsePoint script inside the component root
+- do not place `import` or `export` inside the inline route or imported-partial script
+
+When the UI lives in `index.php` or nested `layout.php`, keep the normal Prisma PHP route structure:
+
+1. PHP first
+2. one parent HTML element
+3. `pp-component` on that route root when PulsePoint is present
+4. one `<script>` block as the last child inside that same root element
+
+When the UI lives in an imported partial rendered through `ImportComponent::render(...)`, keep exactly one root element and place any component-local `<script>` inside that root. Do not manually add `pp-component` inside the imported partial source.
+
+## Usage inside a PulsePoint route
+
+This example keeps the route in the current Prisma PHP single-root component pattern while calling helpers registered from `ts/main.ts`.
+
+```php filename="src/app/index.php"
+<?php
+
+use PP\MainLayout;
+
+MainLayout::$title = 'TypeScript Helpers';
+MainLayout::$description = 'Use registered TypeScript helpers from a PulsePoint route.';
+?>
+
+<section pp-component="typescript-demo-page">
+    <h1>TypeScript helpers</h1>
+    <p>Today: {getToday()}</p>
+    <p>Catalog price: {toMoney(1234.56)}</p>
+    <p>Discounted price: {discountedPrice}</p>
+
+    <button onclick="applyDiscount()">Apply discount</button>
+
+    <script>
+        const [discountedPrice, setDiscountedPrice] = pp.state(toMoney(15245));
+
+        function applyDiscount() {
+            setDiscountedPrice(toMoney(11999.5));
+        }
+    </script>
+</section>
+```
+
+The helper calls stay available in both template expressions and the inline PulsePoint script, while the route still follows the documented Prisma PHP component boundary rules.
+
+## AI rules for TypeScript tasks
+
+- inspect `prisma-php.json` first and confirm whether `typescript` is enabled
+- for existing apps, enable the feature and run `npx pp update project -y` before assuming the TypeScript scaffold exists
+- keep reusable module code in `ts/`
+- register browser helpers from `ts/main.ts`
+- use npm packages through normal imports inside `ts/` files
+- do not place `import` or `export` inside inline PulsePoint scripts in `index.php`, `layout.php`, or imported partials
+- keep normal route files in the single-root PulsePoint pattern with the `<script>` as the last child inside the route root
+- keep `ImportComponent` partials in the single-root pattern and let Prisma PHP inject `pp-component` there automatically

package/dist/docs/upgrading.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading
-description: Learn how to upgrade your Prisma PHP application, enable framework features, and refresh your project safely.
+description: Learn how to upgrade your Prisma PHP application so AI agents can enable features and refresh framework-managed files safely.
 related:
   title: Related docs
   description: Review the Prisma PHP docs for commands, project setup, and feature configuration.
@@ -27,6 +27,8 @@ npx pp update project -y
 
 The `-y` flag runs the update in non-interactive mode, which is the recommended choice for AI-driven project updates and scripted automation.
 
+If a task involves refreshing an existing Prisma PHP app, enabling saved feature flags, or syncing framework-managed files, AI agents should read this page first and prefer the documented non-interactive update flow for automation.
+
 ## Before you update
 
 Before running the update command, review your `prisma-php.json` file.
@@ -45,6 +47,8 @@ npx pp update project -y
 
 This ensures the update process applies the correct files, dependencies, and project structure for the features you selected.
 
+If the feature you are enabling is API-focused, read `backend-only.md` for `backendOnly` usage and `swagger-docs.md` for `swaggerDocs` generation workflow details.
+
 ## Typical upgrade flow
 
 Use this workflow when upgrading an existing Prisma PHP application:
@@ -52,17 +56,17 @@ Use this workflow when upgrading an existing Prisma PHP application:
 1. Open `prisma-php.json`.
 2. Enable or review the features your project should use.
 3. Save the file.
-4. Run the update command:
+4. Run the update command.
 
-```bash package="npm"
-npx pp update project
-```
+    ```bash package="npm"
+    npx pp update project
+    ```
 
-For AI agents or automation, use:
+    For AI agents or automation, use:
 
-```bash package="npm"
-npx pp update project -y
-```
+    ```bash package="npm"
+    npx pp update project -y
+    ```
 
 5. Reinstall or verify project dependencies if needed.
 6. Test the application locally.

package/dist/docs/websocket.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Read the official Prisma PHP websocket docs before generating or editing realtime code.
   links:
+    - /docs/env
     - /docs/websocket-get-started
     - /docs/websocket-chat-app
     - /docs/project-structure
@@ -35,6 +36,7 @@ Do not assume another framework's realtime abstractions apply directly.
 
 - **Ratchet setup, `IoServer`, `HttpServer`, `WsServer`, `ConnectionManager`, `MessageComponentInterface`, `SplObjectStorage`, or websocket server structure** -> official `websocket-get-started`
 - **chat-style websocket examples or broadcast behavior** -> official `websocket-chat-app`
+- **typed environment access for `WS_*` values, `APP_TIMEZONE`, or `.env` loading boundaries** -> `env.md` plus `websocket.md`
 - **feature flags and scaffolding for websocket support** -> `upgrading.md` plus `websocket.md`
 - **where websocket-related files belong in a Prisma PHP project** -> `project-structure.md` plus `websocket.md`
 - **interactive route UI that reacts to websocket events** -> `pulsepoint.md` and `fetching-data.md` plus `websocket.md`
@@ -101,6 +103,8 @@ AI should preserve these settings and precedence rules:
 - `APP_TIMEZONE` with fallback `UTC`
 - CLI overrides through `--host=...`, `--port=...`, and `--verbose=...`
 
+These runtime values are read through `PP\Env`, whose implementation lives in `vendor/tsnc/prisma-php/src/Env.php`.
+
 The effective host and port resolve in this order:
 
 1. CLI arguments

package/package.json

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