Skip to content

Releases: citomni/http

Initial stable release

29 Sep 18:48
@LarsGMortensen LarsGMortensen
v1.0.0
0a86c38

Choose a tag to compare

View all tags
Initial stable release Latest
Latest

CitOmni HTTP v1.0.0 - Initial stable release

Slim, deterministic HTTP delivery for CitOmni apps.
Zero "magic", PSR-4 all the way, PHP 8.2+, tiny boot, predictable overrides.

Highlights

  • Deterministic boot -> vendor baseline -> providers -> app (last wins)
  • Lean router (exact + placeholder/"regex" routes) with 405/404 handling
  • Deep, read-only config ($this->app->cfg->...) with per-env overlays
  • Service map (no directory scanning): instant resolution via $this->app->{id}
  • Optional compiled caches in /var/cache/*.php (atomic writes + OPcache invalidate)
  • HTTP ErrorHandler (JSON-line log, friendly dev output, failsafe prod page)
  • Maintenance mode: 503 guard, Retry-After, allow-list, flag backups/pruning
  • Security foundations: CSRF helper, sane cookie/session defaults, CSP presets
  • Webhook HMAC (WebhooksAuth): TTL, clock-skew tolerance, nonce/replay protection
  • Template engine service (LiteView) with helpful template globals/closures (url, asset, csrfField, ...)

What's included

  • Kernel::run() - boots the app, resolves paths, installs ErrorHandler, and enforces base-URL policy

  • Services (baseline map):

    • request, response, router, session, cookie, view, security, maintenance, nonce, webhooksAuth

  • Controllers

    • PublicController with index() and errorPage()

  • Error handling

    • \CitOmni\Http\Exception\ErrorHandler (size-based log rotation, optional mail notify)

  • Templating

    • LiteView integration; app or vendor template layers

  • Utilities

    • ?_perf=1 dev hook: execution time, memory, included files (as HTML comments)

Requirements

  • PHP 8.2+
  • OPcache strongly recommended in production
  • Recommended extensions: ext-json (required), mbstring (recommended)

Install

composer require citomni/http

Minimal /public/index.php:

<?php
declare(strict_types=1);

define('CITOMNI_START_TIME', microtime(true));
define('CITOMNI_ENVIRONMENT', 'dev');            // 'dev' | 'stage' | 'prod'
define('CITOMNI_PUBLIC_PATH', __DIR__);
define('CITOMNI_APP_PATH', \dirname(__DIR__));

// In stage/prod, prefer an absolute public root URL or set http.base_url in cfg:
if (\defined('CITOMNI_ENVIRONMENT') && \CITOMNI_ENVIRONMENT !== 'dev') {
	define('CITOMNI_PUBLIC_ROOT_URL', 'https://www.example.com');
}

require __DIR__ . '/../vendor/autoload.php';

\CitOmni\Http\Kernel::run(__DIR__);

Configuration overview

  • Vendor baseline: \CitOmni\Http\Boot\Config::CFG

  • App builds config in this order (last wins):

    1. vendor baseline -> 2) provider CFGs -> 3) /config/citomni_http_cfg.php ->
    2. /config/citomni_http_cfg.{env}.php (optional)

Base URL policy

  • dev: http.base_url may be empty -> auto-detect
  • stage/prod: set an absolute http.base_url or define CITOMNI_PUBLIC_ROOT_URL (no trailing slash)

Reverse proxy

  • Set http.trust_proxy=true and fill http.trusted_proxies (IPs/CIDR).
  • Router and Request respect X-Forwarded-* when the client IP is trusted.

Security

  • CSRF: Security service provides csrfToken(), verifyCsrf(), csrfHiddenInput()
  • Cookies/Sessions: secure defaults; SameSite=None requires Secure=true (enforced)
  • Response headers: memberHeaders() and adminHeaders() set CSP, XFO, HSTS (on HTTPS)
  • WebhooksAuth: HMAC over canonical base, clock-skew tolerant TTL, nonce ledger (file-backed), optional method/path/query/body binding (bind_context)

Maintenance mode

  • App-owned flag file: /var/flags/maintenance.php

    return ['enabled' => true, 'allowed_ips' => ['1.2.3.4'], 'retry_after' => 600];

  • 503 guard with Retry-After, allow-list bypass, optional backups & pruning.

Compiled caches (production)

  • /var/cache/cfg.http.php (merged cfg)

  • /var/cache/services.http.php (final service map)

  • Warm programmatically:

    $this->app->warmCache(overwrite: true, opcacheInvalidate: true);

Known limitations / notes

  • Router placeholders: {id}, {email}, {slug}, {code}; unknown placeholders default to [^/]+.
  • IP allow-lists in WebhooksAuth support exact IPv4 and IPv4 CIDR today (IPv6 can be added later).
  • View::$txt(...) helper requires a text/i18n service (commonly from a provider); otherwise it returns the provided default.

Upgrade & compatibility

  • This is the first stable release for citomni/http.

  • No prior migration steps required.

  • Back-compat helpers:

    • Kernel defines CITOMNI_PUBLIC_ROOT_URL
    • You may still define CITOMNI_APP_PATH / CITOMNI_PUBLIC_PATH in index.php.

Links

Thanks

Huge thanks to early adopters and contributors for feedback on determinism, error handling, and maintenance ergonomics. Keep the issues and PRs coming!

Assets 2
Loading