Download the PHP package pagemill/mvc without Composer

PageMill MVC

A lightweight, modern PHP MVC framework focused on developer experience and clean architecture. PageMill MVC provides the essential building blocks for web applications without the bloat, making it perfect for developers who want control without complexity.

Why PageMill MVC? Built for modern PHP (8.2+), fully type-hinted, extensively tested (368 tests, 100% file coverage), and designed around proven patterns. It's the MVC framework that gets out of your way and lets you build.

Features

• ✅ Full MVC Architecture - Complete separation of concerns with Controllers, Models, Views, and Actions
• 🎨 Asset Management - Built-in CSS/JS asset handling with combining, minification, and cache busting
• 📄 Multiple Response Types - HTML templates, JSON APIs, and custom formats out of the box
• 🔧 Component System - Reusable UI elements with automatic asset injection
• 🎯 Content Negotiation - Automatic format detection and response generation based on Accept headers
• 📦 Property Mapping - Type-safe array-to-object mapping with validation
• ⚡ Lightweight - No bloat, just the essentials you need
• 🧪 Fully Tested - 368 tests with comprehensive coverage
• 🔍 Modern PHP - Requires PHP 8.2+, fully type-hinted with strict types
• 📚 Well Documented - Complete PHPDoc blocks and extensive test examples

Requirements

• PHP 8.2 or higher
• Composer

Installation

Install via Composer:

The framework will automatically install its dependencies:

• pagemill/http - HTTP request/response handling
• dealnews/filter - Input filtering and validation
• pagemill/accept - Content-type negotiation

Quick Start

Here's a minimal example to get you up and running in under 5 minutes:

1. Create a Simple Controller

2. Create a View

3. Create a Responder

4. Wire It Up

That's it! You now have a working MVC application.

Core Concepts

PageMill MVC follows a request/response flow through four main components:

Controllers

Controllers orchestrate the request handling. They:

• Filter and validate input
• Execute actions (validation, business logic)
• Build models (fetch data)
• Return data to responders

Actions

Actions contain reusable business logic:

Models

Models fetch and prepare data:

Responders

Responders handle content negotiation and choose the appropriate view:

Views

Views generate output. HTML views extend Template\HTMLAbstract:

JSON views extend View\JSONAbstract:

Asset Management

PageMill MVC includes a powerful asset management system for CSS and JavaScript:

Basic Asset Usage

Asset Locations

Configure where assets are stored:

Inline Assets

Embed assets directly in HTML:

Combined Assets

Use the Combine class to serve multiple assets as one file:

URL format: /combine.php?css=normalize,main,app&v=12345

Element Assets

Automatically load assets from UI components:

Document Metadata

Manage page metadata with the Document class:

UI Components (Elements)

Create reusable UI components:

Configuration

Environment Settings

Property Mapping

The PropertyMap trait maps array data to object properties with type validation:

API Reference

Core Classes

ControllerAbstract

Purpose: Orchestrates request handling

Key Methods:

• handleRequest(): array - Processes the request, returns [$data, $inputs]
• getFilters(): array - Returns input filter definitions
• getRequestActions(): array - Returns validation actions
• getDataActions(): array - Returns data transformation actions
• buildModels(): array - Returns model instances for data fetching

ActionAbstract

Purpose: Encapsulates reusable business logic

Key Methods:

• doAction(array $data): mixed - Executes the action logic
• getErrors(): array - Returns validation errors

ModelAbstract

Purpose: Fetches and prepares data

Key Methods:

• getData(): array - Returns data array (abstract, must implement)

ResponderAbstract

Purpose: Handles content negotiation and response generation

Key Methods:

• respond(array $data, array $inputs): void - Generates and sends response
• acceptable(string $header): bool - Checks if content type is acceptable
• getAcceptedContentTypes(): array - Returns accepted content types
• getView(string $content_type): string - Returns view class name for content type

ViewAbstract

Purpose: Base class for all views

Properties:

• $http_response - HTTP response object

Key Methods:

• generate(): void - Generates output (abstract, must implement)

HTML/Template Classes

Template\HTMLAbstract

Purpose: Base class for HTML views

Properties:

• $assets - Asset manager instance
• $element_assets - Element asset injector
• $document - Document metadata manager

Key Methods:

• generate(): void - Orchestrates HTML generation
• prepareDocument(): void - Set up metadata and assets (abstract)
• generateHeader(): void - Output HTML header (abstract)
• generateBody(): void - Output main content (abstract)
• generateFooter(): void - Output footer and closing tags (abstract)

View\JSONAbstract

Purpose: Base class for JSON API responses

Key Methods:

• generate(): void - Outputs JSON (implemented)
• getData(): array - Returns data to encode (abstract)

HTML\Document

Purpose: Manages document metadata

Properties:

• $title - Page title
• $canonical - Canonical URL
• $robots_index - Allow indexing (default: true)
• $robots_follow - Allow following links (default: true)
• $robots_archive - Allow archiving (default: true)

Key Methods:

• addMeta(array $attributes): void - Add meta tag
• generateHead(): string - Generate <head> contents
• generateHeaders(): void - Send HTTP headers

HTML\Assets

Purpose: Manages CSS and JavaScript assets

Key Methods:

• init(): Assets - Get singleton instance
• addLocation(string $type, array $config): void - Register asset location
• add(string $type, array $assets, string $group = 'default'): void - Add assets
• link(string $type, string $group = 'default'): void - Output <link> or <script> tags
• inline(string $type, string|array $assets): void - Output inline CSS/JS
• setTagTemplate(string $type, string $template): void - Customize output template

HTML\Assets\Injector

Purpose: Automatically loads assets from Element classes

Key Methods:

• add(array $elements): void - Register elements and load their assets
• inline(string $type, string $group = 'default'): void - Output inline assets
• link(string $type, string $group = 'default'): void - Output linked assets

ElementAbstract

Purpose: Base class for reusable UI components

Key Methods:

• static getAssets(?string $class = null): array - Returns required assets
• generateElement(): void - Outputs HTML (abstract)

Utility Classes

Environment

Purpose: Global configuration manager

Key Methods:

• static debug(?bool $toggle = null): bool - Get/set debug mode

Traits\PropertyMap

Purpose: Type-safe property mapping

Key Methods:

• mapProperties(array $inputs, ?bool $ignore = null): void - Maps array to properties

Advanced Usage

Custom Content Types

Support custom response formats:

Nested Actions

Actions can be composed for complex workflows:

Custom Asset Handlers

Create custom asset output formats:

Error Handling

Testing

Running Tests

Run the complete test suite:

Test Coverage

The framework has comprehensive test coverage:

• 368 tests with 734 assertions
• 100% file coverage (16/16 source files)
• ~90% line coverage

See tests/README.md for detailed coverage information.

Writing Tests for Your Application

Example controller test:

Architecture & Best Practices

Request Flow

1. Request arrives → Create Request object
2. Controller instantiated → Filters input
3. Request actions execute → Validation, authorization
4. Models built → Data fetched
5. Data actions execute → Transform/enrich data
6. Responder chooses view → Based on Accept header
7. View generates output → HTML, JSON, etc.
8. Response sent → Complete

Separation of Concerns

• Controllers - Orchestration only, no business logic
• Actions - Business logic, validation, side effects
• Models - Data fetching only
• Views - Presentation only, no data fetching
• Responders - Content negotiation only

When to Use What

Use Controllers when:

• You need to coordinate multiple actions and models
• You're handling HTTP requests

Use Actions when:

• You have reusable business logic
• You need validation that can fail
• You're performing side effects (sending email, logging, etc.)

Use Models when:

• You're fetching data from a database or API
• You're transforming raw data into a usable format

Use Elements when:

• You have reusable UI components
• Components have their own CSS/JS requirements

Performance Tips

1. Asset Combining - Use Combine to reduce HTTP requests
2. Lazy Loading - Only load what you need when you need it
3. Caching - Assets class supports MD5 fingerprinting for cache busting
4. Inline Critical CSS - Use $assets->inline() for above-the-fold styles

Troubleshooting

Common Issues

Problem: "Class not found" errors

Solution: Run composer dump-autoload to regenerate autoload files.

Problem: Assets not loading

Solution: Ensure asset locations are configured correctly:

Problem: Type errors when mapping properties

Solution: Ensure your input data types match property types, or use constraints:

Problem: "Unknown configuration input" exception

Solution: Either add the property to your class, or use ignore mode:

FAQ

Q: Do I have to use all components?

A: No! Use what you need. The framework is designed to be modular. You can use just the asset management, just the MVC components, or everything together.

Q: Can I use this with existing frameworks?

A: Yes, PageMill MVC can be integrated into existing applications. The components are standalone and don't require a specific application structure.

Q: How do I handle AJAX requests?

A: Use JSONAbstract views and let the Responder handle content negotiation automatically based on the Accept header.

Q: Is this production-ready?

A: Yes. The framework is fully tested, type-safe, and follows modern PHP best practices.

Q: What's the performance like?

A: PageMill MVC is lightweight with minimal overhead. The asset system includes combining and caching for production optimization.

Q: Can I extend the base classes?

A: Absolutely! All abstract classes are designed to be extended. That's the whole point.

Contributing

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

Reporting Bugs

1. Check if the bug has already been reported in Issues
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • PHP version and environment details

Suggesting Features

1. Open an issue describing the feature
2. Explain the use case and benefits
3. Provide examples if possible

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (./vendor/bin/phpunit)
5. Follow PSR-12 coding standards
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Code Style

• Follow PSR-12 coding standards
• Use strict types (declare(strict_types=1))
• Add type hints for all parameters and return types
• Write PHPDoc blocks for all public methods
• Keep methods focused and small
• Write tests for new features

License

PageMill MVC is open-source software licensed under the BSD-3-Clause license.

Copyright © 1997-Present DealNews.com, Inc

Credits

Maintainer: DealNews.com, Inc

Dependencies

• pagemill/http - HTTP request/response handling
• pagemill/accept - Content-type negotiation
• dealnews/filter - Input filtering

Built with ❤️ by developers, for developers.

For questions, issues, or discussions, please use the GitHub Issues page.