Download the PHP package citomni/http without Composer

CitOmni HTTP

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 routing with exact + placeholder/"regex" routes
• Deep, read-only config -> $this->app->cfg->http->base_url
• Service maps (no scanning) -> $this->app->{id} resolves instantly (cacheable)
• Prod-friendly -> optional compiled caches in /var/cache/*.php (atomic writes)
• HTTP ErrorHandler (optional, auto-installed if present in package)
• Maintenance 503 with Retry-After and allow-list
• Security foundations -> CSRF token helper, cookie/session CSP/Samesite defaults
• Webhook HMAC (WebhooksAuth) with TTL, clock skew tolerance, nonce/replay protection
• ♻️ Green by design - lower memory use and CPU cycles -> less server load, more requests per watt, better scalability, smaller carbon footprint.

Green by design

CitOmni's "Green by design" claim is empirically validated at the framework level.

The core runtime achieves near-floor CPU and memory costs per request on commodity shared infrastructure, sustaining hundreds of RPS per worker with extremely low footprint.

See the full test report here: CitOmni Docs → /reports/2025-10-02-capacity-and-green-by-design.md

Requirements

• PHP 8.2 or newer
• Recommended extensions: ext-json (required), mbstring (recommended)
  Optional CitOmni packages: citomni/infrastructure, citomni/auth, citomni/testing
• OPcache strongly recommended in production

Install

Your app's composer.json must PSR-4 map your code:

Then:

Quick start

/public/index.php (minimal front controller):

Folder layout (app):

Configuration (last wins)

Vendor HTTP baseline lives in \CitOmni\Http\Boot\Config::CFG. At runtime, the app builds config as:

1. Vendor HTTP baseline
2. Provider CFGs (if any; listed in /config/providers.php)
3. App base cfg /config/citomni_http_cfg.php
4. App env overlay /config/citomni_http_cfg.{env}.php (optional)

Merge rules:

• Associative arrays -> merged per key, last wins
• Numeric lists -> replaced by the last source
• Empty values ('', false, 0, null, []) are valid overrides and still win

Deep access via read-only wrapper:

Example /config/citomni_http_cfg.php

Per-env overlays (optional)

/config/citomni_http_cfg.stage.php

/config/citomni_http_cfg.prod.php

Base URL policy

• dev: Kernel auto-detects when http.base_url=''
• stage/prod: no auto-detect -> require an absolute URL in cfg or define CITOMNI_PUBLIC_ROOT_URL
• Kernel defines CITOMNI_PUBLIC_ROOT_URL (no trailing slash)

Reverse proxy & base URL

If you run behind Nginx/Apache/Cloudflare, configure http.trust_proxy and http.trusted_proxies correctly. Only include trusted proxy IPs/CIDR blocks.

Config:

Nginx (example):

If you publish under a sub-path (e.g. https://example.com/app), make sure your base_url includes that path, or set CITOMNI_PUBLIC_ROOT_URL accordingly. The router handles base-prefix stripping correctly either way.

Routes

Keep routes inline under cfg['routes'] or load them from a separate PHP file.

Placeholders available:

• {id} -> [0-9]+
• {email} -> [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+
• {slug} -> [a-zA-Z0-9-_]+
• {code} -> [a-zA-Z0-9]+ Unknown placeholders fall back to [^/]+.

Custom error pages

Override 403/404/405/500 in cfg['routes']:

Template variables provided to errorPage:

• status_code (int)
• errors (array|null, only filled for 500 when ErrorHandler has entries)

Controllers

• Framework controllers: CitOmni\Http\Controller\*
• App controllers: App\Http\Controller\* The router instantiates controllers and injects the App and view hints:

Healthcheck

A minimal route for load balancers/uptime checks:

Templating with View (helpers & examples)

View renders LiteView templates from either your app (/templates) or a vendor "layer" like citomni/auth. It also exposes a small set of globals and closures you can call directly in templates.

Controller -> render (passes 3 vars)

Corresponding template snippet (public/home.html)

Using Template helpers (LiteView syntax)

LiteView syntax: {{ ... }} prints escaped, {{{ ... }}} prints raw. Control structures use {% ... %} and comments use {# ... #}. Find more examples in the documentation inside the View-service.

Globals & closures available in templates

• app_name (string)
• base_url (string) - from http.base_url (or auto-detected in dev)
• public_root_url (string) - CITOMNI_PUBLIC_ROOT_URL if defined, else base_url
• language (string), charset (string)
• marketing_scripts (string), view_vars (array)
• csrf_protection, honeypot_protection, form_action_switching, captcha_protection (bool flags)
• env (array) -> ['name' => 'dev|stage|prod', 'dev' => bool]

Closures:

• $txt(string $key, string $file, ?string $layer = null, string $default = '', array $vars = []): string Requires a registered txt service (commonly from citomni/infrastructure).
• $url(string $path = '', array $query = []): string Joins base_url + normalized path + optional query.
• $asset(string $path, ?string $version = null): string Absolute if path is already a URL; otherwise base_url + path, with ?v=... appended if version or view.asset_version is set (preserves existing query).
• $hasService(string $id): bool - service id in the map?
• $hasPackage(string $slug): bool - vendor/package detected via services/routes?
• $csrfField(): string - hidden CSRF <input> (empty string if disabled/not available).
• $currentPath(): string - request path (lazy; resolves only if called).
• $role(string $fn, mixed ...$args) - role checks/labels (if role gate is present) Examples: $role('is','admin'), $role('any','manager','operator'), $role('label').

Notes & tips

• Base URL: set an absolute http.base_url for stage/prod; dev can auto-detect.
• Canonical links: prefer public_root_url when constructing canonicals or sitemaps.
• Vendor layers: pass template_layer (e.g. citomni/http) and template_file via routes, or call render('...', 'vendor/package') directly.
• i18n: if you don't use i18n, you can ignore $txt; if you do, ensure the txt service is registered (typically via a provider).

Services

Baseline map shipped by this package:

Extend/override in /config/services.php:

Use anywhere:

Note: log, mailer, and connection are provided by citomni/infrastructure and are not part of the HTTP baseline. This package only references them when present.

Request / Response quick notes

Request

• Proxy awareness: http.trust_proxy + http.trusted_proxies
• baseUrl(), fullUrl(), host(), port(), ip() (with CIDR trust list)
• json() (auto content-type guard; +json supported)

Response

• json()/jsonStatus()/jsonProblem() (never return; sends headers+exits)
• memberHeaders() / adminHeaders() set sane security headers
• download($path, $name) with X-Content-Type-Options: nosniff

Session / Cookie

• Deterministic INI init (secure defaults), Samesite/secure logic
• Flash storage (flash(), pull(), reflash())

View

• Renders via LiteView; exposes helpers: url(), asset(), csrfField(), etc.

Security

• CSRF token helpers (csrfToken(), verifyCsrf(), csrfHiddenInput())

Nonce

• File-backed nonce ledger; atomic create; TTL-based purge; replay protection

Maintenance

• 503 guard with Retry-After, allow-list, flag backup + pruning

WebhooksAuth

• HMAC verify with TTL + clock skew tolerance, optional context binding, IP allow-list, nonce replay protection.
• Example (strict mode):

Client signing example (PHP)

If you enable bind_context, the client must build the canonical string exactly as documented (METHOD, PATH, QUERY, sha256(body) on separate lines).

CSRF example (controller + view)

Controller (POST handler):

Form (LiteView template):

Providers (optional)

Providers export their own config/services and are explicitly whitelisted:

/config/providers.php

Providers merge between vendor baseline and app overrides (last wins).

Error handling

If present, Kernel installs \CitOmni\Http\Exception\ErrorHandler using config under cfg['error_handler'] (not runtime args). It supports:

• JSON-lines log file (with rotation by size)
• Friendly details in dev; safe minimal output in prod
• Optional mail notification via error_log() (recipient/sender)

Maintenance mode

Flag file (app-owned): /var/flags/maintenance.php returns:

HTTP will emit 503 with Retry-After; allow-listed IPs bypass maintenance.

Compiled caches (optional, recommended for prod)

Pre-merge and cache:

• /var/cache/cfg.http.php -> merged cfg
• /var/cache/services.http.php -> final service map

Warm from code:

Writes are atomic (tmp + rename), with best-effort OPcache invalidation.

Security checklist

• [ ] Prod: Set absolute http.base_url or CITOMNI_PUBLIC_ROOT_URL
• [ ] Cookies: Use SameSite=None only with Secure=true
• [ ] HTTPS: Enable HSTS (adminHeaders() sets it automatically when HTTPS)
• [ ] Proxy: Set http.trust_proxy=true + correct trusted_proxies
• [ ] CSRF: Enable and verify tokens on state-changing routes
• [ ] Maintenance: Protect with allow-list; enable backup policy
• [ ] Webhooks: Configure webhooks.secret, nonce_dir, and reasonable ttl_seconds
• [ ] Error output: display_errors=false in prod; use ErrorHandler logging
• [ ] Sessions: Consider rotate_interval for fixation resistance

Performance tips

• Composer

  Then: composer dump-autoload -o

• OPcache (prod)

• Keep vendor HTTP baseline lean. Put optional integrations in providers.

Dev utilities

• Add ?_perf=1 to any URL in dev to print execution time, memory, and included files as HTML comments.
• App::memoryMarker($label, $asHeader=false) prints a compact perf line (dev only).

Backwards compatibility

• Kernel defines CITOMNI_PUBLIC_ROOT_URL (no trailing slash).
• You may keep defining CITOMNI_APP_PATH and CITOMNI_PUBLIC_PATH in index.php.
• Old route entries using FQCN strings still work; prefer ::class for IDE/rename safety.

FAQ

Q: Should I auto-detect base URL in prod? A: No. Dev -> auto-detect; stage/prod -> set absolute URL in citomni_http_cfg.{env}.php or define CITOMNI_PUBLIC_ROOT_URL.

Q: Can I add per-service options? A: Yes. All services accept __construct(App $app, array $options = []). Put options in /config/services.php.

Q: Where do role/text helpers come from? A: View exposes helpers that call services if present (role, txt). If those services aren't installed, the helpers gracefully fallback.

Troubleshooting

"Base URL is wrong behind proxy" Set http.trust_proxy=true, fill trusted_proxies, and ensure your proxy sets X-Forwarded-* headers.

"Headers already sent" Don't echo/var_dump before using Response methods. See response_errors.json (requires a log service).

"CSRF fails on POST" Ensure the hidden input <input name="csrf_token"> exists and matches security.csrf_field_name.

"Nonce storage failed" webhooks.nonce_dir (or var/nonces) must exist and be writable by the PHP process.

Contributing

• Code style: PHP 8.2+, PSR-4, tabs, K&R braces.
• Keep vendor files side-effect free (OPcache-friendly).
• Don't swallow exceptions in core; let the global error handler log.

Coding & Documentation Conventions

All CitOmni projects follow the shared conventions documented here: CitOmni Coding & Documentation Conventions

License

CitOmni HTTP is open-source under the MIT License.
See: LICENSE.

Trademark notice: "CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen.
You may not use the CitOmni name or logo to imply endorsement or affiliation without prior written permission.
For details, see the project NOTICE.

Trademarks

"CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen.
You may make factual references to "CitOmni", but do not modify the marks, create confusingly similar logos,
or imply sponsorship, endorsement, or affiliation without prior written permission.
Do not register or use "citomni" (or confusingly similar terms) in company names, domains, social handles, or top-level vendor/package names.
For details, see the project's NOTICE.

Author

Developed by Lars Grove Mortensen © 2012-present Contributions and pull requests are welcome!

Built with ❤️ on the CitOmni philosophy: low overhead, high performance, and ready for anything.