# 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 - **Direct RPC from the frontend** with `pp.rpc(...)` calling `#[Exposed]` PHP functions — JSON in, JSON out, SSE streaming when the function yields, and framework failures reported as real HTTP statuses - **Named sockets for realtime** with `pp.socket(...)` — long-lived bidirectional messaging (chat, presence, live feeds) served by a Ratchet-based socket server with per-socket auth, origin checks, and rate limits - **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 - **Hardened request pipeline** with double-submit CSRF (`pp_csrf` cookie family), origin validation, content-type checks, and per-function rate limiting - **File-based routing** with clear route file conventions - **App-level test suite** with PHPUnit in a root `tests/` directory, run with `npm run test`, feature-aware via `prisma-php.json` - **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. ## 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.rpc(...)`, `#[Exposed]`, streaming, and the RPC error contract - `websocket.md` for named sockets, `pp.socket(...)`, `SocketRegistry`, and the realtime wire contract - `bootstrap-runtime.md` for the runtime init order, PulsePoint wire headers, and the `pp_csrf` CSRF contract - `testing.md` for the root `tests/` directory, `npm run test`, and feature-gated tests - `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 as the wire between the page and PHP. When working with runtime features such as: - `pp.state` - `pp.effect` - `pp.ref` - `pp.rpc` for frontend-to-PHP calls (with streaming, uploads, and redirects) - `pp.socket` for named-socket realtime messaging - `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 ├── tests/ # app-level PHPUnit tests (npm run test) ├── package.json # frontend/dev scripts ├── composer.json # PHP dependencies ├── phpunit.xml # test suite configuration └── prisma-php.json # Prisma PHP project capability manifest ``` ## Testing App tests live in the root `tests/` directory and run with: ```bash npm run test ``` The suite runs PHPUnit on the PHP binary configured in `prisma-php.json`, uses a deterministic test environment (the real `.env` is never loaded), and is feature-aware: tests for optional features such as WebSocket skip cleanly when the feature is disabled in `prisma-php.json`. Read `testing.md` in the installed docs and the project's `tests/README.md` for the full contract. ## 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.