readme.md

A super lightweight, modern PHP framework for building web applications and REST APIs

🚀 About SPIN Framework

SPIN is a lightweight, high-performance PHP framework designed for building modern web applications and REST APIs. Built with PHP 8+ and following PSR standards, SPIN provides a clean, intuitive foundation for developers who want speed, flexibility, and simplicity without the overhead of larger frameworks.

✨ Why Choose SPIN?

• 🚀 Lightning Fast - Minimal overhead, optimized for performance
• 🔧 PSR Compliant - Built on industry standards for maximum compatibility
• 📱 Modern PHP 8+ - Leverages the latest PHP features and performance improvements
• 🔄 Flexible Architecture - Easy to extend and customize for your specific needs
• 📚 Comprehensive - Built-in support for routing, middleware, caching, databases, and more
• 🌐 Platform Agnostic - Works seamlessly on Windows, Linux, and macOS

📋 Requirements

• PHP: 8.0 or higher
• Extensions: PDO, JSON, OpenSSL, Mbstring
• Web Server: Apache, Nginx, or any PSR-7 compatible server
• Database: MySQL, PostgreSQL, SQLite, CockroachDB, Firebird, or any PDO-compatible database

🛠️ Installation

Quick Start with Composer

composer require celarius/spin-framework

Using the SPIN Skeleton (Recommended)

For the best development experience, start with our official skeleton project:

# Clone the skeleton
git clone https://github.com/Celarius/spin-skeleton.git my-spin-app
cd my-spin-app

# Install dependencies
composer install

# Start development server
php -S localhost:8000 -t src/public

🏗️ Project Structure

my-spin-app/
├── src/
│   ├── app/
│   │   ├── Config/           # Configuration files
│   │   ├── Controllers/      # Controllers
│   │   ├── Middlewares/      # Custom middleware
│   │   ├── Views/            # Template files
│   │   └── Globals.php       # Global functions
│   ├── public/               # Web root directory
│   │   ├── bootstrap.php     # Application entry point
│   └── storage/              # Application storage
│       ├── logs/             # Log files
│       ├── cache/            # Optional. Cache files
├── vendor/                   # Composer dependencies
├── composer.json             # Project dependencies

🚀 Getting Started

1. Configuration

SPIN uses JSON-based configuration files, in the /Config folder, named after the environment config-<env>.json:

{
  "application": {
    "global": {
      "maintenance": false,
      "timezone": "Europe/Stockholm"
    },
    "secret": "${env:APPLICATION_SECRET}"
  },
  "session": {
    "cookie": "SID",
    "timeout": 3600,
    "driver": "apcu"
  },
  "logger": {
    "level": "notice",
    "driver": "php"
  }
}

Configuration files support ${env:<varName>} macros for environment variables in values

2. Routing

Routes are defined in JSON configuration files:

{
  "common": {
    "before": ["\\App\\Middlewares\\RequestIdBeforeMiddleware"],
    "after": ["\\App\\Middlewares\\ResponseLogAfterMiddleware"]
  },
  "groups": [
    {
      "name": "Public API",
      "prefix": "/api/v1",
      "before": ["\\App\\Middlewares\\CorsBeforeMiddleware"],
      "routes": [
        { "methods": ["GET"], "path": "/health", "handler": "\\App\\Controllers\\Api\\HealthController" }
      ]
    },
    {
      "name": "Protected API",
      "prefix": "/api/v1",
      "before": ["\\App\\Middlewares\\AuthHttpBeforeMiddleware"],
      "routes": [
        { "methods": ["GET"], "path": "/users/{id}", "handler": "\\App\\Controllers\\Api\\UserController" }
      ]
    }
  ]
}

3. Controllers

Controllers extend SPIN's base classes and use specific HTTP method handlers:

<?php declare(strict_types=1);

namespace App\Controllers;

use \App\Controllers\AbstractPlatesController;

class IndexController extends AbstractPlatesController
{
    public function handleGET(array $args)
    {
        $model = ['title' => 'Welcome to SPIN', 'user' => 'Guest'];
        $html = $this->engine->render('pages::index', $model);
        return response($html);
    }
}

4. Middleware

Middleware extends Spin\Core\Middleware:

<?php declare(strict_types=1);

namespace App\Middlewares;

use Spin\Core\Middleware;

class AuthMiddleware extends Middleware
{
    public function initialize(array $args): bool
    {
        $this->secret = config('application.secret');
        return true;
    }

    public function handle(array $args): bool
    {
        $token = getRequest()->getHeaderLine('Authorization');
        if (!$this->validateToken($token)) {
            responseJson(['error' => 'Unauthorized'], 401);
            return false;
        }
        return true;
    }
}

🔧 Core Features

🛣️ JSON-Based Routing

• Route Groups - Organize routes with shared middleware and prefixes
• HTTP Method Support - Full support for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• Dynamic Parameters - Capture URL parameters with {paramName} syntax
• Middleware Integration - Apply middleware at common, group, or route level

🔌 Middleware System

• Common Middleware - Applied to all requests globally
• Group Middleware - Applied to specific route groups
• Route Middleware - Applied to individual routes
• SPIN-Specific - Uses initialize() and handle() methods

🗄️ Database Support

• Multiple Drivers - MySQL, PostgreSQL, SQLite, CockroachDB, Firebird
• PDO Based - Secure, prepared statements by default
• Connection Management - Efficient database connection handling
• JSON Configuration - Database settings in configuration files

💾 Caching

• PSR-16 Compatible - Standard cache interface
• Multiple Adapters - APCu, Redis, File-based caching
• JSON Configuration - Cache settings in configuration files
• Performance Optimized - Minimal overhead for maximum speed

📁 File Management

• Secure Uploads - Built-in security and validation
• Multiple Storage Backends - Local, cloud, or custom storage
• File Processing - Image manipulation, document processing
• Access Control - Fine-grained permissions and security

📚 Documentation

Complete documentation is available in the doc/ directory. Quick navigation:

Topic	Resources
Getting Started	Quick Start • Core Concepts • Your First App
User Guide	Configuration • Routing • Middleware • Databases • Cache
Development	Security • Testing • Helpers • File Uploads
Best Practices	Application Design • Error Handling • Performance • Database Patterns
Recipes & Examples	Authentication • CORS Handling • Rate Limiting • Deployment
API Reference	Core Classes & Functions

Browse doc/README.md for the complete documentation index.

🧪 Testing

Run Tests

# Windows
.\phpunit.cmd

# Linux/macOS
./vendor/bin/phpunit

# With coverage report
./vendor/bin/phpunit --coverage-html coverage/

Test Structure

tests/
├── Unit/              # Unit tests
├── Integration/       # Integration tests
├── Feature/           # Feature tests
└── bootstrap.php      # Test bootstrap

🌐 Web Server Configuration

Apache Configuration

<VirtualHost *:80>
    ServerName mydomain.com
    DocumentRoot "/path/to/your/app/src/public"

    <Directory "/path/to/your/app/src/public">
        AllowOverride All
        Require all granted

        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^ bootstrap.php [QSA,L]
    </Directory>
</VirtualHost>

Nginx Configuration

server {
    listen 80;
    server_name mydomain.com;
    root /path/to/your/app/src/public;
    index bootstrap.php;

    location / {
        try_files $uri $uri/ /bootstrap.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index bootstrap.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

🔌 PSR Standards Support

SPIN Framework is built on PSR standards for maximum compatibility:

• PSR-3 - Logger Interface (Monolog by default)
• PSR-7 - HTTP Message Interface (Guzzle by default)
• PSR-11 - Container Interface (League Container by default)
• PSR-15 - HTTP Middleware Interface
• PSR-16 - Simple Cache Interface
• PSR-17 - HTTP Factory Interface

🚀 Performance Features

• Lazy Loading - Components loaded only when needed
• Memory Management - Efficient memory usage and garbage collection
• Connection Pooling - Optimized database connections
• Smart Caching - Intelligent cache invalidation and management
• Compiled Routes - Fast route matching and resolution

🔒 Security Features

• CSRF Protection - Built-in cross-site request forgery protection
• SQL Injection Prevention - PDO prepared statements by default
• XSS Protection - Automatic output escaping
• File Upload Security - Secure file handling and validation
• Input Validation - Comprehensive input sanitization
• JWT Support - Built-in JWT token handling
• Rate Limiting - Built-in request rate limiting

🌟 Community & Support

Getting Help

• Documentation: https://github.com/Celarius/spin-framework
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Code of Conduct

Please read our Code of Conduct to keep our community approachable and respectable.

📄 License

SPIN Framework is open-sourced software licensed under the MIT License.

🙏 Acknowledgments

• Built with ❤️ by the SPIN Framework Team
• Inspired by modern PHP frameworks and PSR standards
• Special thanks to all contributors and the PHP community

📊 Statistics

• Downloads:
• Version:
• Tests:

---

Ready to build something amazing? Start with SPIN Framework today and experience the joy of lightweight, fast PHP development! 🚀