jonytonet/ptah

What is Ptah?

Ptah is a Laravel package that combines SOLID scaffolding, ready-made visual components and a dynamic CRUD system in a single installation. With one command you generate the entire structure of an entity — model, migration, DTO, repository, service, controller, requests, resource, Livewire view and routes — ready to use from the very first php artisan serve.

In a hurry? Follow the Quick Start → — one entity, SQLite, working CRUD in 5 minutes.

⚡ The full structure in minutes — far fewer tokens with AI

What Ptah generates in minutes: the complete, layered structure of every entity (model, migration, DTO, repository, service, controller, requests, resource, Livewire screen and routes), plus auth, RBAC and a dynamic menu. What stays with you: the specific business logic and a short post-scaffold review (see Known Limitations).

Why this saves tokens: with ptah + AI (GitHub Copilot, Claude, Cursor) the agent doesn't waste tokens generating dozens of boilerplate files and re-deciding the architecture on every entity — that's already delivered, consistently. The agent spends its budget only on your differentiator. Fewer tokens, fewer files to review, and an architecture that doesn't drift between entities.

Example: IT Helpdesk — full CRUD structure in ~3 minutes

Step 0 — Check system requirements

Before you start, confirm your environment meets the minimum versions:

php -v        # Required: PHP 8.2+
composer -V   # Required: Composer 2+
node -v       # Required: Node.js 18+
npm -v        # Required: npm 9+

Expected output (example):

PHP 8.2.x ...
Composer version 2.x.x ...
v20.x.x
10.x.x

If any version is below the minimum, update it before proceeding. See the full requirements → for database and extension requirements.

Step 1 — Create the Laravel project

composer create-project laravel/laravel ptah-app
cd ptah-app

Step 2 — Install Ptah

Choose one of the two options below:

Option A — From Packagist (stable — recommended):

composer require jonytonet/ptah

Option B — From GitHub (latest dev version):

Add the VCS repository to your composer.json before requiring the package:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/jonytonet/ptah"
        }
    ],
    "minimum-stability": "dev",
    "prefer-stable": true
}

Then run:

composer require jonytonet/ptah:dev-main

Both options — finish the installation:

php artisan ptah:install

Step 3 — Configure your database

Edit .env to point to your database of choice before running migrations.

SQLite (quick start):

DB_CONNECTION=sqlite

touch database/database.sqlite

MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ptah_app
DB_USERNAME=root
DB_PASSWORD=your_password

PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=ptah_app
DB_USERNAME=postgres
DB_PASSWORD=your_password

See the full database guide → for more options.

Step 4 — Enable the required modules

php artisan ptah:module auth
php artisan ptah:module permissions
php artisan ptah:module menu

Step 5 — Generate the 3 system entities

Category:

php artisan ptah:forge Category --fields="name:string,color:string:nullable,description:text:nullable"

Agent:

php artisan ptah:forge Agent --fields="name:string,email:string,department_id:unsignedBigInteger:nullable"

Ticket:

php artisan ptah:forge Ticket --fields="title:string,description:text,status:string,priority:string,category_id:unsignedBigInteger,agent_id:unsignedBigInteger:nullable,resolved_at:datetime:nullable"

Step 6 — Run migrations, sync menu and serve

php artisan migrate
php artisan ptah:menu-sync --fresh
php artisan serve

What you get at the end (the structure):

• ✅ Login with session protection and 2FA
• ✅ Full CRUD for Categories, Agents and Tickets — table, filters, modal, soft delete, export
• ✅ Role-based access control (MASTER + custom roles)
• ✅ Dynamic sidebar menu
• ✅ SOLID architecture: Controller → Service → Repository → DTO
• ✅ Generated validations, Resources and RESTful routes
• ✅ 14 artefacts created per entity, zero manual boilerplate

What's still yours to do (the actual application): wire up relationships left as TODOs, review the generated validation rules, and add the business logic — ticket escalation, priority notifications, integrations. Then the usual road to production: tests, security review and deploy. See the post-scaffold checklist.

Why AI loves this: instead of generating hundreds of files — thousands of tokens, with architectural drift between entities — the agent runs the commands above and spends its token budget only on your differentiator. Ptah handles the structure; AI handles the business logic.

🚀 Installation

From Packagist (stable — recommended)

# 1. Install the package
composer require jonytonet/ptah

# 2. Run the installer
php artisan ptah:install

# 3. (Optional) Install Laravel Boost for AI agent integration
php artisan ptah:install --boost

From GitHub (latest dev version)

Add to your composer.json before requiring:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/jonytonet/ptah"
        }
    ],
    "minimum-stability": "dev",
    "prefer-stable": true
}

Then:

composer require jonytonet/ptah:dev-main
php artisan ptah:install

See the full installation guide → for database setup, optional modules and troubleshooting.

🧩 Optional modules

Enable only what you need. Each module updates .env and runs its own migrations.

# Check current state of all modules
php artisan ptah:module --list

🤖 Ptah + AI

Ptah is designed to work with AI agents. When installed with --boost, the package automatically registers its guidelines in the configured agents (GitHub Copilot, Claude, Cursor, Gemini, etc.), giving the agent deep knowledge of Ptah conventions, commands and architecture.

Why this matters:

• Without Ptah: AI needs to generate model + migration + repository + service + controller + requests + resource + view + routes for each entity — dozens of files, thousands of tokens, high risk of inconsistency
• With Ptah: AI runs ptah:forge MyEntity --fields="...", the structure is ready, and it spends its tokens only on the business logic — fewer tokens, architecture guaranteed by the package

For prompts, templates and AI workflow, see the AI Guide →. Agents reading this repo (or vendor/jonytonet/ptah) should start at AGENTS.md — a one-page router that says which document answers which question, and the two rules that prevent the most wasted work: configure before you code and every color through a token.

📟 Commands

Full reference for every command and every flag: Commands.md. Swagger/OpenAPI docs are generated via ptah:forge --api (or ptah:module api) followed by php artisan l5-swagger:generate — there is no standalone ptah:docs command.

🎨 Theming & customizing views

Brand colors — set once, everything follows. Define your palette in config/ptah.php (or via .env) and the whole UI — BaseCrud, Forge components, modules — picks it up. No view publishing, survives composer update:

// config/ptah.php
'theme' => [
    'colors' => [
        'primary' => env('PTAH_COLOR_PRIMARY', '#5b21b6'),
        'success' => env('PTAH_COLOR_SUCCESS', '#10b981'),
        'danger'  => env('PTAH_COLOR_DANGER',  '#ef4444'),
        'warn'    => env('PTAH_COLOR_WARN',     '#f59e0b'),
        'dark'    => env('PTAH_COLOR_DARK',     '#1e293b'),
    ],
],

# .env — rebrand without touching code
PTAH_COLOR_PRIMARY=#0d9488

Ptah injects these as CSS variables (--color-primary, --ptah-primary, …) in the layout <head>; every tint, focus ring and hover is derived from them via color-mix(). Accepts any CSS color (hex, rgb, hsl, oklch).

Per-user Appearance. Every authenticated user can also pick their own combination of 6 independent axes — light tone, dark tone, accent color, font color, density and font size — from a 6th tab at /profile, persisted server-side and applied on <html> with no flash. See Configuration.md — Per-user Appearance.

Building your own screens on the theme. Anything you build yourself follows all 6 axes automatically if every color resolves through a token — <x-forge-*> props, bg-primary-style semantic classes, or var(--ptah-*). Fixed-palette classes (bg-white, bg-slate-*, dark: variants) produce elements that stay white when a user switches the light tone to papel. The full token contract, the conversion table for existing screens, and a troubleshooting recipe live in CustomScreens.md.

Customizing views — publish only what you edit. Most customization is done through the CrudConfig modal (database-driven), so you rarely need to touch a Blade file. If you do, ⚠️ publishing a view means you own it — Laravel will prefer your copy and composer update will never refresh it again. Publish the smallest slice:

php artisan vendor:publish --tag=ptah-views-components   # just the <x-forge-*>
php artisan vendor:publish --tag=ptah-views-base-crud    # just the BaseCrud screen
php artisan vendor:publish --tag=ptah-views-auth         # just the auth pages
php artisan vendor:publish --tag=ptah-views-ai           # just the AI widget
# (ptah-views still publishes ALL 60+ views — avoid it unless you really mean to)

To keep the UI always up to date, keep resources/views/vendor/ptah/ empty.

📚 Documentation

📋 Requirements

📄 License

Open source under the MIT License.