quellabs / canvas
A modern, lightweight PHP framework with contextual containers, automatic service discovery, and ObjectQuel ORM integration
Fund package maintenance!
Requires
- php: >=8.3
- dragonmantank/cron-expression: ^3.6
- monolog/monolog: ^3.10
- quellabs/annotation-reader: ^1
- quellabs/canvas-smarty: ^1
- quellabs/contracts: ^1
- quellabs/dependency-injection: ^1
- quellabs/discover: ^1
- quellabs/sculpt: ^1
- quellabs/signal-hub: ^1
- quellabs/support: ^1
- symfony/http-foundation: ^7.0 || ^8.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 1.34.2
- 1.34.1
- 1.34.0
- 1.33.0
- 1.32.0
- 1.31.0
- 1.30.0
- 1.29.0
- 1.28.1
- 1.28.0
- 1.27.1
- 1.27.0
- 1.26.0
- 1.25.0
- 1.24.0
- 1.23.0
- 1.22.0
- 1.21.1
- 1.21.0
- 1.20.0
- 1.19.0
- 1.18.0
- 1.17.0
- 1.16.0
- 1.15.0
- 1.14.2
- 1.14.1
- 1.14.0
- 1.13.1
- 1.13.0
- 1.12.0
- 1.11.0
- 1.10.8
- 1.10.7
- 1.10.6
- 1.10.5
- 1.10.4
- 1.10.3
- 1.10.2
- 1.10.1
- 1.10.0
- 1.9.3
- 1.9.2
- 1.9.1
- 1.9.0
- 1.8.0
- 1.7.0
- 1.6.5
- 1.6.4
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.1
- 1.5.0
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.7
- 1.2.6
- 1.2.5
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.15
- 1.1.14
- 1.1.13
- 1.1.12
- 1.1.11
- 1.1.10
- 1.1.8
- 1.1.7
- 1.1.6
- 1.1.5
- 1.1.4
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.93
- 1.0.92
- 1.0.91
- 1.0.90
- 1.0.89
- 1.0.88
- 1.0.87
- 1.0.86
- 1.0.85
- 1.0.84
- 1.0.83
- 1.0.82
- 1.0.81
- 1.0.80
- 1.0.79
- 1.0.78
- 1.0.77
- 1.0.76
- 1.0.75
- 1.0.74
- 1.0.73
- 1.0.72
- 1.0.71
- 1.0.70
- 1.0.69
- 1.0.68
- 1.0.67
- 1.0.66
- 1.0.65
- 1.0.64
- 1.0.63
- 1.0.62
- 1.0.61
- 1.0.60
- 1.0.59
- 1.0.58
- 1.0.57
- 1.0.56
- 1.0.55
- 1.0.54
- 1.0.53
- 1.0.52
- 1.0.51
- 1.0.50
- 1.0.49
- 1.0.48
- 1.0.47
- 1.0.46
- 1.0.45
- 1.0.44
- 1.0.43
- 1.0.42
- 1.0.41
- 1.0.40
- 1.0.39
- 1.0.38
- 1.0.37
- 1.0.36
- 1.0.35
- 1.0.34
- 1.0.33
- 1.0.32
- 1.0.31
- 1.0.30
- 1.0.29
- 1.0.28
- 1.0.27
- 1.0.26
- 1.0.25
- 1.0.24
- 1.0.23
- 1.0.22
- 1.0.21
- 1.0.20
- 1.0.12
- 1.0.11
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
This package is auto-updated.
Last update: 2026-11-06 18:35:02 UTC
README
A PHP framework built for real-world projects. New projects get a clean, annotation-driven architecture: aspect-oriented programming, a readable ORM, your choice of template engine, and auto-discovered packages for payments, shipments, and scheduling. Existing projects get all of that too — Canvas drops into a codebase you already have without forcing a rewrite.
How to Install
# New project composer create-project quellabs/canvas-skeleton my-app # Existing project composer require quellabs/canvas
Quick start
class BlogController extends BaseController { /** * @Route("/posts/{id:int}") */ public function show(int $id) { $post = $this->em()->find(Post::class, $id); return $this->render('post.tpl', compact('post')); } }
Controllers are discovered automatically through Composer metadata. Routes are defined with annotations. Typed route parameters ({id:int}) are validated before your method runs. No configuration files, no route registration.
Cross-cutting concerns without the mess
Canvas separates cross-cutting concerns — auth, caching, rate limiting, logging — into aspects: reusable classes applied via annotations instead of tangled into business logic.
/** * @Route("/admin/users") * @InterceptWith(RequireAuthAspect::class, priority=100) * @InterceptWith(CacheAspect::class, ttl=300) * @InterceptWith(RateLimitAspect::class, limit=100, window=3600, throwOnFailure=true) */ public function manage() { $users = $this->em()->findBy(User::class, ['active' => true]); return $this->render('admin/users.tpl', compact('users')); }
Each aspect is a standalone class — BeforeAspect for checks that can short-circuit the request, AroundAspect for wrapping behavior like caching, AfterAspect for post-processing. Aspects inherit through controller hierarchies — apply @InterceptWith on a base class and every child controller gets it automatically — with priority ordering controlling execution sequence within each inheritance level.
RateLimitAspect and CsrfProtectionAspect default throwOnFailure to false: on failure they write a request attribute (rate_limit_exceeded, csrf_validation_succeeded) and let the request continue, leaving your controller responsible for checking it. Pass throwOnFailure=true (as above) when you want the aspect itself to reject the request — the common case for most routes.
ObjectQuel ORM
Canvas integrates with ObjectQuel through the quellabs/canvas-objectquel package. Simple lookups use familiar find and findBy methods. Complex queries use ObjectQuel's declarative syntax:
$results = $this->em()->executeQuery(" range of p is App\\Entity\\Post range of u is App\\Entity\\User via p.authorId retrieve (p, u.name) where p.title = /^Tech/i sort by p.publishedAt desc window 0 using window_size 20 ");
Pattern matching, regex, full-text search, and relationship traversal are first-class query expressions — not raw SQL escapes. ObjectQuel can also join database entities with JSON files in a single query via json_source(), something no other PHP ORM supports.
Templating
Canvas uses Smarty as its default template engine. Twig, Latte, Blade, Plates, and Handlebars are each available as a separate package and can be swapped in without touching controller code.
Security headers & CORS
Create config/app.php with php sculpt canvas:init. Its security_header_policy accepts a single policy class or an ordered list, applied to every response in that order:
// config/app.php return [ 'security_header_policy' => [ BasicSecurityHeaderPolicy::class, CorsSecurityHeaderPolicy::class, ], ];
A route-specific override uses the same syntax and replaces the entire list for that route, not just one entry:
/** * @InterceptWith(SecurityHeadersAspect::class, policyClass={StrictSecurityHeaderPolicy::class, CorsSecurityHeaderPolicy::class}) */
CorsSecurityHeaderPolicy is opt-in and reads its allowlists from config/cors.php, created with php sculpt cors:init. The generated file grants no cross-origin access until filled in:
// config/cors.php return [ 'allowed_origins' => ['https://app.example.com'], 'allowed_methods' => ['GET', 'POST'], 'allowed_headers' => ['Content-Type', 'Authorization'], 'exposed_headers' => ['Location'], 'allow_credentials' => true, 'max_age' => 600, ];
Only exact scheme://host(:port) origins are accepted — * and the opaque null origin are rejected. A preflight (OPTIONS with Access-Control-Request-Method) is approved only when the origin, requested method, and every requested header are allowed; Canvas's generated OPTIONS response already carries the route's matched methods in Allow, which the requested method must also appear in.
Existing single-class configurations keep working unchanged. Basic/Medium/Strict headers (clickjacking, MIME-sniffing, HSTS, CSP) are a separate concern from CORS's cross-origin permission headers — an application opting into CORS still needs one of them, and must list CorsSecurityHeaderPolicy::class in any route override that should keep it.
Legacy integration
Most frameworks assume you're starting fresh. Canvas doesn't. Point it at your existing application, and it takes over routing while your old .php files keep working:
// config/app.php return [ 'legacy_enabled' => true, 'legacy_path' => dirname(__FILE__) . "/../legacy" ];
Canvas checks its own routes first. Unmatched URLs fall through to your legacy files — every existing page keeps working from day one.
legacy_enabled relies on process-wide state (the current working directory, and a header buffer for header()/exit() support) that is reset once per request but is not isolated between requests running concurrently in the same process. This is safe on a traditional one-request-per-process setup (PHP-FPM, Apache mod_php, CLI server) but not under a coroutine/persistent-worker runtime (e.g. Swoole) handling multiple requests concurrently on the same worker — a legacy file's relative include/fopen calls could then run against the wrong working directory. Keep legacy mode on a non-coroutine deployment, or ensure its worker never serves more than one request at a time.
Your legacy code can immediately use Canvas services:
// legacy/admin/dashboard.php — your existing file, now with Canvas services $users = canvas()->get(EntityManager::class)->findBy(User::class, ['active' => true]);
canvas() returns the DI container; pass a DI context (string or array), as accepted by Container::for(), to scope resolution before calling get():
$cache = canvas('redis')->get(CacheInterface::class);
Legacy files using header(), die(), and exit() are automatically preprocessed to work within Canvas's request/response flow. The preprocessing is recursive — included files are transformed too, and results are cached. Any vendor/ path segment is always skipped, since third-party libraries don't need their internals rewritten; exclude other paths (e.g. a vendored library kept outside vendor/) with exclusion_paths:
return [ 'legacy_enabled' => true, 'legacy_path' => dirname(__FILE__) . "/../legacy", 'exclusion_paths' => ['libs/third-party'] ];
URLs are mapped to files by trying each configured resolver in order until one finds a match; by default that's just DefaultFileResolver (/users → legacy/users.php or legacy/users/index.php). Configure legacy_resolvers to add others, such as the built-in WordPressStyleResolver for date-based permalinks (/2024/03/my-post → legacy/posts/2024-03-my-post.php), or your own FileResolverInterface implementation:
use Quellabs\Canvas\Legacy\Resolvers\DefaultFileResolver; use Quellabs\Canvas\Legacy\Resolvers\WordPressStyleResolver; return [ 'legacy_enabled' => true, 'legacy_path' => dirname(__FILE__) . "/../legacy", 'legacy_resolvers' => [WordPressStyleResolver::class, DefaultFileResolver::class] ];
Each resolver class is built with legacy_path passed as its legacyPath constructor argument; any other constructor parameter is autowired through the DI container, the same as controllers and aspects.
Migrate one route at a time. When a Canvas controller claims a URL, it takes precedence over the legacy file. When every route is migrated, set legacy_enabled to false.
Features
- Aspect-oriented programming — Before, Around, and After aspects with annotation parameters, priority ordering, and inheritance through controller hierarchies
- ObjectQuel ORM — declarative query language with pattern matching, hybrid JSON sources, and Data Mapper architecture
- Legacy-first integration — wrap existing PHP apps with route fallthrough, automatic preprocessing of
header()/die()/exit(), and acanvas()helper for accessing the DI container from legacy code - Template engines — Smarty by default, with Twig, Latte, Blade, Plates, and Handlebars available as drop-in packages
- Contextual dependency injection — resolve different interface implementations based on request context, without conditional logic in your code
- Signal/slot event system — Qt-style decoupled service communication with type checking and priority-based handlers
- Task scheduling — cron-style background jobs with timeouts, concurrent execution handling, and optional RabbitMQ/Redis-backed queues
- Payments & shipments — provider-agnostic routers that auto-discover installed payment and carrier packages via Composer metadata
- Loom — definition-driven builder for admin pages, forms, and settings panels with automatic data binding
- Validation & sanitization — declarative rules applied as aspects, keeping controllers clean
- Visual inspector — debug bar with database queries, request analysis, and custom panels.
php sculpt inspector:initcreatesconfig/inspector.phpwithenableddefaulting tofalse; whentrueit injects into every HTML response for every visitor, exposing raw POST data, all cookies, and full SQL text with bound parameter values. Restrict who can reach it (e.g. an IP allowlist or auth check) before enabling it anywhere other than local development. - CLI tooling — route listing, route matching, task management, asset publishing, entity generation, config scaffolding (
canvas:init,inspector:init,cache:init,jwt:init,rate-limit:init,cors:init)
Documentation
Full docs, guides, and API reference: canvasphp.com/docs
Contributing
Bug reports and feature requests via GitHub issues. PRs welcome — fork, branch, follow PSR-12, add tests.
Support
If Canvas saves you time, consider sponsoring development.
License
MIT