create-prisma-php-app — React Admin dashboard Template

SHA-256: f8e03830c16a8e9e1a202e225db2d2ce66d799a73f5c30186d5299e888c65fa0

2026-10-13T22:37:04.384Z

# 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.