PHPackages                             progalaxyelabs/stonescriptphp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. progalaxyelabs/stonescriptphp

ActiveLibrary[Framework](/categories/framework)

progalaxyelabs/stonescriptphp
=============================

Core Framework Library - Use progalaxyelabs/stonescriptphp-server to create new projects. Modern PHP backend framework for building APIs with PostgreSQL. Installed automatically as a dependency when you create projects with stonescriptphp-server.

5.7.1(today)01.1k↑200%1[1 issues](https://github.com/progalaxyelabs/StoneScriptPHP/issues)1MITPHPPHP ^8.2CI failing

Since May 1Pushed 1w ago1 watchersCompare

[ Source](https://github.com/progalaxyelabs/StoneScriptPHP)[ Packagist](https://packagist.org/packages/progalaxyelabs/stonescriptphp)[ Docs](https://stonescriptphp.org)[ RSS](/packages/progalaxyelabs-stonescriptphp/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (30)Versions (148)Used By (1)

 [![StoneScriptPHP Logo](images/logo.svg)](images/logo.svg)

⚠️ Are You Looking to Create a New Project?
===========================================

[](#️-are-you-looking-to-create-a-new-project)

You Probably Want [stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server) Instead!
-----------------------------------------------------------------------------------------------------------

[](#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
composer 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
---------------------------------

[](#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
========================

[](#stonescriptphp-framework)

[![PHP Tests](https://github.com/progalaxyelabs/StoneScriptPHP/actions/workflows/php-test.yml/badge.svg)](https://github.com/progalaxyelabs/StoneScriptPHP/actions/workflows/php-test.yml)[![Packagist Version](https://camo.githubusercontent.com/c3aa467f0614f7e383a2d99c82ed9118f0f6fc2a42d2d77a4b5eeb313453f104/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70726f67616c617879656c6162732f73746f6e65736372697074706870)](https://packagist.org/packages/progalaxyelabs/stonescriptphp)[![License](https://camo.githubusercontent.com/7e34bdc018f3ef53031052907b081eb92db5d5682b57dca80a9634f60c9a6b63/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f70726f67616c617879656c6162732f53746f6e65536372697074504850)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/d5b967861df4fa3553078e3840218b23dc37ed58b4cef87b72eecd8fe0dbbfd4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f70726f67616c617879656c6162732f73746f6e65736372697074706870)](composer.json)[![VS Code Extension](https://camo.githubusercontent.com/2fe2dc85db6c78af00238f840a868a8a61f8e01160770f3c50d66daab961f94a/68747470733a2f2f696d672e736869656c64732e696f2f76697375616c2d73747564696f2d6d61726b6574706c6163652f762f70726f67616c617879656c6162732e73746f6e657363726970747068702d736e6970706574733f6c6162656c3d5653253230436f6465253230536e697070657473)](https://marketplace.visualstudio.com/items?itemName=progalaxyelabs.stonescriptphp-snippets)[![Extension Installs](https://camo.githubusercontent.com/d9a855d701f6ec72464349b9d1f88180a989283e5c2751bbac2a350830410933/68747470733a2f2f696d672e736869656c64732e696f2f76697375616c2d73747564696f2d6d61726b6574706c6163652f692f70726f67616c617879656c6162732e73746f6e657363726970747068702d736e697070657473)](https://marketplace.visualstudio.com/items?itemName=progalaxyelabs.stonescriptphp-snippets)

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-ecosystem)

PackagePurposeWhen to Use**[stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server)**Application skeleton✅ **Start here** - Creating new projects**[stonescriptphp](https://github.com/progalaxyelabs/StoneScriptPHP)**Core frameworkAdvanced - Framework development, custom integrationsFeatures
--------

[](#features)

### Core Framework

[](#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

[](#security--auth)

- **JWT Authentication** - RSA & HMAC support, built-in OAuth (Google)
- **Auth Service Integration** - HTTP clients for the Auth Service (memberships, invitations)
- **Token Validation** - Middleware for validating JWT tokens
- **RBAC** - Role-Based Access Control with permissions
- **Security Middleware** - CORS, rate limiting, security headers

### Performance & Monitoring

[](#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

[](#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)
----------------------------------------

[](#quick-start-using-application-skeleton)

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

# Start development server (via composer script)
composer serve
# Your API is running at http://localhost:9100
```

**👉 [View Full Documentation](https://stonescriptphp.org/docs)**

Upgrading
---------

[](#upgrading)

### Keep Your Project Up-to-Date

[](#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 [online upgrade guide](https://stonescriptphp.org/docs/upgrade) for version-specific migration guides.

Running Development Server
--------------------------

[](#running-development-server)

### Using Composer Scripts (Recommended)

[](#using-composer-scripts-recommended)

The application skeleton ([stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server)) includes composer scripts for running a development server:

```
# Start development server
composer serve
# Server runs on http://localhost:9100
```

Press `Ctrl+C` to stop the server.

### Manual Server Start

[](#manual-server-start)

You can also run PHP's built-in development server directly:

```
# Basic usage
php -S localhost:9100 -t public

# Custom host and port
php -S 0.0.0.0:8080 -t public

# With router script (if needed for URL rewriting)
php -S localhost:9100 -t public public/index.php
```

**Note:** PHP's built-in server is for development only. Use Nginx, Apache, or Caddy in production.

### Production Deployment

[](#production-deployment)

For production environments, configure your web server (Nginx/Apache/Caddy) to:

- Set document root to `public/`
- Route all requests to `public/index.php`
- Enable FastCGI with PHP-FPM

See [deployment documentation](https://stonescriptphp.org/docs/deployment) for production setup guides.

Development Workflow
--------------------

[](#development-workflow)

### 1. Define Database Schema

[](#1-define-database-schema)

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

### 2. Create SQL Functions

[](#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

[](#3-generate-php-model)

```
php stone generate model get_users.pssql
```

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

### 4. Create Route

[](#4-create-route)

```
php stone generate route get-users
```

### 5. Map URL to Route

[](#5-map-url-to-route)

In `src/App/Config/routes.php`:

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

### 6. Implement Route Logic

[](#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

[](#7-run-migrations)

```
php stone migrate verify
```

CLI Tools
---------

[](#cli-tools)

**Location:** `cli/` directory in this package **Usage:** Via `php stone` command from [stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server)

The framework 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          # Generate route handler
php stone generate model    # Generate model from SQL function
php stone generate auth:google          # Generate OAuth authentication
php stone migrate verify                # Check database drift
```

See [stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server) for complete CLI documentation.

Architecture Philosophy
-----------------------

[](#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
------------

[](#requirements)

### Required

[](#required)

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

### Optional

[](#optional)

- Redis server (for caching support)
- PHP Extension: `redis` (for Redis caching)

Auth Service Integration
------------------------

[](#auth-service-integration)

### Auth Service Clients

[](#auth-service-clients)

StoneScriptPHP includes HTTP clients for backend-to-backend operations with the Auth Service.

**Use these for:**

- System automation (e.g., auto-create membership after payment)
- Webhook handlers
- Backend CLI tools
- Bulk operations

#### Membership Client

[](#membership-client)

```
use StoneScriptPHP\Auth\Client\MembershipClient;
use StoneScriptPHP\Auth\Client\AuthServiceException;

$client = new MembershipClient('http://auth-service:3139');

try {
    // Create membership after payment webhook
    $membership = $client->createMembership([
        'identity_id' => $userId,
        'tenant_id' => $tenantId,
        'role' => 'premium_member'
    ], $systemAdminToken);

    // Update role
    $client->updateMembership($membershipId, [
        'role' => 'admin'
    ], $adminToken);

    // Get user's memberships
    $memberships = $client->getUserMemberships($userId, 'myapp', $token);

} catch (AuthServiceException $e) {
    log_error("Auth service error: " . $e->getMessage());
}
```

#### Invitation Client

[](#invitation-client)

```
use StoneScriptPHP\Auth\Client\InvitationClient;

$invitations = new InvitationClient('http://auth-service:3139');

// Invite user
$invitation = $invitations->inviteUser(
    email: 'user@example.com',
    tenantId: $tenantId,
    role: 'member',
    authToken: $adminToken
);

// Bulk invite (system automation)
$invitations->bulkInvite([
    ['email' => 'user1@example.com', 'tenant_id' => $tid, 'role' => 'member'],
    ['email' => 'user2@example.com', 'tenant_id' => $tid, 'role' => 'admin'],
], $adminToken);

// Cancel invitation
$invitations->cancelInvitation($invitationId, $adminToken);
```

**Note:** For frontend operations (user login, token validation), use the auth service directly from Angular or use JWT validation middleware.

Documentation
-------------

[](#documentation)

### 📖 Main Documentation

[](#-main-documentation)

- **[📚 Complete Documentation](https://stonescriptphp.org/docs)** - Full documentation site
- **[🏗️ High Level Design (HLD)](HLD.md)** - System architecture and design
- **[📦 Server Package](https://github.com/progalaxyelabs/StoneScriptPHP-Server)** - Application skeleton

### 🚀 Getting Started

[](#-getting-started)

- [Getting Started Guide](https://stonescriptphp.org/docs/getting-started)
- [CLI Usage Guide](https://stonescriptphp.org/docs/cli-usage)
- [Environment Configuration](https://stonescriptphp.org/docs/environment)

### 🔧 Core Features

[](#-core-features)

- [API Reference](https://stonescriptphp.org/docs/api-reference)
- [Logging & Exceptions](https://stonescriptphp.org/docs/logging)
- [Request Validation](https://stonescriptphp.org/docs/validation)
- [Middleware Guide](https://stonescriptphp.org/docs/middleware)
- [Caching System](https://stonescriptphp.org/docs/caching)

### 🔐 Security

[](#-security)

- [Authentication](https://stonescriptphp.org/docs/authentication)
- [JWT Configuration](https://stonescriptphp.org/docs/jwt)
- [RBAC (Access Control)](https://stonescriptphp.org/docs/rbac)
- [Security Best Practices](https://stonescriptphp.org/docs/security)

### ⚡ Performance

[](#-performance)

- [Redis Caching Guide](https://stonescriptphp.org/docs/caching)
- [Performance Guidelines](https://stonescriptphp.org/docs/performance)

Contributing to the Framework
-----------------------------

[](#contributing-to-the-framework)

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

### Development Setup

[](#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

[](#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
-------------------

[](#versioning-strategy)

StoneScriptPHP follows [Semantic Versioning](https://semver.org/):

- **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.4.2 - Production-ready with ongoing improvements

Related Packages
----------------

[](#related-packages)

- **[stonescriptphp-server](https://github.com/progalaxyelabs/StoneScriptPHP-Server)** - Application skeleton (recommended for new projects)

Support & Community
-----------------------

[](#support--community)

- **Website**: [stonescriptphp.org](https://stonescriptphp.org)
- **Documentation**: [stonescriptphp.org/docs](https://stonescriptphp.org/docs)
- **Framework Issues**: [GitHub Issues](https://github.com/progalaxyelabs/StoneScriptPHP/issues)
- **Discussions**: [GitHub Discussions](https://github.com/progalaxyelabs/StoneScriptPHP/discussions)

License
-------

[](#license)

MIT License - see [LICENSE](LICENSE) file for details

---

Remember: For New Projects
--------------------------

[](#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](https://github.com/progalaxyelabs/StoneScriptPHP-Server) to get started!

###  Health Score

54

—

FairBetter than 96% of packages

Maintenance99

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 99.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

146

Last Release

0d ago

Major Versions

v1.1.0 → v2.0.02025-12-09

v2.12.1 → v3.0.02026-02-20

v3.33.0 → 4.0.02026-06-14

4.8.1 → 5.0.02026-06-26

PHP version history (2 changes)v1.0.0PHP >=8.2

v1.1.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/395201d5852ab3828cb1de9eda82667c405c5dd11b55d9b5be4d768f93955c1d?d=identicon)[pradeepkumardesk](/maintainers/pradeepkumardesk)

---

Top Contributors

[![pradeepkumardesk](https://avatars.githubusercontent.com/u/131523495?v=4)](https://github.com/pradeepkumardesk "pradeepkumardesk (287 commits)")[![pradeepdsmk](https://avatars.githubusercontent.com/u/7545127?v=4)](https://github.com/pradeepdsmk "pradeepdsmk (2 commits)")

---

Tags

phpapiframeworkrestpostgresqltypescriptcode-generation

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/progalaxyelabs-stonescriptphp/health.svg)

```
[![Health](https://phpackages.com/badges/progalaxyelabs-stonescriptphp/health.svg)](https://phpackages.com/packages/progalaxyelabs-stonescriptphp)
```

###  Alternatives

[zemit-cms/core

Build Phalcon REST APIs faster with database-first scaffolding, model relationships, eager loading, identity, permissions, CLI, and WebSocket support.

148.5k1](/packages/zemit-cms-core)[patricksavalle/slim-rest-api

Production-grade REST-API App-class for PHP SLIM, in production on https://zaplog.pro (https://api.zaplog.pro/v1)

101.4k](/packages/patricksavalle-slim-rest-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)