README

CAREMINATE is a modular, contract-first PHP framework intended for web applications, APIs, command-line applications, asynchronous workers, SaaS platforms, and optional distributed-runtime integrations.

Project status

CAREMINATE is in pre-alpha development.

Phase 1 engineering implementation is complete.

Operational acceptance requires the repository's Phase 1 acceptance workflow to pass on the protected main branch.

The current package provides:

Repository and Composer boundaries
PSR-4 namespace ownership
PHPUnit 13 test infrastructure
PHPStan 2.2 level 10 analysis
Strict and deprecation-aware static analysis
PHP_CodeSniffer 4 coding standards
Rector 2.5 dry-run verification
A catchable framework exception boundary
Categorized path-validation exceptions
Immutable semantic framework version metadata
Cross-platform lexical path normalization
POSIX path support
Windows drive-path support
Windows UNC path support
Lexical path containment validation
Runtime-environment contracts
PHP version validation
Required PHP-extension validation
Immutable runtime diagnostic results
Deterministic runtime check reports
A Windows-compatible CLI requirement checker
A fail-closed initial front controller
PHP 8.4 and PHP 8.5 CI coverage
Ubuntu 24.04 and Windows 2025 CI coverage
Immutable GitHub Action references
Workflow syntax and policy validation
Locked dependency auditing
Advisory, malware, and abandoned-package policies
Full-history secret scanning
Checksum-verified security tooling
Reproducible production dependency-installation checks
Automated Composer and GitHub Actions update proposals
A private vulnerability-reporting policy
A single Phase 1 branch-protection acceptance gate

The package does not yet provide:

An application container
An application kernel
Service providers
Environment-file loading
Configuration loading
HTTP request or response abstractions
Routing
Filesystem adapters
Production application bootstrapping

Design goals

CAREMINATE is being designed around:

Explicit lifecycle behavior
Stable public contracts
Constructor dependency injection
Controlled module contributions
Safe module disabling
Secure defaults
Deterministic diagnostics
Static-analysis compatibility
Windows and Linux portability
Short-lived and long-running PHP runtimes
Backward compatibility within a major release

Requirements

Production requirements:

PHP 8.4 or later
PHP extension: Ctype
PHP extension: Filter
PHP extension: JSON
PHP extension: Mbstring
PHP extension: OpenSSL

Development and CI requirements:

Composer 2.10.2 or later within the Composer 2 major release
Git
Required PHPUnit PHP extensions
Gitleaks 8.30.0 for the complete local Phase 1 gate

Database, cURL, Intl, image-processing, queue, and other adapter-specific extensions are not global framework requirements. They will be validated by the subsystems that require them.

Supported CI matrix

Operating system	PHP 8.4	PHP 8.5
Ubuntu 24.04	Required	Required
Windows 2025	Required	Required

Every matrix entry runs:

Composer validation
Locked dependency installation
Platform requirement verification
Runtime requirement validation
PHPUnit
PHPStan level 10
PHP_CodeSniffer
Rector dry-run verification
Dependency metadata cleanliness verification

Additional Linux jobs run:

Composer dependency auditing
Full-history Gitleaks scanning
GitHub Actions workflow validation
Immutable action-reference validation
Reproducible dependency-installation comparison

The final required status is:

Phase 1 Acceptance / Phase 1 acceptance gate

Checking runtime requirements

From the repository root:

composer runtime:check

Run the checker directly on Windows with XAMPP:

C:\xampp\php\php.exe framework\bin\check-requirements

Run it directly on POSIX:

php framework/bin/check-requirements

The checker returns:

Exit code 0 when all requirements are satisfied
Exit code 1 when one or more requirements fail
Exit code 2 when the checker cannot start or encounters an internal error

The output does not use ANSI colors, terminal-width detection, timestamps, or locale-dependent formatting. It is deterministic and suitable for CI logs.

Initial front controller

The initial web entry point is:

public/index.php

It currently performs:

A pre-autoload PHP version check
Composer autoloader discovery
Standard runtime requirement validation
Safe server-side diagnostic logging
Generic HTTP failure rendering
A temporary runtime-ready response

When successful, the temporary response is:

CAREMINATE runtime is ready.

The response will be replaced by application bootstrap and HTTP-kernel dispatch when those subsystems are introduced.

Detailed runtime diagnostics are never returned to HTTP clients.

Namespace

Framework source uses:

Careminate\

Composer maps the namespace to:

framework/src/

Framework tests use:

Careminate\Tests\

Composer maps the test namespace to:

framework/tests/

Foundation primitives

Framework exception boundary

Framework-originated exceptions implement:

Careminate\Foundation\Exception\FrameworkExceptionInterface

A caller may catch the framework boundary:

use Careminate\Foundation\Exception\FrameworkExceptionInterface;

try {
    // Framework operation
} catch (FrameworkExceptionInterface $exception) {
    // Central framework failure handling
}

Specific exceptions continue to extend appropriate native PHP exception categories.

For example, InvalidPathException and InvalidRuntimeRequirementException extend InvalidArgumentException.

Framework version

Read the current framework version:

use Careminate\Foundation\FrameworkVersion;

$version = FrameworkVersion::current();

echo (string) $version;
echo $version->userAgent();

Current output:

0.1.0-dev
Careminate/0.1.0-dev

Path abstraction

Normalize a path:

use Careminate\Foundation\Path;

$root = Path::from('C:\xampp\htdocs\caremi');

echo $root;

Output:

C:/xampp/htdocs/caremi

Append relative path segments:

$log = $root->append('storage', 'logs', 'framework.log');

Resolve a path that must remain lexically contained:

$cache = $root->resolveWithin(
    'storage/cache',
    'framework.cache',
);

Path is a lexical value object.

It does not:

Access the filesystem
Resolve symbolic links
Verify existence
Verify readability or writability
Resolve mount points
Perform authorization checks

Runtime requirement API

Create the standard checker:

use Careminate\Foundation\Runtime\StandardRuntimeRequirements;

$report = StandardRuntimeRequirements::checker()->check();

if ($report->hasFailures()) {
    foreach ($report->failures() as $failure) {
        echo $failure->label();
        echo $failure->actual();
        echo $failure->resolution();
    }
}

Test custom runtime environments by implementing:

Careminate\Foundation\Runtime\RuntimeEnvironmentInterface

Add custom runtime requirements by implementing:

Careminate\Foundation\Runtime\RuntimeRequirementInterface

Requirement identifiers are stable machine-readable values such as:

php.version
php.extension.mbstring

Installing development dependencies

From the repository root:

composer install
composer --working-dir=framework install

Both committed lock files are authoritative for development and CI.

Do not run an unconstrained dependency update as part of normal CI execution.

Quality commands

Run the root quality gate:

composer quality

Run the root and isolated framework quality gates:

composer quality:all

Run the complete local Phase 1 acceptance gate:

composer phase1:acceptance

The complete local acceptance command requires Gitleaks 8.30.0 to be available on PATH.

Run individual checks:

composer quality:composer
composer runtime:check
composer test
composer analyse
composer style
composer refactor:dry
composer security:audit
composer security:audit:framework
composer security:secrets
composer build:verify
composer build:verify:framework

Apply coding-standard fixes:

composer format

Apply reviewed Rector transformations:

composer refactor

Generate coverage when PCOV or Xdebug is available:

composer test:coverage

Security policy

Security issues must not be reported through public issues or pull requests.

See the repository security policy:

SECURITY.md

The dependency policy fails when Composer identifies:

Active security advisories
Malware policy matches
Abandoned packages

No dependency-policy exception is permitted without:

A documented reason
A named owner
An expiration or review date
A compensating control
Explicit approval

Secret-scan findings must be handled as potential credential incidents.

Removing a secret from the newest commit is not sufficient. The secret must be revoked or rotated.

Reproducibility policy

The repository commits both dependency lock files.

CI installs production dependencies twice into isolated directories using:

The same PHP version
The same Composer version
The same lock file
Distribution archives
Disabled plugins
Disabled package scripts
Mirrored path repositories
Authoritative classmaps

The resulting file paths and SHA-256 content hashes must match.

This Phase 1 check validates dependency-tree content reproducibility. It does not yet claim that future packaged release archives will be byte-for-byte identical. Release artifact reproducibility will require a separate release process.

Quality policy

Runtime requirements must pass before tests and analysis run.
PHPUnit warnings, notices, deprecations, and risky tests fail the test run.
Tests must declare coverage intent or use CoversNothing.
PHPStan runs at level 10.
PHPStan suppressions require identifiers and explanations.
A PHPStan baseline must not be introduced without an accepted ADR.
PSR-12 and strict types are mandatory.
Rector runs in dry-run mode during the quality gate.
Automatic transformations require human review.
Composer manifests and lock files must validate strictly.
External GitHub Actions must be pinned to full commit SHAs.
CI workflows must not use pull_request_target.
Checkout credentials must not persist after checkout.
Normal CI jobs receive read-only repository permissions.
Dependencies must pass Composer policy auditing.
Repository history must pass secret scanning.
Production dependency installation must be reproducible.
The final Phase 1 gate must pass before merging to main.

Architecture documentation

General documentation: docs/
Architecture decisions: docs/decisions/
Architecture references: docs/architecture/
Engineering guides: docs/engineering/
Foundation guides: docs/foundation/
Runtime guides: docs/runtime/
Security guides: docs/security/

Current Phase 1 documentation:

docs/foundation/foundation-primitives.md
docs/runtime/runtime-requirements.md
docs/engineering/continuous-integration.md
docs/engineering/phase-1-acceptance.md
docs/security/security-baseline.md

Repository security settings

Repository administrators must enable:

Branch protection or repository rulesets for main
Required pull requests
Required Phase 1 acceptance status
Stale approval dismissal
Conversation resolution
Protected branch deletion prevention
Protected branch force-push prevention
Dependabot alerts
Dependabot security updates
Private vulnerability reporting
Secret scanning when available
Push protection when available

Workflow files cannot enforce repository-hosting settings by themselves.

Stability

Until a public contract is explicitly marked stable, all APIs remain subject to change.

Experimental APIs must not be represented as stable or standards-compliant.

License

The package is temporarily marked as proprietary pending an explicit licensing decision. MODIFIED FILE: framework/docs/README.md

CAREMINATE Documentation

This directory contains the authoritative technical documentation for the CAREMINATE Framework.

Documentation must describe implemented behavior only.

Structure

docs/
├── architecture/
│   └── Repository and architectural reference documents
├── decisions/
│   └── Architecture decision records
├── engineering/
│   └── Engineering processes, CI, quality, and acceptance gates
├── foundation/
│   └── Foundation primitives and low-level framework behavior
├── runtime/
│   └── Runtime requirements, diagnostics, and startup validation
└── security/
    └── Security controls, policies, threat boundaries, and operations

Additional documentation areas will be introduced only when corresponding features exist.

Planned documentation categories include:

Installation
Configuration
Contracts
Extension points
Performance
Testing
Troubleshooting
Upgrade guides
API references
Release engineering

Current architecture documentation

architecture/repository-structure.md

Current engineering documentation

engineering/quality-toolchain.md
engineering/continuous-integration.md
engineering/phase-1-acceptance.md

Current foundation documentation

foundation/foundation-primitives.md

Current runtime documentation

runtime/runtime-requirements.md

Current security documentation

security/security-baseline.md
Repository-level SECURITY.md

Current architecture decisions

decisions/0001-repository-and-package-boundaries.md
decisions/0002-quality-toolchain-and-gates.md
decisions/0003-foundation-primitives.md
decisions/0004-runtime-requirements-and-entry-points.md
decisions/0005-ci-security-and-reproducibility-baseline.md

Documentation rules

Every framework feature must document:

Its purpose
Its architecture
Its public contracts
Its configuration
Its normal behavior
Its failure behavior
Its security considerations
Its performance considerations
Its extension points
Its testing approach
Its upgrade implications

Do not document planned behavior as though it has already been implemented.

Security documentation rules

Security documentation must distinguish:

Enforced controls
Repository-hosting settings
Operator responsibilities
Application responsibilities
Known limitations
Planned controls

Never represent a CI check as proof that deployed applications are secure.

Architecture decisions

Significant architectural decisions must be recorded under decisions/.

See decisions/README.md for the required ADR structure and lifecycle.

caremillc / framework

Maintainers

Package info

Statistics

Security