Download the PHP package quellabs/canvas without Composer

Canvas

A modern, lightweight PHP framework that gets out of your way. Write clean controllers with route annotations, query your database with an intuitive ORM, and let contextual containers handle the complexity. Built to work seamlessly alongside your existing PHP codebase - modernize incrementally without breaking what already works.

What Makes Canvas Different

• 🔄 Legacy-First Integration - Drop into any existing PHP app without breaking existing URLs
• 🎯 Annotation-Based Routing - Define routes directly in controllers with @Route annotations
• 🗄️ ObjectQuel ORM - Query databases using intuitive, natural PHP syntax
• 📦 Contextual Containers - Work with interfaces; Canvas resolves implementations by context
• ⚡ Aspect-Oriented Programming - Add crosscutting concerns without cluttering business logic

Quick Start

Installation

Bootstrap (public/index.php)

This bootstrap file is automatically generated when using the skeleton package. If you're not using the skeleton package, you'll need to create this file manually.

Controllers with Route Annotations

Canvas automatically discovers controllers and registers their routes using annotations:

ObjectQuel ORM

ObjectQuel lets you query data using syntax that feels natural to PHP developers. Inspired by QUEL (a declarative query language from early relational databases), it bridges traditional database querying with object-oriented programming.

Simple Entity Operations

Advanced ObjectQuel Queries

For complex queries, ObjectQuel provides a natural language syntax:

Key Components

• range - Creates an alias for an entity class, similar to SQL's FROM clause. Think of it as "let p represent App\Entity\Post"
• retrieve - Functions like SQL's SELECT, specifying what data to return. You can retrieve entire entities (p) or specific properties (u.name)
• where - Standard filtering conditions, supporting parameters (:published) and regular expressions (/^Tech/i matches titles starting with "Tech", case-insensitive)
• sort by - Equivalent to SQL's ORDER BY for result ordering
• via - Establishes relationships between entities using foreign keys (p.authorId links posts to users)

ObjectQuel Features

• Readability: More intuitive than complex Doctrine DQL or QueryBuilder syntax
• Type Safety: Entity relationships are validated at query time
• Parameter Binding: Safe parameter substitution prevents SQL injection
• Relationship Traversal: Easily query across entity relationships with via keyword
• Flexible Sorting: Multi-column sorting with sort by field1 asc, field2 desc

Legacy Integration

Canvas is designed to work seamlessly alongside existing PHP codebases, allowing you to modernize your applications incrementally without breaking existing functionality. The legacy integration system provides a smooth migration path from traditional PHP applications to Canvas.

Quick Start with Legacy Code

Start using Canvas today in your existing PHP application. No rewrites required - Canvas's intelligent fallthrough system lets you modernize at your own pace.

First, enable legacy support by updating your public/index.php:

That's it! Your existing application now has Canvas superpowers while everything continues to work exactly as before.

Using Canvas Services in Legacy Files

Now you can immediately start using Canvas services in your existing files:

How Route Fallthrough Works

Canvas uses an intelligent fallthrough system that tries Canvas routes first, then automatically looks for corresponding legacy PHP files:

Custom File Resolvers

If your legacy application has a different file structure, you can write custom file resolvers:

Legacy Preprocessing

Canvas includes preprocessing capabilities to handle legacy PHP files that use common patterns like header(), die(), and exit() functions:

What preprocessing does:

• Converts header() calls to Canvas's internal header management
• Transforms http_response_code() to Canvas response handling
• Converts die() and exit() calls to Canvas exceptions (maintains flow control)

Important limitation: Preprocessing only applies to the main legacy file, not to included/required files. Files included by legacy scripts may need refactoring if they use these functions.

Benefits of Legacy Integration

• 🚀 Zero Disruption: Existing URLs continue to work unchanged
• 🔧 Enhanced Legacy Code: Add Canvas services (ORM, caching, logging) to legacy files
• 🔄 Flexible Migration: Start with services, move to controllers, then to full Canvas
• 📈 Immediate Benefits: Better database abstraction, modern dependency injection, improved error handling

Advanced Features

Route Validation & Wildcards

Available validators: int, alpha, alnum, slug, uuid, email

Route Prefixes

Aspect-Oriented Programming

Canvas provides true AOP for controller methods, allowing you to separate crosscutting concerns from your business logic. Aspects execute at different stages of the request lifecycle.

Creating Aspects

Aspects implement interfaces based on when they should execute:

Applying Aspects

Class-level aspects apply to all methods in the controller:

Method-level aspects apply to specific methods:

Aspect Parameters

Pass configuration to aspects through annotation parameters:

The aspect receives these as constructor parameters:

Execution Order

Aspects execute in a predictable order:

1. Before Aspects - Authentication, validation, rate limiting
2. Around Aspects - Caching, transactions, timing
3. After Aspects - Logging, response modification

Inherited Aspects

Build controller hierarchies with shared crosscutting concerns:

Form Validation

Canvas provides a powerful validation aspect that separates validation concerns from business logic:

Creating Validation Classes

Auto-Response for APIs

Enable automatic JSON error responses for API endpoints:

Contextual Services

Use different implementations based on context:

CLI Commands

Canvas includes a command-line interface called Sculpt for managing your application:

Route Management

Asset Publishing

Canvas provides a powerful asset publishing system to deploy configuration files, templates, and other resources:

Key features:

• Safe publishing with automatic backup creation
• Transaction rollback if operations fail
• Interactive confirmation with preview of changes
• Extensible publisher system for custom deployment needs

Why Canvas?

• Legacy Integration: Works with existing PHP without breaking anything
• Zero Config: Start coding immediately with sensible defaults
• Clean Code: Annotations keep logic close to implementation
• Performance: Lazy loading, route caching, efficient matching
• Flexibility: Contextual containers and composable aspects
• Growth: Scales from simple sites to complex applications

Contributing

We welcome contributions! Here's how you can help improve Canvas:

Reporting Issues

• Use GitHub issues for bug reports and feature requests
• Include minimal reproduction cases
• Specify Canvas version and PHP version

Contributing Code

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow PSR-12 coding standards
4. Add tests for new functionality
5. Update documentation for new features
6. Submit a pull request

License

Canvas is open-sourced software licensed under the MIT license.