PHPackages spatial/spatial - 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. [Queues & Workers](/categories/queues) 4. / 5. spatial/spatial ActiveProject[Queues & Workers](/categories/queues) spatial/spatial =============== PHP8+ WebAPI Clean Architecture Framework. 4.1.0(2y ago)3131MITPHPPHP ^8.2 Since Sep 20Pushed 1w agoCompare [ Source](https://github.com/aiira-co/spatial)[ Packagist](https://packagist.org/packages/spatial/spatial)[ Docs](https://github.com/aiira_co/spatial)[ RSS](/packages/spatial-spatial/feed)WikiDiscussions master Synced 3d ago READMEChangelog (10)Dependencies (10)Versions (23)Used By (0) Spatial Framework - Starter Project =================================== [](#spatial-framework---starter-project) This is the official starter template for the Spatial PHP Framework, showcasing best practices and modern patterns. Quick Start ----------- [](#quick-start) ``` # Create a new project from Packagist composer create-project spatial/spatial my-api cd my-api # Configure environment cp .env.example .env # Edit .env with your database credentials # Run the application docker-compose up -d # Access the API curl http://localhost:8800/web-api/health ``` Project Structure ----------------- [](#project-structure) This project demonstrates Spatial's **Clean Architecture** approach: ``` src/ ├── presentation/ # API Layer (Controllers, Modules) │ ├── IdentityApi/ # User authentication & management │ ├── WebApi/ # Public web API │ └── AppModule.php # Main application module ├── core/Application/ # Business Logic (CQRS Handlers) │ └── Logics/ │ ├── Identity/ # User domain logic │ └── App/ # Application domain logic ├── infrastructure/ # External concerns (Services, Middleware) └── common/ # Shared utilities & DTOs ``` Generated Code Examples ----------------------- [](#generated-code-examples) This project uses **Spatial CLI v1.1+** with all modern features: ### Example 1: Health Check (Simple) [](#example-1-health-check-simple) **Clean code without observability** - Perfect for simple endpoints: ``` php vendor/bin/spatial make:controller Health --module=WebApi ``` See: `src/presentation/WebApi/Controllers/HealthController.php` ### Example 2: Products API (With Configuration) [](#example-2-products-api-with-configuration) **Uses .spatial.yml defaults** - Logging enabled automatically: ``` # With .spatial.yml, this automatically includes: # - Logging (from config defaults) # - Auth (from controller overrides) php vendor/bin/spatial make:controller Products --module=WebApi ``` See: `src/presentation/WebApi/Controllers/ProductsController.php` ### Example 3: User Management (Full Observability) [](#example-3-user-management-full-observability) **Critical business endpoints** - Full logging, tracing, and auth: ``` php vendor/bin/spatial make:controller User --module=IdentityApi --logging --tracing --auth ``` See: `src/presentation/IdentityApi/Controllers/UserController.php` Configuration File (.spatial.yml) --------------------------------- [](#configuration-file-spatialyml) This project includes a `.spatial.yml` file with sensible defaults: ``` generators: defaults: logging: true # Log by default tracing: false # Trace only critical paths releaseEntity: true # Prevent memory leaks overrides: make:controller: auth: true # Protected by default make:query: tracing: true # Monitor query performance make:command: tracing: true # Track business operations ``` ### Benefits of Configuration: [](#benefits-of-configuration) - **Consistency**: Team-wide coding standards - **DRY**: No repetitive flags - **Flexibility**: Override per-command when needed CLI Features Showcase --------------------- [](#cli-features-showcase) ### 1. Dry-Run Mode [](#1-dry-run-mode) Preview code before creating: ``` php vendor/bin/spatial make:query GetProducts --module=App --entity=Product --dry-run ``` ### 2. Smart Error Messages [](#2-smart-error-messages) Helpful suggestions for typos: ``` php vendor/bin/spatial make:query GetUsers --module=Identty --entity=User # ❌ Module 'Identty' not found. # 💡 Did you mean: IdentityApi? ``` ### 3. Optional Features [](#3-optional-features) Choose what you need: ``` # Minimal (no OTEL) php vendor/bin/spatial make:query GetSimple --module=App --entity=Data # With logging only php vendor/bin/spatial make:query GetUsers --module=Identity --entity=User --logging # Full observability php vendor/bin/spatial make:command ProcessOrder --module=App --entity=Order --logging --tracing --releaseEntity ``` Example Workflows ----------------- [](#example-workflows) ### Creating a New API Feature [](#creating-a-new-api-feature) 1. **Create the module:** ``` php vendor/bin/spatial make:module OrdersApi ``` 2. **Create entity and handlers:** ``` php vendor/bin/spatial make:entity Order --schema=Orders php vendor/bin/spatial make:command CreateOrder --module=Orders --entity=Order php vendor/bin/spatial make:query GetOrders --module=Orders --entity=Order ``` *Note: Logging and tracing automatically added from .spatial.yml* 3. **Create controller:** ``` php vendor/bin/spatial make:controller Order --module=OrdersApi ``` *Note: Auth automatically added from .spatial.yml* 4. **Add event listener (optional):** ``` php vendor/bin/spatial make:listener SendOrderEmail --event=OrderCreatedEvent ``` API Endpoints ------------- [](#api-endpoints) ### Health Check [](#health-check) ``` GET /web-api/health ``` ### Products [](#products) ``` GET /web-api/products # List all GET /web-api/products/{id} # Get one POST /web-api/products # Create (requires auth) PUT /web-api/products/{id} # Update (requires auth) DELETE /web-api/products/{id} # Delete (requires auth) ``` ### Values (Demo) [](#values-demo) ``` GET /web-api/values GET /web-api/values/{id} ``` Best Practices Demonstrated --------------------------- [](#best-practices-demonstrated) 1. **Clean Architecture**: Separation of concerns (presentation, core, infrastructure) 2. **CQRS Pattern**: Commands for mutations, queries for reads 3. **Dependency Injection**: All dependencies injected via constructor 4. **Optional Observability**: Add logging/tracing only where needed 5. **Configuration over Convention**: Customize via .spatial.yml 6. **API-First Design**: RESTful endpoints with proper HTTP verbs Configuration ------------- [](#configuration) ### Environment Variables (.env) [](#environment-variables-env) ``` APP_NAME="Spatial API" APP_ENV=development # Database DB_CONNECTION=mysql DB_HOST=mysql DB_PORT=3306 DB_DATABASE=spatial DB_USERNAME=root DB_PASSWORD=secret #OpenTelemetry (Optional) OTEL_ENABLED=true OTEL_ENDPOINT=http://otel-collector:4318 ``` ### Server Configuration [](#server-configuration) - **PHP 8.2+** required - **OpenSwoole** for async performance - **Docker** for easy deployment Development Commands -------------------- [](#development-commands) ``` # Code generation php vendor/bin/spatial make:query --module= --entity= php vendor/bin/spatial make:command --module= --entity= php vendor/bin/spatial make:controller --module= php vendor/bin/spatial make:listener --event= # Database php vendor/bin/spatial migrate:run php vendor/bin/spatial migrate:rollback php vendor/bin/spatial db:seed # Code quality php vendor/bin/spatial lint php vendor/bin/spatial lint --fix php vendor/bin/spatial analyze --level=5 ``` Learning Resources ------------------ [](#learning-resources) - **Framework Docs**: - **CLI Reference**: See `vendor/spatial/cli/README.md` - **Examples**: Explore `src/` directory - **Clean Architecture**: - **CQRS Pattern**: Next Steps ---------- [](#next-steps) 1. **Explore the Code**: Check out existing controllers and handlers 2. **Try the CLI**: Generate your first feature with dry-run mode 3. **Customize**: Edit `.spatial.yml` to match your team's standards 4. **Build**: Create your amazing API! License ------- [](#license) MIT License - See LICENSE file for details Support ------- [](#support) - **Issues**: [GitHub Issues](https://github.com/aiira-co/spatial/issues) - **Discussions**: [GitHub Discussions](https://github.com/aiira-co/spatial/discussions) - **Email**: ### Health Score 45 — FairBetter than 91% of packages Maintenance64 Regular maintenance activity Popularity10 Limited adoption so far Community7 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor1 Top contributor holds 100% 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 ~94 days Recently: every ~0 days Total 21 Last Release 964d ago Major Versions 1.2.0 → 2.0.02018-10-14 1.1.1 → v2.x-dev2018-10-14 v2.x-dev → 3.3.32021-03-19 3.2.21 → 4.0.02023-11-11 3.4.3 → v4.x-dev2023-11-11 PHP version history (4 changes)1.2.0PHP ^7.4 3.0.0.x-devPHP >=7.2.0 2.0.0PHP ^8.0 4.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/89a7841218dbe957691b40303edd1b54b253070d3e8750b39ed705b2ddb6ed8d?d=identicon)[spatial](/maintainers/spatial) --- Top Contributors [![aiira-co](https://avatars.githubusercontent.com/u/28719431?v=4)](https://github.com/aiira-co "aiira-co (118 commits)") --- Tags phpasyncapidockerswoolespatialclean architecture ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/spatial-spatial/health.svg) ``` [![Health](https://phpackages.com/badges/spatial-spatial/health.svg)](https://phpackages.com/packages/spatial-spatial) ``` ### Alternatives [shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.6M554](/packages/shopware-core)[contao/core-bundle Contao Open Source CMS 1231.6M2.7k](/packages/contao-core-bundle)[rcsofttech/audit-trail-bundle Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking. 1189.8k](/packages/rcsofttech-audit-trail-bundle)[concrete5/core Concrete core subtree split 20166.1k49](/packages/concrete5-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)