Production Readiness & Strategy

This document outlines the stability status of TypePHP, production deployment strategies, and recommended safety guidelines.

---

Pre-1.0 Stability Warning

Stability Warning: TypePHP is currently in active pre-1.0 development and has not yet reached its stable v1.0.0 release.

Do NOT use TypePHP in high-stakes, mission-critical production applications yet.

TypePHP is currently recommended for:

• Local development environments (require-dev)
• Pest / PHPUnit test suites
• CI/CD build pipelines
• Staging and QA testing servers
• Non-critical live applications and internal web tools

---

Selective Whitelisting Strategy

When deploying TypePHP to non-critical live applications or staging environments, use Selective Whitelisting in typephp.php rather than type-checking your entire codebase.

Instead of including all application directories, target only specific domain modules:

// typephp.php
return [
    'include' => [
        'app/Domain/Billing/**', // Whitelist specific domain logic
        'app/Services/Payment/**',
    ],

    'exclude' => [
        'vendor/**',
        'storage/**',
        'var/**',
        'cache/**',
    ],
];

Why Selective Whitelisting Works

1. Zero Overhead for Unincluded Code: Files not listed in include pass directly to PHP's native C-engine with zero AST parsing, zero transformation, and zero validation overhead.
2. Targeted Guard Rails: Your core domain services protect themselves against bad input data without adding execution overhead to simple GET endpoints or rendering logic.

---

Production Performance Optimization

When running TypePHP in live or staging environments, apply these three critical performance optimizations to ensure maximum throughput:

1. Disable File Modification Monitoring (Zero-I/O Mode)

By default, TypePHP checks file modification times (@filemtime) on every file inclusion to automatically rebuild the cache when a file changes. In production, code is immutable. Checking hundreds of timestamps per request degrades performance.

Set cache_check_mtime to false in typephp.php:

'cache' => true,
'cache_check_mtime' => false, // Eliminates disk I/O checks for maximum performance

When disabled, TypePHP generates a static hash based purely on the file path, loading the cached AST instantly from memory via PHP's OPCache.

2. Pre-Warm Cache During Deployment (cache:warm)

If you disable file modification monitoring (as recommended above), you must clear and rebuild the cache manually during your deployment pipeline before opening web traffic:

# In your CI/CD deployment script:
vendor/bin/typephp cache:rebuild

This pre-transforms all included PHP files on disk, ensuring the very first HTTP request receives instant $O(1)$ execution speed.

3. Disable Heavy Inline Variable Toggles

In live environments, you can disable local internal variable assignment checks while keeping strict function parameter and return boundaries active:

'params'  => true, // Keep public function parameter contracts ON
'returns' => true, // Keep public function return contracts ON

'inline_vars' => [
    'properties' => true,
    'generics'   => true,
    'callables'  => true,
    'scalars'    => false, // Turn off inline scalar checks for maximum loop speed
    'arrays'     => false, // Turn off inline array checks for maximum loop speed
    'objects'    => true,
],

---

Emergency Kill-Switches

If you ever need to disable TypePHP instantly in a live environment, you have two zero-downtime options:

1. Environment Variable Kill-Switch (TYPEPHP_DISABLE)

Set TYPEPHP_DISABLE=true in your server environment or .env file:

export TYPEPHP_DISABLE=true

This prevents StreamWrapper from registering during Composer autoloading.

2. Config Master Switch (enabled => false)

Set 'enabled' => false in typephp.php or dynamically at runtime:

TypePHP::setConfig(['enabled' => false]);

All runtime check methods immediately become instant no-ops and pass raw values through natively.

Key Difference Between Disabling Approaches:

• Environment Level (TYPEPHP_DISABLE=true): Evaluated during Composer autoloading (vendor/autoload.php). TypePHP never boots, and the StreamWrapper is never registered with PHP's Zend Engine.
• Config Level ('enabled' => false): TypePHP boots normally, but StreamWrapper and RuntimeTypeChecker act as an instant pass-through, bypassing all type checks during execution.