Tereta Framework

Overview

Modular, attribute-driven PHP framework with web and CLI runtimes.
It allows developers to build applications with minimal configuration, leveraging the powerful features of PHP 8.4+ and extending functionality through modules and attributes.
Best suited for commercial projects where extensibility, flexibility and cost-effective development matter.

Key responsibilities:

Bootstrap web and CLI runtime flows
Load runtime configuration from .config.php (can be moved outside the web root via require)
Wire core modules (routing, DB, customer, theme, admin packages)
Provide extension points via module classes and attributes

Quick Start

1. Create a new project from the skeleton:

composer create-project tereta/project .
composer server
php ./cli

This bootstraps a fresh project with all tereta/ core packages installed into vendor/, entry points (cli.php, pub/index.php), and a sample configuration.

Alternatively, for framework contributors, clone the monorepo:

git clone https://gitlab.com/tereta/framework.git . composer install

2. Configure the project:

cp .config.sample.php .config.php chmod -R 755 var/

Edit .config.php to set database DSN, SMTP credentials, reCAPTCHA keys, etc.

3. Run locally:

composer server # without Docker, using built-in PHP server composer docker:up # with Docker

composer setup performs the full bootstrap in one go (install, Docker up, DB schema refresh, theme install & build):

composer setup

4. Build the theme separately (if needed):

composer theme:install composer theme:build

5. On macOS with Docker, generate local SSL certificates for dev domains:

composer docker:certificate -- domain.dev domain.com

6. Run tests and static analysis:

composer test

Project Structure

The skeleton is intentionally small — framework modules live in vendor/tereta/ and are installed via Composer. Your application code lives in src/.

.
├── cli.php                 # CLI entry point
├── pub/
│   ├── index.php           # Web application entry point
│   ├── media/              # User-uploaded media (gitignored)
│   ├── theme/              # Built theme assets (gitignored)
│   └── site.webmanifest
├── src/                    # Your application code (PSR-4 autoloaded from `/`)
├── packages/               # Local path-repo packages (optional, gitignored by default)
├── resources/              # Project resources (pages, templates) — gitignored
├── theme/                  # Theme sources (SCSS, JS) — see tereta/theme
├── dev/
│   ├── docker/             # Docker Compose + tools (certificates, nginx, php-fpm)
│   ├── cicd/               # CI/CD helpers
│   ├── git/                # Git hooks and scripts
│   └── phpstan/            # PHPStan bootstrap
├── docs/                   # Documentation (RU translation lives here)
├── var/                    # Runtime state: cache, logs (gitignored, must be writable)
├── vendor/                 # Composer dependencies (incl. tereta/* core modules)
├── .config.sample.php      # Configuration template — copy to .config.php
├── .config.web.php         # Web-only overrides
├── composer.json
└── README.md

Core framework modules (installed via Composer under vendor/tereta/):

Package	Responsibility
`tereta/application`	Web and CLI runtime bootstrap
`tereta/cache`	Caching services and adapters
`tereta/cli`	CLI commands, input/output
`tereta/config`	Configuration pool
`tereta/core`	Shared models, traits, interfaces
`tereta/customer`	Auth, registration, account flows
`tereta/db`	DB abstraction, models, schemas
`tereta/di`	Dependency injection container
`tereta/email`	Email transports and factory
`tereta/fs`	File and directory utilities
`tereta/logger`	Logging channels
`tereta/markdown`	Markdown processing
`tereta/page`	Page controllers
`tereta/recaptcha`	reCAPTCHA validation
`tereta/route`	Routing, requests, responses
`tereta/security`	CSRF, security headers
`tereta/session`	Session management
`tereta/support`	Support pages
`tereta/theme`	Rendering, theme DI, SCSS build
`tereta/thread`	Threads/discussions
`tereta/utilities`	Misc helpers

Environment and Requirements

Required:

PHP 8.4+
Extensions: ctype, dom, iconv, mbstring, pdo, fileinfo, curl
Write access to var/

Optional:

Node.js + npm (theme build)
Docker Compose (local development environment)
MySQL or PostgreSQL (for DB)

Common issues:

Configuration file not found — create .config.php from .config.sample.php
DB connection error — check pdo.dsn and credentials in .config.php
Static files not loading with built-in server — run with -t pub exactly as shown above

Tests

Run all checks (PHPCS + PHPStan + PHPUnit):

composer test

Individually:

composer phpcs      # Code style (PSR-12)
composer phpstan    # Static analysis (level 7)
composer phpunit    # Unit tests

Tests are located in:

src/*/*/Tests
packages/*/src/Tests

Deploy and Production

(CI/CD)

CI/CD is configured via GitLab CI (.gitlab-ci.yml). The pipeline includes:

Test stage:

lint — code style check (PHPCS) and static analysis (PHPStan)
unit — theme build and PHPUnit execution

Deploy stage:

dev branch — automatic deploy to development environment
main branch — manual deploy to production

Deploy is performed via SSH. Required CI/CD variables:

SSH_PRIVATE_KEY — private key (file)
SSH_HOST, SSH_PORT, SSH_USER — connection parameters
SSH_DIRECTORY — project directory on the server

Local GitLab Runner

dev/docker/docker-compose.yml includes a gitlab-runner service for executing CI jobs locally. Registration is automated via a Composer script.

1. Set at minimum in dev/docker/.env:

GITLAB_RUNNER_TOKEN=glrt-xxxxxxxxxxxxxxxxxxxx

Optional variables (with defaults):

Variable	Default	Purpose
`GITLAB_URL`	`https://gitlab.com/`	GitLab instance URL
`GITLAB_RUNNER_NAME`	`local-docker-runner`	Runner name
`GITLAB_RUNNER_TAGS`	`local,docker`	Tags
`GITLAB_RUNNER_IMAGE`	`debian:trixie-slim`	Default image for jobs
`GITLAB_RUNNER_CONCURRENT`	`4`	Max concurrent jobs (global)
`GITLAB_RUNNER_LIMIT`	`4`	Job limit for this runner

2. Start the container and register:

composer docker:up              # bring up containers, including gitlab-runner
composer docler:runner:update   # register runner with GitLab

The script patches concurrent = N in /etc/gitlab-runner/config.toml and restarts the container.

Security: the container mounts /var/run/docker.sock — this grants full access to the host Docker daemon. Use only for local development.

Production checklist:

PHP 8.4+ on the server
composer install --no-dev for production
Theme built (composer theme:build)
var/ writable by the web server

Author and License

Author: Tereta Alexander
Website: tereta.dev
License: Apache License 2.0. See LICENSE.

 www.████████╗███████╗██████╗ ███████╗████████╗ █████╗
     ╚══██╔══╝██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔══██╗
        ██║   █████╗  ██████╔╝█████╗     ██║   ███████║
        ██║   ██╔══╝  ██╔══██╗██╔══╝     ██║   ██╔══██║
        ██║   ███████╗██║  ██║███████╗   ██║   ██║  ██║
        ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝
                                                      .dev