Welcome to the SPIN Framework documentation hub. This is your central navigation point for learning the framework, building applications, and contributing to the project.
| Section | Purpose | Best For |
|---|---|---|
| Getting Started | Installation, first app, core concepts | New users |
| User Guide | Feature-by-feature deep dives | Building applications |
| Best Practices | Design patterns, performance, security | Intermediate to advanced |
| Recipes | Code examples, common patterns, tutorials | Problem-solving |
| Contributor Guide | Development setup, testing, contributing | Contributors |
| Reference | API docs, configuration schemas, glossary | Quick lookup |
Start here if you're new to SPIN Framework or web framework development in general.
- Quick-Start.md (~5 minutes) — Install SPIN, create a route, test your first endpoint
- Project-Structure.md (~10 minutes) — Understand framework and application directory layout
- Core-Concepts.md (~15 minutes) — Request/response cycle, routing, middleware, global helpers
- Your-First-App.md (~45 minutes) — Build a complete Task API with CRUD operations
Estimated total reading time: 75 minutes
Where to start: Begin with Quick-Start.md for the fastest path to your first running endpoint.
Related: See Getting-Started/ directory
Comprehensive documentation of SPIN Framework features. Each guide covers one major feature area with examples and best practices.
- Configuration.md — Environment-based config files, variable expansion, reading at runtime
- Routing.md — JSON-based route definitions, route groups, parameter binding, HTTP methods
- Middleware.md — Request/response pipeline, global and group-level middleware, short-circuiting
- Databases.md — PDO drivers, connection pooling, query execution, transactions
- Cache.md — Caching strategies, adapters (Redis, APCu, File), cache invalidation
- Helpers.md — Global helper functions, utilities, response builders, JWT/JWE, UUID generation
- Uploaded-files.md — File upload handling, validation, storage
- Storage-folders.md — Organizing file storage, paths, accessibility
- Security.md — Authentication, authorization, CSRF, input validation, encryption
- Testing.md — PHPUnit setup, writing tests, mocking, integration testing
Recommended reading order:
- Configuration (project setup)
- Routing (how requests map to code)
- Middleware (request processing)
- Databases (data persistence)
- Security (protecting your app)
- Then follow your specific needs
Related: See User-Guide/ directory
Design patterns, architectural decisions, and optimization guidelines developed from real-world experience with the SPIN Framework.
- Error Handling — Exception strategies, error responses, logging
- Type Safety — Leveraging PHP's type system, strict typing requirements
- Code Organization — Structure, namespacing, class responsibilities
- Performance Optimization — Caching strategies, query optimization, profiling
- Middleware Design — Building composable, reusable middleware components
- Controller Organization — Single responsibility, testing, code reuse
- Testing Strategy — Test coverage goals, integration vs. unit tests, mocking strategies
- Configuration Management — Secrets handling, environment-specific configs, validation
- Authentication Flows — JWT patterns, session management, refresh tokens
- Authorization Models — Role-based access control (RBAC), permission validation
- Input Validation — Sanitization, type checking, allowlisting
- CORS and HTTPS — Cross-origin requests, secure headers
- REST Principles — Resource modeling, HTTP method selection, status codes
- API Versioning — Versioning strategies, backward compatibility
- Error Responses — Consistent error formats, documentation
- Documentation — OpenAPI/Swagger, endpoint examples, client SDKs
Related: See Best-Practices/ directory
Practical code examples and step-by-step guides for common development tasks. Each recipe is self-contained and ready to adapt to your needs.
- Creating Your First API — Scaffold, endpoints, response formats
- Building a Multi-Environment App — Configs per environment, secrets management
- Adding Authentication — JWT setup, login endpoints, protected routes
- Setting Up Logging — Application logging, request tracking, error reporting
- Database Migrations — Schema versioning, migrations, rollbacks
- Connection Pooling — Multiple connections, failover, load balancing
- Caching Query Results — Cache keys, invalidation, warming
- Paginating Results — Offset/limit, cursor-based, sorting
- Rate Limiting — Protecting endpoints, quota management
- File Upload APIs — Accepting uploads, validation, storage
- Webhooks — Sending events, retries, security
- Docker Containerization — Dockerfile, compose setup, container config
- CI/CD Integration — GitHub Actions, testing on push, automated deploy
- Performance Tuning — Caching, compression, database optimization
- Monitoring and Observability — Logging, metrics, error tracking
Related: See Recipes/ directory
Documentation for developers contributing to SPIN Framework itself. Learn how to set up your environment, run tests, and submit contributions.
- Development Setup — Cloning, dependencies, IDE configuration
- Running Tests — PHPUnit, coverage, debugging tests
- Code Style — PSR-12, naming conventions, documentation standards
- Commit Conventions — Message format, atomic commits, no merge commits
- Submitting a Pull Request — Branch strategy, PR description, code review process
- Breaking Changes — Impact assessment, deprecation periods, changelog entries
- Adding Features — Design discussion, RFC process, testing requirements
- Bug Fixes — Investigation, test coverage, backporting
- Directory Organization — Where code lives, how it's organized
- Dependency Management — Adding/updating packages, version constraints
- Documentation — Keeping docs in sync, building the doc site
- Release Process — Version numbering, changelog, tagging
Related: See Contributor-Guide/ directory
Quick-lookup documentation for specific topics. Use when you know what you're looking for.
- Core Classes —
Application,Controller,Middleware,Route,Request,Response - Helpers — Function signatures, parameters, return values
- Exceptions — Exception types, error codes, handling
- Configuration Schema — All config keys, types, defaults, examples
- Common Tasks — "How do I...?" index
- Glossary — Terms, acronyms, concepts
- FAQ — Frequently asked questions
- Troubleshooting — Common problems and solutions
- PHP Documentation — php.net
- PSR Standards — PSR-3 (Logging), PSR-7 (HTTP), PSR-11 (Container), PSR-16 (Cache), PSR-17 (HTTP Factories)
- FastRoute — nikic/fast-route
- Monolog — monolog/monolog
- PHP-JWT — firebase/php-jwt
Related: See Reference/ directory
- Read: User Guide → Routing.md — Understand how requests work
- Read: User Guide → Configuration.md — Learn to configure apps
- Try: Recipe "Creating Your First API"
- Read: User Guide → Security.md — Learn to build safely
- Read: User Guide → Testing.md — Learn to test code
- Read: CLAUDE.md — Key architectural decisions
- Skim: User Guide → Routing.md — JSON-based routing is different
- Skim: User Guide → Configuration.md — Environment-based config with macros
- Read: User Guide → Middleware.md — Pipeline architecture
- Reference: Best Practices/ as needed
- Read: Recipe "Creating Your First API"
- Read: User Guide → Routing.md — Route definition
- Read: User Guide → Middleware.md — Middleware patterns
- Read: User Guide → Security.md — Auth/authorization
- Read: Best Practices → API Design
- Try: Recipes for your specific needs
- Read: User Guide → Configuration.md — Environment config
- Read: User Guide → Security.md — Security checklist
- Read: User Guide → Testing.md — Test before deploy
- Try: Recipe "Docker Containerization"
- Try: Recipe "CI/CD Integration"
- Monitor: Set up logging and error tracking
- Read: Contributor-Guide/Development-Setup.md
- Read: Contributor-Guide/Code-Standards.md
- Read: Contributor-Guide/Submitting-Changes.md
- Set up your environment
- Find an issue or feature to work on
- Submit your pull request
Starting a new project: Configuration, Routing, Getting Started Handling database queries: Databases, Best Practices → Performance Building an API: Routing, Security, Best Practices → API Design Protecting my app: Security, Best Practices → Security, Middleware Improving performance: Cache, Best Practices → Performance, Recipes → Performance Tuning Testing my code: Testing, Contributor-Guide → Running Tests Deploying to production: Configuration, Security, Recipes → Deployment Contributing code: Contributor-Guide, Testing
Configuration: User-Guide/Configuration.md, Best-Practices/ Routing: User-Guide/Routing.md Middleware: User-Guide/Middleware.md, Best-Practices/ Databases: User-Guide/Databases.md, Best-Practices/, Recipes/ Caching: User-Guide/Cache.md, Best-Practices/ Security: User-Guide/Security.md, Best-Practices/ Testing: User-Guide/Testing.md, Contributor-Guide/ File Operations: User-Guide/Uploaded-files.md, User-Guide/Storage-folders.md
Beginner: Getting-Started, User-Guide → Configuration, Routing, Middleware Intermediate: User-Guide → Security, Testing, Databases; Best-Practices Advanced: Best-Practices, Recipes, Contributor-Guide
- spin-skeleton — Example application demonstrating SPIN Framework usage. Start here to see a working app.
- SPIN Framework GitHub — Source code, issue tracker, releases
- Packagist: celarius/spin-framework — Installation via Composer
- Documentation Issues — Found an error or unclear explanation? Open an issue
- Questions — Check the FAQ in the Reference/ directory
- Community — Join our community discussions (link to be added)
- Security Issues — Please report responsibly to sandell@celarius.com
This documentation mirrors the current state of SPIN Framework 0.0.35 (pre-1.0). As the framework evolves, documentation is updated to match. Check the CHANGELOG for recent changes and the GitHub releases for version-specific notes.
Last updated: March 2026