README

SlimApp is a reusable application layer for the Slim 4 PHP framework. It provides YAML configuration, validated service wiring, Twig integration, JSON helpers, session transports, authentication building blocks, logging, bounded outbound HTTP, cache, database, LDAP, mail, and client-network authorization.

The package supplies infrastructure rather than a complete identity or persistence policy. Applications remain responsible for choosing their writable data projections, authentication backend, authorization rules, secret storage, and production deployment boundary.

Requirements

PHP 8.2 or newer;
Composer for dependency installation;
the PHP YAML extension when configuration is loaded from conf/config.yaml;
the PHP cURL extension for the shared outbound HTTP client; and
a PSR-7 web-server integration supported by Slim.

Optional components require additional runtime support:

Component	Runtime dependency
Cache and `MemcachedSession`	PHP Memcached extension and a reachable Memcached server
`DatabaseService` with `mysqli`	PHP MySQLi extension and a reachable MySQL-compatible server
`LdapService`	PHP LDAP extension and a reachable LDAP/LDAPS server
SMTP mail	Reachable SMTP server; sendmail transport requires a working local sendmail command

Composer validates library dependencies and the PHP version. PHP extension availability remains a deployment responsibility: the standard YAML bootstrap and optional component extensions are not declared as unconditional package requirements.

Installation

Install SlimApp into a project:

composer require asu/slim-app

For repository development, install development dependencies instead:

composer install

The examples look for a project-local vendor/autoload.php first and this repository's dependency directory second. If the project uses a custom Composer vendor-dir, update the $autoload_paths list in the copied example's src/Application.php.

Choose an example

Example	Intended starting point
01 — basic website	Routing, configuration, controllers, and Twig templates
02 — JSON REST API	JSON parsing, schema validation, explicit projections, and API responses
03 — authentication	Password and TOTP login, throttling, server-side challenges, and sessions
04 — network policy	IP allow-listing, trusted reverse proxies, canonical URLs, and error boundaries

Each example README documents its purpose, routes, dependencies, security constraints, and run commands. The examples are illustrative and deliberately omit unrelated application policy.

Quick start

After installing asu/slim-app, copy example 01—including its hidden .htaccess file—to an empty project directory:

cp -a vendor/asu/slim-app/examples/01-simple/. .

The resulting project uses this layout:

PROJECT_DIR/
├── assets/                  # public styles used by the basic example
├── conf/
│   └── config.yaml          # application configuration
├── public/                  # the only web-server document root
│   ├── .htaccess
│   └── index.php
├── src/
│   ├── Controllers/
│   ├── views/
│   └── Application.php
└── vendor/                  # Composer dependencies

The minimal example configuration is:

application:
    debug: true

logging:
    name: my-application
    handlers: ['null']

Run the PHP development server from the project root:

php -S 127.0.0.1:8081 -t public

Then open http://127.0.0.1:8081/. The built-in server is for local development only.

Production web server

Publish only the public/ directory. Configuration, source, dependencies, logs, and secrets must remain outside the document root. A minimal Apache virtual-host fragment is:

<VirtualHost *:443>
    ServerName app.example.test
    DocumentRoot /var/www/app/public

    <Directory /var/www/app/public>
        Options -Indexes +FollowSymLinks
        AllowOverride FileInfo
        Require all granted
    </Directory>

    # Configure TLS certificates and the PHP handler for this deployment.
</VirtualHost>

The example .htaccess needs mod_rewrite and permission to use FileInfo overrides. Nginx, Apache reverse-proxy, and forwarded-client examples are documented in example 04. See Slim's web-server documentation for the framework routing boundary.

Documentation

Configuration: ConfigService, schemas, configuration lookup, and secret-handling requirements.
Application services: container names, logging, cache, database, LDAP, and mail contracts.
cURL service: bounded outbound HTTPS, form and JSON requests, DNS pinning, response semantics, and mutual TLS.
Sessions and transports: server-side and JWT sessions, cookies, Bearer transport, errors, and security boundaries.
Application runtime: construction, middleware order, the error boundary, and canonical absolute URLs.
Security contracts: implemented security requirements and remaining design decisions.
IP range middleware: direct clients, trusted proxies, forwarded address resolution, and login throttling.
JSON object projections: schema validation and explicit readable/writable properties.
Testing: test commands, suite structure, isolation, and PHP compatibility.

Database and LDAP services can support an application-defined authentication backend, but SlimApp does not select or provide a concrete database/LDAP login policy. Twig includes a small i18n helper; locale selection and translation catalog management remain application responsibilities. No CSS framework, including Bootstrap, is bundled by SlimApp.

Development

Run the complete test suite:

composer test

Focused unit and integration commands are described in testing. Before deploying or releasing, also run composer audit in an environment with Packagist access and review the application's own dependencies and infrastructure.

Production checklist

set application.debug: false;
configure the exact external application.base_url wherever absolute URLs are generated;
keep passwords, signing keys, and infrastructure credentials out of version control;
use HTTPS and reviewed cookie/session settings for authenticated applications;
expose Memcached and backend listeners only to the required private peers;
trust forwarding headers only from explicitly configured, owned proxies;
replace demonstration identities, no-op logging, and documentation-only networks; and
test authorization failures, external-service failures, and proxy behavior in the deployed environment.

License

SlimApp is released under the MIT license. See LICENSE.

asu / slim-app

Maintainers

Package info

Statistics

Security