progalaxyelabs/stonescriptphp-server

Application skeleton for StoneScriptPHP. Ready-to-use project template with CLI tools, folder structure, and examples. Includes the stonescriptphp framework as a dependency.

Maintainers

Details

github.com/progalaxyelabs/StoneScriptPHP-Server

Homepage

Source

Issues

Documentation

Installs: 28

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:project

pkg:composer/progalaxyelabs/stonescriptphp-server

v2.3.0 2026-01-16 15:33 UTC

Requires

Requires (Dev)

MIT 13d79a3f1e95d1986d3a8b211bf15b039a4da4b5

phprestapiboilerplatepostgresqlSkeletonstonescriptphp

This package is auto-updated.

Last update: 2026-01-22 15:59:31 UTC

README

A minimal, composable API server skeleton for building PostgreSQL-backed REST APIs.

Clean starting point with zero bloat - add only what you need through CLI commands.

Features

  • 🎯 Minimal by default - Only database connection, no pre-configured auth or models
  • 🔧 Composable authentication - Choose email/password, OAuth, API keys, or combine them
  • 📦 Migration-based - Version-controlled database schema
  • 🚀 Production-ready - Docker support, RBAC, JWT, rate limiting
  • ⚡ Developer-friendly - CLI code generation, hot reload

Quick Start

1. Create Project

composer create-project progalaxyelabs/stonescriptphp-server my-api
cd my-api

2. Setup Environment

# Interactive setup wizard (recommended)
php stone setup

# Or manually create .env with database credentials
cp .env.example .env

3. Choose Your Authentication

Email/Password Authentication:

php stone generate auth:email-password
php stone migrate up
php stone seed rbac
php stone create:admin

Google OAuth:

php stone generate auth:google
php stone migrate up

API Keys:

php stone generate auth:api-key
php stone migrate up

Or combine multiple methods!

4. Start Development

# Start Docker-based development server (recommended)
composer dev
# API running at http://localhost:8000

# Or use framework's built-in server
php stone serve
# API running at http://localhost:9100

Architecture

What's included by default:

  • Database connection setup
  • Routing infrastructure
  • Environment configuration
  • Docker setup
  • CLI tools

What's NOT included (generate as needed):

  • ❌ No authentication routes
  • ❌ No user models or tables
  • ❌ No default roles or permissions
  • ❌ No seeders

Philosophy: Start minimal, add incrementally via CLI commands.

Docker Development

StoneScriptPHP-Server provides a Docker-first development experience with Nginx + PHP-FPM.

Development Commands

# Start development server (builds image if needed, runs detached)
composer dev
# or
composer serve

# Stop development server
composer stop

# Restart server
composer restart

# View application logs (follow mode)
composer logs

# Access container shell
composer shell

# Rebuild image (after Dockerfile changes)
composer build

# Clean up (removes container and image)
composer clean

What's Included

  • Nginx - Production-grade web server with proper URL rewriting
  • PHP-FPM - High-performance PHP processor
  • Supervisor - Process manager for Nginx + PHP-FPM
  • Development tools - git, vim, curl, postgres client, etc.

Live Reload

Your code is mounted as a volume - changes are reflected immediately without rebuilding.

Database Connection

Connect to your external PostgreSQL instance via .env:

DB_HOST=localhost      # or your database host
DB_PORT=5432
DB_NAME=stonescriptphp
DB_USER=postgres
DB_PASSWORD=postgres

CLI Commands

Authentication

# Generate authentication methods (composable)
php stone generate auth:email-password    # Traditional auth
php stone generate auth:google            # Google OAuth
php stone generate auth:linkedin          # LinkedIn OAuth
php stone generate auth:apple             # Apple OAuth
php stone generate auth:api-key           # API key auth

Database

php stone migrate status    # Check migration status
php stone migrate up        # Run pending migrations
php stone migrate down      # Rollback last batch
php stone migrate verify    # Check for schema drift

Seeding

php stone seed rbac         # Seed roles & permissions

User Management

php stone create:admin      # Create system admin (interactive)

Code Generation

php stone generate route POST /auth/login       # Generate route handler
php stone generate model get_user.pgsql         # Generate model from SQL function
php stone generate client                       # Generate TypeScript client
php stone generate jwt                          # Generate JWT keypair

Development

php stone serve             # Start dev server
php stone stop              # Stop dev server
php stone test              # Run tests

Example Workflow

Building an API with email/password auth:

# 1. Create project
composer create-project progalaxyelabs/stonescriptphp-server my-api
cd my-api

# 2. Setup database
php stone setup

# 3. Add email/password authentication
php stone generate auth:email-password

# 4. Run migrations
php stone migrate up

# 5. Seed RBAC (roles & permissions)
php stone seed rbac

# 6. Create admin user
php stone create:admin
# Enter: admin@example.com, password, Admin User

# 7. Start server
php stone serve

# 8. Test login
curl -X POST http://localhost:9100/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"your-password"}'

Migrations

Migrations are stored in migrations/ and run in order:

migrations/
├── 001_create_users_table.sql           # Base users table
├── 002_add_email_password_auth.sql      # Email/password columns
├── 003_add_oauth_providers.sql          # OAuth providers table
├── 004_create_api_keys_table.sql        # API keys table
└── 005_create_rbac_tables.sql           # RBAC tables

Each generate auth:* command adds the necessary migrations. They're composable - run in any order!

Docker Deployment

# Start with docker-compose
docker compose up -d

# Run migrations inside container
docker exec -it stonescriptphp-app php stone migrate up

# Create admin user
docker exec -it stonescriptphp-app php stone create:admin

See docker-compose.yaml for configuration.

Default Roles (after php stone seed rbac)

Role Permissions
super_admin All permissions
admin Most permissions except critical ones
moderator Content management + user viewing
user Basic content permissions
guest Read-only access

Customize by editing the seeder or creating your own roles.

Environment Variables

Required variables (created by php stone setup):

# App
APP_NAME=StoneScriptPHP
APP_ENV=development
APP_PORT=9100

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=your-password
DATABASE_DBNAME=your-database

# JWT (auto-generated)
JWT_PRIVATE_KEY_PATH=./keys/jwt-private.pem
JWT_PUBLIC_KEY_PATH=./keys/jwt-public.pem
JWT_EXPIRY=3600

# Optional: OAuth
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Project Structure

my-api/
├── migrations/              # Database migrations (generated)
├── public/
│   └── index.php           # Entry point
├── src/
│   ├── App/
│   │   ├── Routes/         # Route handlers
│   │   ├── DTO/            # Data Transfer Objects
│   │   ├── Lib/            # Custom libraries
│   │   └── AppEnv.php      # Application environment config
│   ├── config/
│   │   ├── routes.php      # Route definitions
│   │   └── allowed-origins.php  # CORS config
│   └── postgresql/
│       ├── tables/         # Table schemas
│       └── functions/      # SQL functions
├── composer.json
├── docker-compose.yaml
└── .env

Contributing

This is the application skeleton. For framework contributions, see StoneScriptPHP.

License

MIT License - see LICENSE file for details.

Next Steps