php-type-safety

Unify runtime assertions and PHPDoc shapes for PHPStan and Psalm strict mode.

25|Updated Feb 22, 2026

Search Tags:#php #type-safety #phpstan #phpdoc #webmozart-assert #psalm #array-shapes

Ready to run

npx skills add https://github.com/peterfox/agent-skills --skill php-type-safety

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: php-type-safety
Source: https://github.com/peterfox/agent-skills/tree/main/php-type-safety
Command: npx skills add https://github.com/peterfox/agent-skills --skill php-type-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

PHP projects often struggle to maintain type safety across dynamic data boundaries. This skill provides a disciplined pattern: combine runtime assertions (Webmozart\Assert) with PHPDoc shapes to help PHPStan and Psalm understand and enforce types, reducing bugs and improving maintainability.

Core Features & Use Cases

Runtime assertions at entry/exit points to validate inputs and guard downstream operations.
PHPDoc shapes and type aliases to describe complex data structures (arrays, maps, lists) for static analysis.
Templates and generics support to create reusable, strongly-typed APIs across modules.

Quick Start

Annotate a function parameter with a PHPDoc shape and add a runtime assertion at the boundary.

Frequently Asked Questions about php-type-safety

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I enforce PHP type safety for complex arrays with PHPStan and Psalm?▼

Enforce PHP type safety by combining runtime assertions using webmozart/assert with PHPDoc shapes and type aliases. This unifies runtime validation and static analysis, allowing PHPStan and Psalm to correctly understand and enforce complex array structures in strict mode.

What is the best way to validate dynamic data boundaries in PHP?▼

The best way to validate dynamic data boundaries in PHP is applying runtime assertions at entry and exit points. Using webmozart/assert guards downstream operations, while PHPDoc templates and generics document intent to ensure type correctness across modules.

Why does PHPStan fail on complex array shapes and maps despite type hints?▼

PHPStan fails on complex array shapes because standard type hints lack detail for dynamic data. By adding PHPDoc array shapes, type aliases, and webmozart/assert runtime checks, you provide the strict metadata static analyzers need to validate types without guessing.

Do I need webmozart/assert to satisfy strict static analysis in PHP?▼

You need webmozart/assert to satisfy strict static analysis because it provides runtime validation at dynamic boundaries. Combining these runtime checks with PHPDoc annotations ensures both runtime safety and static analyzer compliance for complex data structures.

Can I use PHPDoc templates and generics to create strongly-typed PHP APIs?▼

Yes, you can use PHPDoc templates and generics to create strongly-typed PHP APIs. Documenting reusable APIs with PHPDoc type aliases and array shapes, alongside runtime assertions, ensures type correctness and clear intent across modules for static analysis.

When should I not use runtime assertions for PHP type checking?▼

Avoid using runtime assertions for PHP type checking in performance-critical loops where validation overhead is unnecessary. Instead, apply webmozart/assert strictly at entry and exit boundaries to guard downstream operations without impacting internal execution performance.