Download the PHP package alexkart/typed-registry-laravel without Composer

typed-registry-laravel

Laravel integration for typed-registry following Laravel best practices for environment variable and configuration access.

Why?

Laravel's env() and config() helpers return mixed values, making strict type checking difficult. This package provides:

• Type-safe config access - TypedConfig facade and typedConfig() helper with strict return types
• Type-safe env access - typedEnv() helper for use in config files only (following Laravel best practices)
• String-preserving env access - typedEnvString() helper for values that must stay strings (passwords, tokens)
• Intelligent casting - Environment variables automatically cast from strings ("8080" → 8080, "1e3" → 1000.0)
• PHPStan ready - Works seamlessly with static analysis at max level
• Zero runtime overhead - Simple wrappers around Laravel's existing systems

Installation

Requires:

• PHP 8.3+
• Laravel 11+ or 12+ or 13+

The package uses Laravel's auto-discovery feature. The service provider and facade are registered automatically.

Quick Start

Environment Variables in Config Files

Following Laravel Best Practices: Environment variables should ONLY be accessed in config files, never directly in controllers or services.

Configuration Access Everywhere

Use the TypedConfig facade or typedConfig() helper in controllers, services, and anywhere else:

Features

typedEnv() Helper - For Config Files Only

Wraps Illuminate\Support\Env with intelligent type casting for numeric strings:

Casting Rules:

• Numeric strings → int or float based on format (handles scientific notation, leading zeros, whitespace, overflow)
• Boolean strings ("true", "false") → bool (handled by Laravel's Env)
• Null strings ("null", "(null)") → null (handled by Laravel's Env)
• All other strings remain unchanged

typedEnvString() Helper - For String Values

Use this helper when you have environment variables that are semantically strings but may contain only digits (passwords, tokens, API keys):

Casting Rules:

• All scalar values (string, int, float, bool) → string
• Booleans: true → "1", false → "" (PHP's native casting)
• Null remains null

TypedConfig Facade - Use Anywhere

Wraps Laravel's Config facade with strict typing, no casting:

Or use the helper function:

Full API

All three helpers (typedEnv(), typedEnvString(), and TypedConfig) expose the same 20 methods from TypedRegistry:

Primitive Getters

Nullable Variants

With Defaults (Never Throws)

Lists (Sequential Arrays)

Maps (Associative Arrays with String Keys)

Type Casting Behavior

EnvProvider - Intelligent Casting

The EnvProvider (used by typedEnv()) intelligently casts numeric environment variable strings:

EnvStringProvider - Cast to String

The EnvStringProvider (used by typedEnvString()) casts all scalar values to strings:

ConfigProvider - No Casting

ConfigProvider performs zero type coercion. Values must be stored with the correct type:

Error Handling

Strict Getters Throw on Type Mismatch

Default Getters Never Throw

Real-World Example

PHPStan Integration

The package works seamlessly with PHPStan at max level:

Development

Quality Standards:

• PHPStan Level: Max (10) with strict rules
• Test Coverage: All providers and facades
• PHP Version: 8.3+
• Laravel Version: 11+, 12+, 13+

Comparison with Core Package

Contributing

Contributions are welcome! Please ensure:

1. All tests pass (vendor/bin/phpunit)
2. PHPStan Level 10 passes (vendor/bin/phpstan analyse)
3. Code follows existing style (strict types, final classes)

License

MIT License. See LICENSE for details.

Credits

• Built on alexkart/typed-registry
• Maintained by the TypedRegistry contributors

Questions? Open an issue on GitHub.