Download the PHP package protoframework/proto without Composer

Proto Framework

Introduction to Proto

Proto is an open-source modular monolith framework for building scalable server applications quickly and securely. It's secure, performant, and designed for developer productivity. It includes an AI document to help agents build with Proto.

Overview

Distributed systems are great, except when they are not. Building large, team-based systems that scale presents many challenges—testing, conflicts, build times, response times, developer environments, etc. Proto was created to allow scalable server applications to be built rapidly and securely. Its modular design enables teams to develop specific features without many of the common pitfalls of distributed systems. Proto auto-bootstraps and loads modules on demand, and configuration is managed in the Common/Config .env file.

Framework Features

Proto includes a comprehensive set of features for creating complex applications, including:

• Modules system to encapsulate features
• API Systems with REST Router
• Validation with sanitization
• Server-Sent Events (SSE)
• Websockets & Sockets
• HTTP Resources
• Security Gates and Policies
• Error Tracking and Handling
• Authentication using roles, permissions, and organizations
• Controllers
• Caching (Redis)
• Configs with .env JSON support
• Models with complex relationships (eager and lazy)
• Collections for data manipulation
• Storage Layers to abstract data storage from data sources
• Session Management (database and file support)
• Services & Service Providers
• Events, Event Loops with async support
• Jobs with event queues (database, Kafka support)
• Design Patterns
• HTML Templates using components
• Email Rendering with Templates
• Dispatching Email, SMS, and Web Push
• Resource Generators for quick code scaffolding
• Database Abstractions
• Database Adapters with MySQLi support
• Query Builders
• Database Migrations with seeding support
• Seeding for testing
• Factories for generating test data
• Testing with PHPUnit, data faking, and robust utilities
• Automations to create routine tasks
• File Storage (local, AWS S3 support)
• Integrations to third-party services (REST, JWT, Oauth2 support)
• Utilities for dates, strings, files, encryption, and more

File Structure

A typical Proto application is structured as follows:

• common/ The root for your application code and shared components between modules.
• modules/ Contains self-contained modules for each major domain or feature.
• public/ Front-end assets and public resources.
• vendor/protoframework/proto/ The core framework. This folder is accessible but should not be modified.

Bootstrapping

Proto auto bootstraps when interfacing with an API, Controller, Model, Storage, or Routine. Simply include /vendor/autoload.php and call the namespaced classes you need.

There is no need for extensive manual setup; Proto handles loading, event registration, and other behind-the-scenes tasks automatically.

Core Concepts

The core of Proto is its modular monolith design. Instead of a distributed system with many separate services, Proto encourages building a single application composed of isolated modules. This approach simplifies development, testing, and deployment while maintaining clear boundaries between features.

The common code resides in the common/ directory, which contains shared components and utilities used across modules.

Modules & Gateways

Each feature or domain is encapsulated in its own module under the modules/ folder. Modules are self-contained but can communicate with other registered modules.

Modules

Each module contains its own APIs, controllers, models, and gateways. Modules help isolate features and enable independent testing and deployment.

The structure of a module:

An example Module class:

Gateways

Gateways provide a public interface for module methods. They allow other modules to call functionality without exposing the internal workings of the module. Gateways can support versioning for backward compatibility.

Example gateway implementation:

Accessing a Module Gateway

To access a module's gateway, use the global modules() function followed by the module name and version:

This is an example controller for the Auth module that calls the User module's gateway.

Module Registration

For a module to be valid and loaded, it must be registered in your configuration file (e.g. in the common .env file) under the "modules" key. For example:

API Routing

API routes for a module are defined in an api.php file within the module's API folder. Nested folders allow for deep API paths.

Basic API route example:

api.php files can be nested in subfolders for better organization. Here's a nested API route example:

The file User/Api/Account/api.php contains:

This helps organize and manage API routes more effectively.

Complex API Route Example

Here is a more complex complex example of an api file with multiple routes and middleware applied:

The API router only loads the api.php files within each module's API directory or subdirectory if it matches the router's path. This makes it efficient, only registering routes that would trigger without loading all routes.

Controllers

Controllers are classes used to manage data, handle HTTP requests, validate input, and return standardized responses. They can access models, integrations, or other controllers, and can dispatch email, text, and web push notifications. Proto provides parent controller classes with built-in CRUD methods so child controllers don't need to reimplement common functionality.

Naming Convention

Controller names should always be singular and followed by "Controller":

Controller Types

Proto provides several controller base classes:

• Controller: Basic controller for general use
• ApiController: For handling HTTP requests with built-in request helpers and validation
• ResourceController: Provides full RESTful CRUD functionality for a model
• ModelController: For controllers that primarily interact with a single model

Resource Controllers

Resource controllers are used with the router's resource() method to automatically handle RESTful operations. They provide the following default methods:

• all(Request $request): GET all items
• get(Request $request): GET a single item by ID
• add(Request $request): POST to create a new item
• setup(Request $request): PUT add or update
• update(Request $request): PATCH to update an item
• delete(Request $request): DELETE an item

Example resource controller:

API Controllers

API controllers handle custom HTTP endpoints that don't fit the standard CRUD pattern. They extend ApiController and receive the Request object:

Controller Responses

Controllers return standardized response objects that encapsulate data, success status, and error messages. This standardization is used by the API system.

Available response methods:

Response examples:

Custom Methods

Controllers can have custom methods to extend functionality:

Request Data Handling

Controllers provide methods for accessing request data:

You can customize the request item key:

Validation & Sanitization

Proto includes a powerful validator that sanitizes and validates data by type. The validate() method defines validation rules:

Supported validation types:

• int: Integer
• float: Floating point number
• string: String (with optional length limit using :number)
• email: Email address
• ip: IP address
• phone: Phone number
• mac: MAC address
• bool: Boolean
• url: URL
• domain: Domain name

Validation modifiers:

• required: Field is required
• :number: Set max length (e.g., string:255)

Custom validation in methods:

Getting Resource ID

Resource controllers provide a helper to get the resource ID from request parameters:

Accessing Models and Storage

Controllers can instantiate their associated model and access storage:

Pass-Through Responses

Controllers automatically wrap the result of any undeclared method called on their model or model's storage in a Response object. This allows empty controllers to automatically have access to the model's public methods:

To bypass response wrapping and get raw results, call the method statically:

This feature makes it faster to add new resources without rewriting response logic for every method.

Resource Controller Conventions

ResourceController can own filters, flags, lookups, and lifecycle without overriding all() / get() / add().

Qualify filters. Unqualified keys that match the model $fields are prefixed with the model alias so joins do not make status ambiguous. Default is on; set $qualifyFilters = false to opt out.

If a controller's own filter service reads named, unprefixed properties off the raw client filter (e.g. $clientFilter->isPinned) before building its own SQL, $qualifyFilters auto-prefixing runs on the wrong shape. Either keep $qualifyFilters = false and qualify only the final built fragments via Filter::aliased(), or read from rawRequestFilter() (below) instead of the auto-qualified filter.

Declarative enrichments. Declare batch flags, copied fields, and counts. They run on get() and all() before enrichRows(). Use 'include' => 'name' to gate an enrichment behind ?include=.

Allowlisted includes. ?include=author,stats is ignored unless the name is in $allowedIncludes. Put always-on extras in $defaultIncludes. Models may implement includeJoins($builder, array $includes) for optional joins; keep identity/privacy joins in joins().

List scopes. Model $scopes run on every Model::all() / getRows() / fetchWhere(), and ResourceController also applies them (plus controller $scopes and Policy::scope()) on all() and get(). Direct Model::get($id) does not apply scopes, so internal writes can still load a row. VisibleScope is owner OR (privacy=public AND status=published) — it is a thin preset of Proto\Models\Scopes\OwnershipVisibilityScope, which takes an arbitrary list of AND'd [column, operator, value] visibility conditions (e.g. status='active' AND archivedAt IS NULL) for controllers whose visibility rule isn't the public/published shape.

Lookups and PATCH. $lookupKeys accepts uuid/slug after numeric id. rulesForPartialUpdate() strips required for omitted PATCH fields.

Lifecycle. Override afterAdd / afterUpdate / afterDelete. Successful mutations also emit {model}.created|updated|deleted via events()->emit().

Shared cache. ModelPolicy namespaces keys by user or session. $cacheSharedPayload = true shares lists only (all() keys include applyListScopes()); get() stays user/session scoped. Viewer flags are stripped before a shared list is stored and re-applied after a hit. Declare every viewer-specific field in $currentUserFlags or $enrichments type flag.

Routing. Use router()->resourceStrict('article', ArticleController::class) instead of resource() when the same prefix has item ids and literal children. ResourceHelper defers activation in api.php and prefers static segments, so article/featured wins over article/:id in either order. Use router()->includeApi(__DIR__ . '/Featured/api.php') to compose sibling api files. Outside api.php, call deferActivation() / flushDeferred() or register the literal child first.

Services. Proto\Services\Service provides success(), failure(), restrictFields(), and generateUuid(). Set $serviceClass on the controller instead of constructing a service in __construct(). Gateways memoize children with $this->gateway(ChildGateway::class). Classes that can't extend Proto\Services\Service (e.g. a hand-copied base with its own success() that would collide) can use Proto\Services\Traits\ServiceResultFactory; for ok() / fail() helpers that build the same ServiceResult without a base-class change.

Filters. Request filter JSON cannot carry raw SQL fragments. Columns are allowlisted to the model's filterable fields ( $fields minus secrets, or $filterableFields). Request IN / NOT IN lists are capped at 100. App-built parameterized entries ([sql, [params]]) still work when you append them after getFilter(). For sync windows use Filter::since() (bound params) or Filter::sinceLiteral() / Filter::isSafeTimestamp() when a query builder interpolates the clause. Keys in protected array $passthroughFilterKeys = []; bypass the model-fields allowlist (still parameterized, still IN-capped) for controllers that need a client filter key that isn't a real column. rawRequestFilter() returns the raw decoded client filter before allowlisting for controllers that need to read named properties off it directly.

Search. Model $searchableFields defaults to [] (off). Set ['*'] to infer from $fields minus blacklist, audit, and secret columns (email, phone, token, apiKey, and similar). An explicit list is used as-is.

Other helpers. UserJoinFields presets keep email/mobile off public user joins. BatchMap is the service-layer version of BatchEnrichmentTrait. UnionFeed, PreferenceScorer, and SeenDemotion merge and rank heterogeneous feeds in PHP. Model::countGroupedBy() issues SELECT fk, COUNT(*) … GROUP BY fk. Resource generation also scaffolds factory, seeder, and service files.

Developer Tools

Proto includes a developer application located in public/developer that offers:

• Error tracking
• Migration management
• Generator system for scaffolding modules, gateways, APIs, controllers, and models

Use this tool to quickly scaffold new features or manage existing ones without needing a fully distributed microservices setup.

Getting Started

Installation

1. Install package using Composer:

or start your PHP server.

Contributing

Contributions are welcome! To contribute:

1. Fork the Repository on GitHub
2. Create a Branch for your feature or bug fix
3. Commit Your Changes with clear, descriptive messages
4. Submit a Pull Request with a detailed description of your changes

Releases: Packagist uses git tags for versioning; do not set a "version" field in composer.json.

Please follow our CONTRIBUTING.md for coding standards and guidelines.

License

Proto is open-source software licensed under the MIT License.

Contact

For questions or support, please reach out via:

• GitHub Issues: Proto Issues
• Community Chat: (Coming soon)