velt / framework

v0.1.3 2026-07-09 11:58 UTC

Requires

• php: ^8.2
• velt/cli: ^0.2.0
• velt/database: ^0.1.0
• velt/http: ^0.1.0
• velt/kernel: ^0.1.0
• velt/orm: ^0.1.0
• velt/preview: ^0.1.1
• velt/ui: ^0.1.0

Requires (Dev)

• phpunit/phpunit: ^11.5

Suggests

• velt/skeleton: Install the application skeleton when starting a new Velt project.

MIT

• Samuel Kaluba

Published on Packagist.org on 2026-07-09 12:04 UTC

README

velt/framework is the official compatibility assembly for the Velt ecosystem. It does not hide every subsystem inside one repository: it defines which released Kernel, HTTP, UI, database, ORM, CLI and Preview versions form a supported framework distribution.

Status: alpha. Use the tagged beta CLI and skeleton for evaluation; do not treat the current 0.x component matrix as a production-stable API promise.

Why this package exists

Velt is deliberately modular. A small API can install Kernel, HTTP and database packages directly, while a complete application can require velt/framework and receive the official assembly. Centralizing compatibility constraints prevents each skeleton or application from inventing a different package combination.

This repository owns:

• compatible component constraints;
• minimum PHP and extension requirements shared by the distribution;
• conflicts for combinations known to be incompatible;
• clean-install and lowest/highest dependency tests;
• upgrade notes for coordinated releases;
• the definition of what a Velt framework release contains.

It does not own routing internals, ORM behavior, native bridge code or application templates. Changes to those contracts belong in their focused repositories.

Installation

Most developers should create an application instead of requiring the meta-package manually:

composer global require velt/cli:^0.2@beta
velt new my-app

For a custom Composer application:

composer require velt/framework:^0.1

Component architecture

Component	Purpose
velt/kernel	Application object, dependency container, configuration, providers, events and lifecycle
velt/http	Request/response objects, routing, dispatch and middleware contracts
velt/ui	Declarative page/component tree and renderer contracts
velt/database	PDO connections, query builder, schema, migrations and seeders
velt/orm	Active Record models, querying, persistence and relations
velt/cli	velt new, diagnostics, development commands and generators
velt/preview	Development sessions and versioned preview transport

Android support remains a separate opt-in concern through velt/native; it requires PHP 8.4 and is not forced into web/API applications.

Application boot flow

public/index.php or embedded runtime
        ↓
Composer autoload
        ↓
bootstrap/app.php
        ↓
Kernel Application + configuration
        ↓
service providers register dependencies
        ↓
providers boot after the container is ready
        ↓
HTTP dispatcher, command or native event handles work

An application is expected to keep framework bootstrapping in bootstrap/app.php, domain behavior in feature modules, HTTP declarations in routes, presentation in declarative pages and data changes in migrations.

Current compatibility policy

Framework line	PHP	Kernel	HTTP	UI	Database	ORM	CLI	Preview
0.1.x	^8.2	^0.1	^0.1	^0.1	^0.1	^0.1	^0.2	^0.1

Because the ecosystem is pre-1.0, minor releases can still contain carefully documented contract adjustments. Every breaking change must include an upgrade note and a compatibility-matrix update. Stable 1.0 requires documented deprecation windows and reproducible cross-repository tests.

Selective installation

The meta-package is optional. Backend-only projects may install a smaller set:

composer require \
  velt/kernel:^0.1 \
  velt/http:^0.1 \
  velt/database:^0.1 \
  velt/orm:^0.1

Do not copy local path repositories into published packages. They are acceptable only inside a maintainer sandbox used to develop multiple repositories together.

Development across repositories

A local integration application can use Composer path repositories with symlinks, but the release gate must repeat installation using tags or distribution archives:

{
  "repositories": [
    { "type": "path", "url": "../veltphp-kernel", "options": { "symlink": true } },
    { "type": "path", "url": "../veltphp-http", "options": { "symlink": true } }
  ]
}

After changing package constraints:

composer validate --strict
composer update --with-all-dependencies
composer test

Then verify a clean consumer without those path entries.

Release gates

A framework tag is allowed only when:

• all component manifests validate strictly;
• clean installs succeed on supported PHP and operating systems;
• lowest and highest compatible dependencies pass;
• a web project and API project can be created, migrated, tested and served;
• no published lock or artifact references a local directory or unintended dev-main;
• security advisories and licenses are reviewed;
• the compatibility matrix matches actual available tags;
• changelog and upgrade documentation are complete;
• integration artifacts include source revisions and test reports.

Android is promoted independently only after the additional NativePHP/JNI/Compose/APK gates described in velt-mobile-architecture.

Testing

composer validate --strict
composer install --no-interaction --prefer-dist
composer test

The integration-quality repository owns the larger matrix that creates actual projects and proves the selected component versions together.

Versioning

Velt follows Semantic Versioning. During 0.x, package constraints remain conservative and prerelease tags identify work that is not yet a stable support promise. Coordinated releases should use milestones and record the exact component tag set.

Contributing

Open framework issues only for assembly, compatibility and coordinated-release work. A behavior bug in routing, UI, database or ORM belongs in the repository implementing that behavior. Pull requests changing constraints must explain why the old and new combinations differ and include clean-consumer evidence.

Security

Report dependency-confusion, supply-chain or compatibility vulnerabilities privately through GitHub Security. Do not place credentials, Packagist tokens or signing material in issues, fixtures or workflow logs.

License

MIT