README

⚠️ Are You Looking to Create a New Project?

You Probably Want stonescriptphp-server Instead!

This repository contains the core framework library. Most developers should use the application skeleton to get started:

# ✅ RECOMMENDED: Create a new project with the application skeleton
composer create-project progalaxyelabs/stonescriptphp-server my-api
cd my-api
php stone serve

Why use stonescriptphp-server?

• Includes complete project structure
• Pre-configured routes and examples
• stone CLI entry point ready to use
• Environment setup automated
• This framework (stonescriptphp) is automatically installed as a dependency
• CLI tools auto-update with composer update

When to Use This Package Directly

Only install this framework package directly if you're:

• ✅ Contributing to the framework core
• ✅ Building custom framework extensions or plugins
• ✅ Integrating StoneScriptPHP into an existing project
• ✅ Creating your own custom project template

# Direct installation (advanced usage only)
composer require progalaxyelabs/stonescriptphp

StoneScriptPHP Framework

A modern PHP backend framework for building APIs with PostgreSQL, inspired by Angular routing, MCP-style CLI commands, and Laravel's elegance for a streamlined developer experience.

Built for developers who value clean architecture and rapid API development, StoneScriptPHP combines PostgreSQL's power with an intuitive CLI workflow.

📦 Package Ecosystem

Features

Core Framework

• CLI Tools - Code generators in cli/ directory (used via php stone from server package)
• PostgreSQL-first - Built for PostgreSQL with migration system
• Fast Development - Code generators for routes, models, migrations
• Auto-updates - CLI tools update automatically with composer update

Security & Auth

• JWT Authentication - RSA & HMAC support, built-in OAuth (Google)
• RBAC - Role-Based Access Control with permissions
• Security Middleware - CORS, rate limiting, security headers

Performance & Monitoring

• Redis Caching - Optional Redis integration with cache tags, TTL, automatic invalidation
• Production Logging - PSR-3 compatible, console + file output, colorized
• Exception Handling - Global exception handler with structured errors
• Validation Layer - Powerful request validation with 12+ built-in rules

Developer Experience

• Color-Coded Logs - Beautiful ANSI-colored console output
• Comprehensive Docs - 20+ documentation files (600+ pages)
• Testing - PHPUnit test suite included
• VS Code Extension - Snippets and IntelliSense

Quick Start (Using Application Skeleton)

# Create a new project
composer create-project progalaxyelabs/stonescriptphp-server my-api
cd my-api

# Start development server
php stone serve
# Your API is running at http://localhost:9100

👉 View Full Getting Started Guide

Upgrading

Keep Your Project Up-to-Date

Update framework and CLI tools:

# Update framework (vendor packages)
composer update progalaxyelabs/stonescriptphp

# Update CLI tools (project files)
php stone upgrade

Check for updates without installing:

php stone upgrade --check

See docs/UPGRADE.md for version-specific migration guides.

Development Workflow

1. Define Database Schema

Create tables in src/App/Database/postgres/tables/table_name.pssql

2. Create SQL Functions

Create functions in src/App/Database/postgres/functions/function_name.pssql

-- Example: get_users.pssql
CREATE OR REPLACE FUNCTION get_users()
RETURNS TABLE (
    id INTEGER,
    name VARCHAR(100),
    email VARCHAR(255)
) AS $$
BEGIN
    RETURN QUERY
    SELECT u.id, u.name, u.email
    FROM users u
    ORDER BY u.id DESC;
END;
$$ LANGUAGE plpgsql;

3. Generate PHP Model

php stone generate model get_users.pssql

Creates FnGetUsers.php in src/App/Database/Functions/

4. Create Route

php stone generate route get-users

5. Map URL to Route

In src/App/Config/routes.php:

return [
    'GET' => [
        '/api/users' => GetUsersRoute::class,
    ],
];

6. Implement Route Logic

class GetUsersRoute implements IRouteHandler
{
    public function validation_rules(): array
    {
        return []; // No validation needed for GET
    }

    public function process(): ApiResponse
    {
        $users = FnGetUsers::run();
        return res_ok(['users' => $users]);
    }
}

7. Run Migrations

php stone migrate verify

CLI Tools (v2.0.13+)

Location: cli/ directory in this package Usage: Via php stone command from stonescriptphp-server

The framework now bundles all CLI code generators. When you run composer update, the CLI tools automatically update along with the framework.

# Run from stonescriptphp-server project:
php stone generate route <name>         # Generate route handler
php stone generate model <file.pgsql>   # Generate model from SQL function
php stone generate auth:google          # Generate OAuth authentication
php stone migrate verify                # Check database drift

See stonescriptphp-server for complete CLI documentation.

Architecture Philosophy

StoneScriptPHP follows a PostgreSQL-first architecture:

1. Business Logic in Database - SQL functions encapsulate complex queries and business rules
2. Type-Safe PHP Models - Generated classes wrap SQL functions with PHP typing
3. Thin Route Layer - Routes handle HTTP concerns (validation, auth, responses)
4. Clean Separation - Database → Models → Services → Routes → Frontend

This approach:

• Leverages PostgreSQL's procedural capabilities
• Keeps logic close to the data
• Enables database performance optimization
• Facilitates testing and maintenance

Requirements

Required

• PHP >= 8.2
• PostgreSQL >= 13
• Composer
• PHP Extensions: pdo, pdo_pgsql, json, openssl

Optional

• Redis server (for caching support)
• PHP Extension: redis (for Redis caching)

Documentation

📖 Main Documentation

• 📑 Documentation Index - Complete documentation with navigation
• 🏗️ High Level Design (HLD) - System architecture and company work-management
• 📋 Release Notes - Version history

🚀 Getting Started

• Getting Started Guide
• CLI Usage Guide
• Environment Configuration
• Setup Quiet Mode - CI/CD and Docker automation

🔧 Core Features

• API Reference
• Logging & Exceptions
• Request Validation
• Middleware Guide
• Caching System

🔐 Security

• Authentication
• JWT Configuration
• RBAC (Access Control)
• RBAC Quickstart
• Security Best Practices
• CSRF Protection
• Bot Protection

⚡ Performance

• Redis Caching Guide
• Performance Guidelines

Contributing to the Framework

We welcome contributions! This repository is for framework core development.

Development Setup

# Clone the framework repository
git clone https://github.com/progalaxyelabs/StoneScriptPHP.git
cd StoneScriptPHP

# Install dependencies
composer install

# Run tests
composer test

Testing Local Changes

To test framework changes in a project without publishing:

// In your test project's composer.json
{
    "repositories": [
        {
            "type": "path",
            "url": "../StoneScriptPHP",
            "options": {"symlink": false}
        }
    ],
    "require": {
        "progalaxyelabs/stonescriptphp": "@dev"
    }
}

Then run composer update progalaxyelabs/stonescriptphp

Versioning Strategy

StoneScriptPHP follows Semantic Versioning:

• Patch versions (2.0.x): Bug fixes, security patches. Safe to update anytime.
• Minor versions (2.x.0): New features, backward-compatible. Update when needed.
• Major versions (x.0.0): Breaking changes. Review migration guide first.

Current stable: v2.0.x - Production-ready with ongoing bug fixes

Related Packages

• stonescriptphp-server - Application skeleton (recommended for new projects)

Support & Community

• Website: stonescriptphp.org
• Documentation: stonescriptphp.org/docs
• Framework Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE file for details

Remember: For New Projects

Most developers should start with the application skeleton:

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

This framework package is automatically included as a dependency. Visit stonescriptphp-server to get started!