prisma-php 0.0.10 → 0.0.12

package/dist/docs/commands.md

@@ -0,0 +1,458 @@
+---
+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
+    - /docs/typescript
+---
+
+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.
+
+When this flag is enabled, Prisma PHP should keep frontend TypeScript in the root `ts/` directory, register browser helpers from `ts/main.ts`, and use those registered globals from template expressions and PulsePoint component scripts.
+
+Read `typescript.md` for the TypeScript-specific workflow.
+
+### 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.

package/dist/docs/email.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Read the official Prisma PHP email docs before generating or editing mail flows.
   links:
+    - /docs/env
     - /docs/email-get-started
     - /docs/env-file
     - /docs/php-validator
@@ -33,6 +34,7 @@ Do not assume another framework's mailer abstraction applies directly.
 ## Read this doc when you need
 
 - **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, `sendEmail`, HTML email, text email, `from`, `to`, `cc`, `bcc`, `replyTo`, or attachments** → official `email-get-started`
+- **custom runtime reads of SMTP values, mail feature flags, or `.env` loading boundaries** → `env.md` plus `email.md`
 - **contact forms or page-local email sends via PulsePoint** → `fetching-data.md` plus `email.md`
 - **direct POST handlers or handler-only email routes** → `route-handlers.md` plus `email.md`
 - **validation of recipient, sender, or contact-form input** → `validator.md` plus `email.md`
@@ -44,6 +46,8 @@ The Prisma PHP mailer is a PHPMailer wrapper with a fluent API.
 
 The constructor initializes a `PHPMailer` instance, forces `UTF-8`, configures SMTP transport from `.env`, and applies a default sender when `MAIL_FROM` is present and valid.
 
+When a task goes beyond the built-in mailer workflow and needs direct runtime config access, AI should route that part through `PP\Env` and `env.md` instead of adding ad hoc `getenv()` parsing.
+
 AI should preserve that model instead of replacing it with undocumented helpers or raw `mail()` calls.
 
 ## Exact core file location
@@ -82,6 +86,8 @@ Behavior notes:
 
 AI should update `.env` whenever email support is introduced and should not hardcode SMTP credentials in route files or components.
 
+If application code needs to read related mail settings directly, prefer `PP\Env` typed helpers so defaults and empty-value handling stay consistent with the Prisma PHP env implementation.
+
 ## Public fluent methods AI should know
 
 The current `Mailer` class exposes:

package/dist/docs/env.md

@@ -0,0 +1,224 @@
+---
+title: Env
+description: Learn how Prisma PHP reads environment values with PP\Env so AI agents can use typed env helpers, understand the .env loading boundary, and avoid ad hoc getenv parsing.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP env docs before generating or editing configuration access code.
+  links:
+    - /docs/env
+    - /docs/env-file
+    - /docs/project-structure
+    - /docs/prisma-php-ai-mcp
+    - /docs/websocket-get-started
+---
+
+Prisma PHP environment access should follow the documented `PP\Env` model, not ad hoc parsing copied from Laravel config helpers, Symfony parameter bags, or repeated raw `getenv()` checks scattered across the codebase.
+
+If a task involves `.env`, environment variables, feature flags, host and port values, timezones, API keys, numeric limits, or typed runtime configuration reads, AI agents should read the relevant Prisma PHP env docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the Env docs first
+
+Before generating, editing, or reviewing environment-related code, use this order:
+
+1. Read `./prisma-php.json` when the task is in a generated Prisma PHP app.
+2. Read the installed local docs in `node_modules/prisma-php/dist/docs`.
+3. Read this `env.md` file.
+4. Inspect the current `.env` file or deployment environment when the task depends on real values.
+5. Inspect the bootstrap or server entry file that loads or consumes environment variables.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's env loader or configuration container applies directly.
+
+## Read this doc when you need
+
+- **`.env`, environment variables, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, or `Env::int(...)`** -> official `env`
+- **`.env` file placement, runtime loading, or dotenv bootstrapping** -> official `env-file` plus `env.md`
+- **runtime settings for websocket or MCP servers** -> `websocket.md` or `mcp.md` plus `env.md`
+- **SMTP credentials, sender defaults, or provider secrets** -> `email.md` or `get-started-ia.md` plus `env.md`
+- **database connection strings and Prisma datasource config** -> `prisma-php-orm.md` plus `env.md`
+
+## Core Env model AI should follow
+
+Prisma PHP documents environment access around a lightweight helper class:
+
+- `PP\Env` reads values that already exist in the runtime
+- it provides raw access through `get()`
+- it provides typed helpers through `string()`, `bool()`, and `int()`
+- it centralizes default handling instead of repeating parsing logic in multiple files
+
+AI should preserve that model instead of re-implementing manual conversion everywhere.
+
+## Exact core file location
+
+The Prisma PHP core `Env` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/Env.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer an env task, this is the exact core file to review.
+
+## Resolution order and normalization
+
+The current `Env` implementation resolves values in this order:
+
+1. `getenv()`
+2. `$_ENV`
+3. `$_SERVER`
+
+Normalization behavior:
+
+- booleans become `'true'` or `'false'`
+- scalar values are cast to strings
+- unsupported types such as arrays or objects return `null`
+
+That means `Env` is safe for central configuration reads, but it is not a substitute for validating arbitrary request payloads.
+
+## Public methods AI should know
+
+The current `Env` class exposes:
+
+- `static get(string $key): ?string`
+- `static string(string $key, string $default = ''): string`
+- `static bool(string $key, bool $default = false): bool`
+- `static int(string $key, int $default = 0): int`
+
+Do not invent undocumented helper methods when this public surface already covers the common Prisma PHP configuration workflow.
+
+## Method behavior summary
+
+Use `get()` when you want the raw nullable string value and plan to handle parsing yourself.
+
+Use `string()` for values such as:
+
+- app names
+- timezones
+- URLs
+- API keys
+- driver names
+
+Behavior note:
+
+- `string()` returns the default when the value is missing or when it is an empty string
+
+Use `bool()` for values such as:
+
+- feature flags
+- verbose logging toggles
+- JSON response toggles
+- debug mode switches
+
+Accepted boolean-like values are case-insensitive:
+
+- `true` and `false`
+- `1` and `0`
+- `yes` and `no`
+- `on` and `off`
+
+Behavior note:
+
+- invalid boolean strings fall back to the provided default
+
+Use `int()` for values such as:
+
+- port numbers
+- timeouts
+- retry limits
+- upload limits
+- cache durations
+
+Behavior note:
+
+- `int()` only converts numeric values; otherwise it returns the default
+
+## Important `.env` boundary
+
+`PP\Env` does not parse a `.env` file by itself.
+
+It only reads values that are already present in the PHP runtime. When Prisma PHP needs to load `.env` values from disk first, the bootstrap or server entry typically does that explicitly, for example with `Dotenv::createImmutable(...)->safeLoad()`.
+
+AI should keep that boundary clear:
+
+- use dotenv loading when the runtime has not loaded `.env` yet
+- use `PP\Env` when reading values after the environment is available
+- do not describe `PP\Env` as a standalone dotenv parser
+
+## Recommended example patterns
+
+### Bootstrap runtime settings
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Dotenv\Dotenv;
+use PP\Env;
+
+if (file_exists(DOCUMENT_PATH . '/.env')) {
+    Dotenv::createImmutable(DOCUMENT_PATH)->safeLoad();
+}
+
+date_default_timezone_set(Env::string('APP_TIMEZONE', 'UTC'));
+
+$showErrors = Env::bool('SHOW_ERRORS', false);
+$appName = Env::string('APP_NAME', 'Prisma PHP App');
+$appPort = Env::int('APP_PORT', 3000);
+```
+
+### Fail early for required secrets
+
+```php
+<?php
+
+use PP\Env;
+
+$openAiKey = Env::string('OPENAI_API_KEY', '');
+
+if ($openAiKey === '') {
+    throw new Exception('OPENAI_API_KEY is missing.');
+}
+```
+
+### Inspect a raw value directly
+
+```php
+<?php
+
+use PP\Env;
+
+$driver = Env::get('DB_DRIVER');
+
+if ($driver === null) {
+    $driver = 'mysql';
+}
+```
+
+## Example environment values
+
+```dotenv
+APP_NAME="Prisma PHP"
+APP_TIMEZONE="UTC"
+APP_PORT=3000
+SHOW_ERRORS=true
+OPENAI_API_KEY="sk-..."
+DB_DRIVER="mysql"
+MAX_UPLOAD_MB=20
+```
+
+## Common patterns AI should preserve
+
+- prefer `string()`, `bool()`, and `int()` over repeated manual parsing
+- always provide a sensible default for optional settings
+- validate critical secrets explicitly and fail early when they are missing
+- keep configuration reads near bootstrap or server setup when possible
+- pass resolved configuration into the parts of the system that need it instead of re-reading the same keys everywhere
+
+## AI rules for env tasks
+
+- read `env.md` before generating environment-related Prisma PHP code
+- prefer `PP\Env` over ad hoc `getenv()` parsing when working inside documented Prisma PHP code paths
+- keep secrets and deployment values in `.env` or the runtime environment, not hardcoded in route files or components
+- remember that `PP\Env` reads already-loaded values and does not load `.env` on its own
+- use defaults for optional settings and explicit checks for required secrets
+- inspect `vendor/tsnc/prisma-php/src/Env.php` only when the docs and current app code do not answer the task