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

Package	Purpose	When to Use
stonescriptphp-server	Application skeleton	✅ Start here - Creating new projects
stonescriptphp	Core framework	Advanced - Framework development, custom integrations

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:

Business Logic in Database - SQL functions encapsulate complex queries and business rules
Type-Safe PHP Models - Generated classes wrap SQL functions with PHP typing
Thin Route Layer - Routes handle HTTP concerns (validation, auth, responses)
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

🔐 Security

⚡ Performance

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!

progalaxyelabs / stone-script-php

Maintainers

Details