What is php-standard-library/foundation used for in Laravel?

php-standard-library/foundation provides lightweight PHP building blocks: exceptions, Ref immutable references, and invariant functions. Laravel teams can use it in domain layers for DDD-style value objects, domain exceptions, and runtime assertions without pulling in a full framework component. It is framework-agnostic, so it supplements rather than replaces Laravel's built-ins.

How do I install php-standard-library/foundation in a Laravel project?

Install it with Composer using composer require php-standard-library/foundation. Because the package is framework-agnostic, there is no Laravel service provider to register in the provided context; import its classes directly. Check the repository for the exact version constraint and PHP requirement before adding it to composer.json.

Does php-standard-library/foundation support Laravel 10 and Laravel 11?

The package is not Laravel-specific, so its Laravel compatibility is determined by its PHP version constraints and your app's PHP version. Laravel 10 and 11 require modern PHP versions, so verify the package's composer.json and run your test suite before adopting it. The provided context does not list explicit Laravel 10 or 11 support, so treat it as framework-agnostic rather than guaranteed.

How does Ref work and when should I use it in Laravel domain code?

Ref is an immutable reference wrapper intended to make values such as entity IDs or value objects harder to mutate accidentally. In Laravel domain code, use it where you want explicit immutable contracts instead of relying on convention. Keep it in domain layers and avoid wrapping framework objects that already have established identity semantics.

What are invariant functions and how do they help validation?

invariant functions are runtime assertions that enforce conditions and fail fast when a domain rule is broken. They are useful in constructors, value objects, and domain services to document and enforce preconditions. Because they are lightweight primitives, they add little production overhead while catching invalid states during development and testing.

Can I use php-standard-library/foundation exceptions with Laravel's exception handler?

Yes, you can map package or domain exceptions to HTTP responses in Laravel's App\Exceptions\Handler or via renderable exceptions. Use the foundation exceptions for domain-specific failures and translate them at the boundary to ProblemDetails or your API error format. Avoid letting low-level domain exceptions leak directly to HTTP responses without mapping.

Is php-standard-library/foundation a replacement for Illuminate\Support or Laravel Validator?

No, it should complement Laravel's built-ins rather than replace Illuminate\Support or the Validator. Use Laravel's validation and support utilities for framework concerns, and use foundation primitives for domain-focused exceptions, immutable references, and invariant checks. Teams should scope adoption to domain or cross-cutting layers to avoid naming collisions.

How do I test code that uses Ref and invariant in Laravel with PHPUnit or Pest?

You can test Ref and invariant-based code with normal PHPUnit or Pest tests by constructing values and asserting expected exceptions or results. Because Ref is a simple immutable wrapper, no special Laravel container bindings are required in the provided context. If you introduce custom exception mapping, add feature tests that verify Laravel's handler returns the expected HTTP response.

Is php-standard-library/foundation safe for production and is it maintained?

The primitives are lightweight and can be used in production, but the package has low visible adoption and no clear maintainer in the assessment. Treat it as a dependency risk: pin versions, review the code, and consider forking critical pieces such as Ref and invariant if long-term stability matters. Run integration tests against your Laravel version before relying on it in critical paths.

What are alternatives to php-standard-library/foundation for DDD value objects and domain exceptions in Laravel?

Alternatives include Laravel's own Illuminate\Support classes and Validator for framework-level needs, plus small in-house value object and domain exception base classes. For DDD patterns, teams often use established libraries or internal shared packages for Result types, IDs, and exception hierarchies. Compare maintenance, PHP version support, and whether you need framework-agnostic primitives before choosing.

Foundation Laravel Package

php-standard-library/foundation

Foundation provides the core building blocks for PHP Standard Library packages: a consistent exception hierarchy, the Ref reference wrapper for safe value passing, and invariant functions for validating preconditions and enforcing assumptions. Lightweight, dependency-free, and designed for reuse acr...

PHP Standard Library - Foundation provides the essential building blocks for the PHP Standard Library ecosystem: a robust set of exceptions, a lightweight Ref abstraction for mutable references, and a collection of invariant functions that enforce preconditions and validate state at runtime. Rather than duplicating logic across packages, Foundation centralizes these primitives so every component shares consistent error handling and validation behavior.

Designed as a dependency-light base layer, it integrates seamlessly with the rest of the standard library while remaining useful on its own in any modern PHP project.

Exception hierarchy with clear, typed error classes for consistent failure handling
Ref object for passing and mutating values by reference in a type-safe way
Invariant functions to assert preconditions and catch invalid state early
Zero-configuration adoption with straightforward, intuitive APIs
PSR-compatible and framework-agnostic for use in any PHP codebase