Download the PHP package giovanni-venturelli/sophia without Composer

Sophia Framework — Lightweight PHP Components, DI, and Router

Minimal, production‑oriented PHP framework with:

• Component-based rendering with native PHP templates
• Angular‑inspired Dependency Injection system
• Simple Router (components, API callbacks, parameters, guards)
• Optional database layer with fluent QueryBuilder and Active Record ORM

Components are plain PHP classes (annotated), services are auto‑wired, routes map to components (views) or callbacks (APIs).

Quick navigation

• What you get (features)
• Architecture at a glance
• Installation
• Project structure
• Quick start (index.php + routes.php)
• Create your first component
• Dependency Injection (services)
• Routing basics (components, params, urls)
• Performance & Build System
• Database integration (optional)
• Troubleshooting
• Deep dives (module READMEs)
• Migration from Twig to native PHP

What you get (features)

• Components rendered with native PHP templates and helper functions
• Property injection in components and constructor injection in services
• Root singletons via #[Injectable(providedIn: 'root')]
• Route configuration with parameters, named routes, redirects, nested routes, guards
• Optional database service with fluent QueryBuilder and Active Record entities

Architecture at a glance

• Components: core/component (attributes, registry, renderer)
• DI (Injector): core/injector (root singletons + per‑component scoped providers)
• Router: core/router (maps requests to components or callbacks)
• Database (optional): core/database (connection service + ORM)

Flow for a component route: 1) Router matches the incoming path → selects a component class 2) ComponentRegistry lazily registers it and Renderer creates a ComponentProxy 3) ComponentProxy opens a DI scope, warms providers, creates the component, runs property injection, then onInit() 4) Renderer collects public properties/zero‑arg getters and renders the PHP template

Installation

• PHP 8.1+
• Composer

If you use environment variables, add a .env file (Dotenv is included in composer.json) and configure the database as needed (see Database integration).

Project structure

Quick start (index.php + routes.php)

Minimal bootstrap in index.php:

Define routes in routes.php:

Create your first component

Component class under pages/... and a PHP template next to it:

Template home.php:

The renderer passes route params (:id) as initial data to the root component.

Dependency Injection (services)

• Mark root singletons with #[Injectable(providedIn: 'root')].
• Use property injection in components: #[Inject] private Service $service;
• Use constructor injection in services; dependencies are resolved by the Injector.

Example service + usage in a component:

See the full DI reference: Injector (DI).

Routing basics (components, params, urls)

• Define paths like post/:id to capture params; available to components and templates
• Name routes with name and generate URLs using the url() helper
• Provide data on routes; read them with route_data()

Template helpers:

More details: Router.

Redirections and Guards

(Existing content for Routing basics...)

Performance & Build System

Sophia includes a build system to optimize performance in production (up to 40% faster).

How it works

In development mode (DEBUG=true), the framework scans folders and uses the Reflection API on every request. In production (DEBUG=false), the framework loads pre-generated static maps.

CLI Commands

From the project root:

When to run the build?

The build is only necessary when the structure of the application changes:

• Creating new components or services.
• Modifying routes or selectors.
• Modifying providers in Dependency Injection.

Note: It is not necessary to rebuild if you only modify the database content, the logic code inside a method, or the HTML markup of an existing template.

Database integration (optional)

The ConnectionService is a root‑provided service with a fluent QueryBuilder and an Active Record‑style ORM via Entity.

Example entity:

Query examples:

Full guide: Database.

Troubleshooting

• Template not found: ensure the file exists next to the component class or in a path added to the renderer
• Undefined variable: expose data via public properties or zero‑arg getters
• Injection error: add #[Inject] to typed component properties; mark services as #[Injectable] and/or list them in providers
• Routing mismatch: check basePath, path normalization, and that names/params match when calling url()

Deep dives (module READMEs)

• Components: Components
• Injector (DI): Injector (DI)
• Router: Router
• Database: Database
• Templates: Templates Guide
• Forms: Forms Guide

Using this repository as a package + demo

This repo is organized so that the core framework (package) is published to Packagist, while the demo app stays in-repo only.

• Package (library): giovanni-venturelli/sophia (root of this repo)
  • Namespaces exported: Sophia\\* (component, injector, router, form, database)
  • Packagist dist excludes the demo and app assets via .gitattributes
• Demo app: /demo (not included in the Packagist dist)
  • Depends on the package via Composer repository of type path to the repo root
  • Autoloads the demo namespaces from the project folders (../pages, ../Shared, ../services)

Install the package (as a dependency) in another project

Run the demo locally from this repo

1) Install dependencies for the demo (uses a path repo to the root library):

2) Start a PHP dev server pointing to the demo folder (or your web server root to demo/):

Then open:

• http://localhost:8080/index.php/home/123 (adjust paths if needed)

Notes

• The demo reuses the project folders pages/, Shared/, services/, config/, css/, js/, cache/ from the repo root.
• The router base path in the demo is set to /sophia/demo. If you serve it at a different path, update $basePath in demo/index.php and the global asset paths.
• The package requires PHP >= 8.1; the demo also requires vlucas/phpdotenv for .env loading.

Publishing to Packagist

1) Push this repository to GitHub under giovanni-venturelli/sophia. 2) Create a version tag, e.g.:

3) Submit the repository URL to Packagist and set up the GitHub Service Hook so Packagist auto-updates on new tags.

After publish, consumers can composer require giovanni-venturelli/sophia.

Forms — end-to-end example

Route (already present in routes.php):

Template:

The $form_action('send') helper generates a URL like /sophia/forms/submit/<token>. Make sure the base path is set in index.php.

Named routes — quick tip

Always add name to routes you want to link to from templates:

Then in templates: