create-prisma-php-app 5.0.0-alpha.17 → 5.0.0-alpha.18

package/dist/AGENTS.md

@@ -32,6 +32,7 @@ Important repo-mode rules:
 - do not assume `node_modules/prisma-php/dist/docs` is the active docs location for this workspace
 - do not assume `vendor/tsnc/prisma-php/src` exists locally in this workspace unless the task explicitly provides or references it
 - when editing or improving Prisma PHP guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned with each other
+- keep each `dist/docs/*.md` page AI-discoverable on its own by making the frontmatter description and opening guidance explicit about when agents should read that file and which nearby docs to consult next
 
 ### 2. Consumer app mode
 
@@ -74,6 +75,12 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **Project setup, folder placement, route file choice, feature placement, or overall file conventions**  
   Read `project-structure.md`
 
+- **CLI project creation, starter kits, feature flags, or `npx pp update project` usage**  
+  Read `commands.md`
+
+- **Backend-only Prisma PHP usage, API-first projects, `backendOnly`, separate frontend consumers, or CORS setup for API routes**  
+  Read `backend-only.md`
+
 - **Creating a page, layout, nested route, dynamic route, or normal UI route**  
   Read `layouts-and-pages.md`
 
@@ -83,12 +90,18 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **Loading data, calling backend logic from the frontend, `pp.fetchFunction(...)`, `#[Exposed]`, route-local mutations, streaming responses, or interactive backend validation**  
   Read `fetching-data.md`
 
+- **AI integration, provider SDKs, chat UIs, streamed assistant output, or deciding between page-local assistant UI, websocket, and MCP tools**  
+  Read `get-started-ia.md`, then use `fetching-data.md`, `validator.md`, `websocket.md`, or `mcp.md` as needed
+
 - **PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp-for`, `pp-spread`, or `pp-ref`**  
   Read `pulsepoint.md`
 
 - **Validation, sanitization, `PP\Validator`, `PP\Rule`, field validation, form validation, live validation, or request validation rules**  
   Read `validator.md`, then apply the relevant local guidance from `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
 
+- **Environment variables, `.env`, `PP\Env`, `Env::get`, `Env::string`, `Env::bool`, `Env::int`, feature flags, host and port config, or runtime bootstrap settings**  
+  Read `env.md`, then verify the official env docs at `env` and `env-file`
+
 - **File uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename flows, replace flows, delete flows, allowed file types, upload size rules, or file manager UI behavior**  
   Read `file-manager.md`, then verify the official File Manager docs and, when internals matter, the core upload file at `vendor/tsnc/prisma-php/src/FileManager/UploadFile.php`
 
@@ -119,6 +132,9 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **API-style routes, JSON responses, handlers, webhooks, form-processing endpoints, `route.php`, or request validation in handlers**  
   Read `route-handlers.md`
 
+- **Swagger or OpenAPI generation, `swaggerDocs`, `pphp-swagger.json`, `create-swagger-docs`, or `settings/prisma-schema-config.json`**  
+  Read `swagger-docs.md`
+
 - **Upgrading Prisma PHP, enabling features, syncing framework-managed project files, or running project updates**  
   Read `upgrading.md`
 
@@ -130,12 +146,16 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 The current Prisma PHP docs shipped here include:
 
 - `authentication.md`
+- `backend-only.md`
 - `caching.md`
+- `commands.md`
 - `components.md`
 - `email.md`
+- `env.md`
 - `error-handling.md`
 - `fetching-data.md`
 - `file-manager.md`
+- `get-started-ia.md`
 - `index.md`
 - `installation.md`
 - `layouts-and-pages.md`
@@ -145,11 +165,12 @@ The current Prisma PHP docs shipped here include:
 - `project-structure.md`
 - `pulsepoint.md`
 - `route-handlers.md`
+- `swagger-docs.md`
 - `upgrading.md`
 - `validator.md`
 - `websocket.md`
 
-When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `email.md`, `mcp.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
+When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
 
 ## Framework-generated files
 
@@ -432,6 +453,26 @@ Important email rules:
 - prefer the documented fluent API such as `to(...)`, `subject(...)`, `html(...)`, `text(...)`, `attach(...)`, and `send()`
 - use `raw()` only when low-level PHPMailer access is genuinely needed
 
+## Env rules
+
+When the task involves `.env`, `PP\Env`, feature flags, ports, host names, timezones, API keys, numeric limits, or other runtime configuration values, read `env.md` first.
+
+Use this env workflow:
+
+1. read `env.md`
+2. inspect `.env` or the deployment environment when the task depends on actual values
+3. inspect the bootstrap or server entry file that loads or consumes the environment
+4. inspect the feature-specific doc such as `email.md`, `mcp.md`, `websocket.md`, `get-started-ia.md`, or `prisma-php-orm.md` when the env values belong to that feature
+5. inspect `vendor/tsnc/prisma-php/src/Env.php` only if the docs do not answer the task
+
+Important env rules:
+
+- prefer `PP\Env` over repeated ad hoc `getenv()` parsing in documented Prisma PHP code paths
+- use `Env::string(...)`, `Env::bool(...)`, and `Env::int(...)` for typed access with defaults
+- use `Env::get(...)` when raw nullable string access is actually needed
+- remember that `PP\Env` reads values from `getenv()`, `$_ENV`, and `$_SERVER`; it does not parse `.env` by itself
+- keep secrets and deployment-specific settings in `.env` or the real runtime environment, not hardcoded in route files or components
+
 ## WebSocket rules
 
 When the task involves realtime messaging, presence, live dashboards, `Ratchet`, or browser `WebSocket`, read `websocket.md` first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-prisma-php-app",
-  "version": "5.0.0-alpha.17",
+  "version": "5.0.0-alpha.18",
   "description": "Prisma-PHP: A Revolutionary Library Bridging PHP with Prisma ORM",
   "main": "dist/index.js",
   "type": "module",

package/dist/README.md

@@ -1,213 +0,0 @@
-# Prisma PHP
-
-Prisma PHP is a modern full-stack PHP framework that combines native PHP, PulsePoint reactivity, PHPX components, and a Prisma-inspired ORM into one cohesive developer experience.
-
-Build reactive interfaces with a server-first mental model, structured routing, type-safe data access, and a project layout designed for real applications.
-
-## Getting Started
-
-Create a new Prisma PHP project:
-
-```bash
-npx create-prisma-php-app@latest my-app
-```
-
-Start the development server:
-
-```bash
-npm run dev
-```
-
-Open the local app in your browser after the dev server starts.
-
-## Prerequisites
-
-Before creating a Prisma PHP project, make sure you have:
-
-- Node.js 22.x or higher
-- PHP 8.2 or higher
-- Composer 2.x or higher
-- XAMPP or another local PHP environment
-
-If you are using XAMPP on Windows, enabling `extension=zip` in `php.ini` is recommended so Composer dependencies install correctly.
-
-## What Prisma PHP Includes
-
-Prisma PHP brings together the core pieces needed to build full-stack PHP apps:
-
-- **Native PHP + modern reactivity** with PulsePoint
-- **PHPX component system** for reusable UI composition
-- **Prisma PHP ORM** for schema-first, type-safe database access
-- **Built-in authentication patterns** for sessions, route protection, RBAC, credentials auth, and provider login
-- **File-based routing** with clear route file conventions
-- **CLI scaffolding** for new apps, starter kits, and optional features
-- **Flexible deployment options** for local development and production workflows
-
-## Common Create Commands
-
-Create a default full-stack app:
-
-```bash
-npx create-prisma-php-app@latest my-app
-```
-
-Create a project with common options:
-
-```bash
-npx create-prisma-php-app@latest my-app --tailwindcss --typescript
-```
-
-Use a starter kit:
-
-```bash
-npx create-prisma-php-app my-app --starter-kit=fullstack
-```
-
-Other documented flags may include capabilities such as WebSocket support, MCP support, backend-only mode, Swagger docs, and Prisma integration depending on the installed version.
-
-## Documentation
-
-Prisma PHP ships with local documentation for the installed project version.
-
-The installed docs live here:
-
-```txt
-node_modules/prisma-php/dist/docs
-```
-
-Treat these installed docs as the primary documentation source for the current project version.
-
-You can also explore the public docs site:
-
-```txt
-https://prismaphp.tsnc.tech/
-```
-
-## AI Quick Start
-
-If you are using AI-assisted development in a Prisma PHP project:
-
-1. Read `./prisma-php.json` first.
-2. Read the installed docs in `node_modules/prisma-php/dist/docs`.
-3. Read `AGENTS.md` for task-routing rules, framework constraints, and code-generation guidance.
-4. Inspect `vendor/tsnc/prisma-php/src` only when the docs do not answer the task.
-
-### Default interactive UI rule
-
-In Prisma PHP, AI should treat **PulsePoint as the default frontend interactivity model**.
-
-For normal full-stack page work:
-
-- render the page with `index.php`
-- manage browser-side state and UI behavior with **PulsePoint**
-- call PHP from the frontend with **`pp.fetchFunction(...)`**
-- expose callable PHP functions with **`#[Exposed]`**
-- validate incoming data on the PHP side with **`PP\Validator`**
-
-Do **not** default to PHP-only refresh cycles, handcrafted `fetch('/api/...')` patterns, or extra `route.php` handlers for normal interactive page behavior when PulsePoint plus `pp.fetchFunction(...)` already fits the task.
-
-Only prefer a more PHP-only interaction style when the **user explicitly asks for PHP-only behavior**, or when the task is clearly non-reactive.
-
-## Project Capability Manifest
-
-Prisma PHP uses `prisma-php.json` at the repository root as the source of truth for enabled framework features and local environment configuration.
-
-Use it to verify capabilities such as:
-
-- Tailwind CSS support
-- backend-only mode
-- Prisma ORM support
-- Swagger docs
-- WebSocket support
-- MCP support
-- TypeScript support
-- local development paths and BrowserSync settings
-
-Do not assume a feature is enabled unless `prisma-php.json` confirms it.
-
-## Documentation Map
-
-Use these docs as the main entry points for common work:
-
-- `index.md` for the general documentation entry point
-- `project-structure.md` for project structure, route placement, and file conventions
-- `layouts-and-pages.md` for pages, layouts, nested routes, and dynamic routes
-- `components.md` for PHPX components, props, children, fragments, icons, buttons, and composition
-- `fetching-data.md` for `pp.fetchFunction(...)`, `#[Exposed]`, and interactive backend flows
-- `prisma-php-orm.md` for Prisma ORM, `schema.prisma`, migrations, and generated PHP classes
-- `authentication.md` for auth strategy, sessions, RBAC, credentials auth, and provider flows
-- `file-manager.md` for uploads, `multipart/form-data`, `$_FILES`, and `PP\FileManager\UploadFile`
-- `route-handlers.md` for `route.php`, JSON responses, and direct server handlers
-- `error-handling.md` for expected errors, `error.php`, `not-found.php`, and validation failures
-- `caching.md` for cache behavior and `CacheHandler`
-- `metadata-and-og-images.md` for metadata, title, description, icons, and head behavior
-- `pulsepoint.md` for PulsePoint runtime usage and reactivity patterns
-- `upgrading.md` for feature enablement and project update workflows
-
-## Recommended Development Approach
-
-When working in Prisma PHP:
-
-- prefer the installed Prisma PHP docs over assumptions from other frameworks
-- use `AGENTS.md` as the strict AI operating guide
-- inspect nearby project files before generating new framework-specific code
-- inspect framework internals only when the installed docs are not enough
-
-## Route and File Conventions
-
-Prisma PHP uses file-based routing with special route files such as:
-
-- `index.php` for rendered UI routes
-- `layout.php` for shared UI wrappers
-- `route.php` for direct handlers such as JSON or API-style endpoints
-- `loading.php` for loading UI
-- `not-found.php` for route-level not-found UI
-- `error.php` for route-level or app-level error UI
-
-For task-specific route decision rules and framework generation rules, read `AGENTS.md`.
-
-## PulsePoint and Frontend Reactivity
-
-Prisma PHP uses PulsePoint for browser-side reactivity, and AI should assume this is the **default choice** for interactive UI behavior in full-stack routes.
-
-When working with runtime features such as:
-
-- `pp.state`
-- `pp.effect`
-- `pp.ref`
-- `pp-for`
-- `pp-spread`
-- `pp-ref`
-
-read the installed Prisma PHP docs for the current version first, then consult:
-
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-
-## Project Structure
-
-A generated Prisma PHP project typically includes folders like these:
-
-```text
-prisma-php-project/
-├── prisma/            # schema, migrations, seed files
-├── public/            # public entry point and assets
-├── settings/          # project configuration
-├── src/               # application source code
-├── package.json       # frontend/dev scripts
-├── composer.json      # PHP dependencies
-└── prisma-php.json    # Prisma PHP project capability manifest
-```
-
-## Updating Existing Projects
-
-When enabling features or syncing framework-managed project files:
-
-1. Update `prisma-php.json` first.
-2. Read `upgrading.md` in the installed docs.
-3. Run the documented project update workflow for the current version.
-
-## Learn More
-
-Start with the installed docs for the current project version, use the topic-specific markdown guides for focused work, and rely on `AGENTS.md` when strict AI generation rules are needed.