# Use of @psalm-types in @param

**URL:** <https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908>\
**Category:** Contributors\
**Created:** [April 30, 2025, 3:47am UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908 "2025-04-30T03:47:25Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![Paul\_McGarry](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/paul_mcgarry/32/1655_2.png) [@Paul\_McGarry](https://discourse.laminas.dev/u/Paul_McGarry)\
**Post date:** [April 30, 2025, 3:47am UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/1 "2025-04-30T03:47:25Z")

</div>

Hi there,

I am finding code like:

> <https://github.com/laminas/laminas-validator/blob/3.3.x/src/Callback.php>

```auto
/**
 * @psalm-type OptionsArgument = array{
 * callback: callable(mixed, array<string, mixed>, mixed...): bool,
 * callbackOptions?: array<array-key, mixed>,
 * bind?: bool,
 * throwExceptions?: bool,
 * messages?: array<string, string>,
 * translator?: TranslatorInterface|null,
 * translatorTextDomain?: string|null,
 * translatorEnabled?: bool,
 * valueObscured?: bool,
 * }
 */
final class Callback extends AbstractValidator
{
....
    /** @param OptionsArgument|callable $options */
    public function __construct(array|callable $options)

```

difficult to use because tools that don’t understand `@psalm-type` see the OptionsArgument on the `@param` an unknown class/type and raise static analysis errors.

It seems non-ideal for a library to be exposing PHP doc that isn’t widely understood as it makes the library more difficult to use properly. (Obviously there is some vagueness here, as any tool could not understand some “common” PHPDoc structures, but “Tool B” not understanding PHPdoc tags specifically created by “Tool A” seems reasonable.)

I think there are probably two options that would ease my pain:

1. Remove `@psalm-type` and just use more “common” array shape PHP Doc where that is viable.

and/or

1. Make sure any `@param/@var` don’t include any `@psalm-type` defined types and pair a more generic `@param` with `@psalm-param` including the psalm-type where there is value to be obtained for that extra info

My feeling is that (1) would be better generally as it would expose the array shape to more tools more generically, but perhaps there may be places where psalm specific support is useful and (2) ,might be more useful.

I’m happy to submit some PRs, but would appreciate some guidance as to what would be preferred.

---

<div class="post-metadata">

**Author:** ![froschdesign](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/froschdesign/32/38_2.png) [@froschdesign](https://discourse.laminas.dev/u/froschdesign)\
**Post date:** [April 30, 2025, 9:20am UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/2 "2025-04-30T09:20:29Z")

</div>

> [@Paul\_McGarry](#):
>
> …and pair a more generic `@param`…

And this is the problem “generic”, it does not help during static analysis and development on user side.

> [@Paul\_McGarry](#):
>
> It seems non-ideal for a library to be exposing PHP doc that isn’t widely understood as it makes the library more difficult to use properly.

I would say Psalm is widely used. 😃  
Also in IDEs, e.g.:

> **[PHP type checking | PhpStorm](https://www.jetbrains.com/help/phpstorm/php-type-checking.html#psalm-annotations)**
>
> PhpStorm is a static code analysis tool that enforces type safety in PHP and enables support for generics in PHP.

> [@Paul\_McGarry](#):
>
> It seems non-ideal…

It is indeed not ideal, because it would be better to avoid arrays as a configuration in this place. A cleanly defined constructor should be the goal. But with laminas-filter and laminas-validator we are in a dilemma because laminas-inputfilter based on these components. And a complete change would have been too big a break - in the components and on the user’s side.

> [@Paul\_McGarry](#):
>
> I’m happy to submit some PRs, but would appreciate some guidance as to what would be preferred.

Send a pull request that updates the `Callback` validator and the checks on GitHub will show us if it works. We are happy to review it.  
Thanks in advance! 👍

---

<div class="post-metadata">

**Author:** ![froschdesign](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/froschdesign/32/38_2.png) [@froschdesign](https://discourse.laminas.dev/u/froschdesign)\
**Post date:** [April 30, 2025, 9:45am UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/3 "2025-04-30T09:45:06Z")

</div>

> [@froschdesign](#):
>
> A cleanly defined constructor should be the goal.

An example can be find in the next major version of laminas-view:

> <https://github.com/laminas/laminas-view/blob/5080b88aff7f275e26ebe7ba2799467a6f568457/src/Helper/HeadTitle.php#L32-L50>

---

<div class="post-metadata">

**Author:** ![Paul\_McGarry](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/paul_mcgarry/32/1655_2.png) [@Paul\_McGarry](https://discourse.laminas.dev/u/Paul_McGarry)\
**Post date:** [April 30, 2025, 12:32pm UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/4 "2025-04-30T12:32:26Z")

</div>

> [@froschdesign](#):
>
> I would say Psalm is widely used

Sorry, I didn’t mean that Psalm isn’t itself widely used.

I just happen to be looking at a project that uses Phan (and PHPStan), and Phan doesn’t understand the psalm-type.

I have created PR #415 against the latest 2.x branch as I am working towards that at the moment (need to work through the deprecations in that before looking at switching to 3)

Assuming it’s an acceptable change I’ll create a similar one for the 3.x branch for consistency (probably only for the constructor, no point on the property as it’s a final class in v3)

---

<div class="post-metadata">

**Author:** ![Paul\_McGarry](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/paul_mcgarry/32/1655_2.png) [@Paul\_McGarry](https://discourse.laminas.dev/u/Paul_McGarry)\
**Post date:** [April 30, 2025, 2:48pm UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/5 "2025-04-30T14:48:06Z")

</div>

Oh well, thanks for taking the time to look at it and loop people in.  
Not the result I’d have preferred but them’s the breaks…

---

<div class="post-metadata">

**Author:** ![froschdesign](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.laminas.dev/froschdesign/32/38_2.png) [@froschdesign](https://discourse.laminas.dev/u/froschdesign)\
**Post date:** [April 30, 2025, 4:05pm UTC](https://discourse.laminas.dev/t/use-of-psalm-types-in-param/3908/6 "2025-04-30T16:05:10Z")

</div>

I am sorry, I would have liked to help you, but there are decisions to be made somewhere.  
Yes, sometimes it is hard, but that is the way it is with open source.  
But please do not be discouraged, because the two pull requests were exactly right. This is a basis for discussion and shows interest. Your objection will definitely be taken into consideration – beside the current dilemma.  
We are grateful for any help, even if it is only criticism. 👍