PHPDoc - how show the options - php

Question

Imagine a function like this
function mytrim($str,$where)
{
if ($where=="left") return ltrim($str)
if ($where=="right") return rtrim($str)
}
Its very important to me show what is the options of the where in this functions (right or left)

Answer 1

The best way I found to do it is
/**
* #param string $str
* #param left|right $where
* #return mixed|string
*/
will show "where: \left|\right"
There is a better way to do it ?

Answer 2

Leaving aside that I don't think you should have this function in the first place, you could make use of type hints and return types to document the arguments instead of using PHPDoc:
<?php declare(strict_types=1);
function mytrim(string $str, string $where): ?string
{
if ($where=="left") return ltrim($str);
if ($where=="right") return rtrim($str);
}
Docs tend to get outdated fast while function signatures are always current.
Now you could argue that this will not tell you what you can provide for $where and you'd still need the PHPDoc to know how to ltrim and rtrim. You could utilize constants for that though, e.g.
<?php declare(strict_types=1);
const MYTRIM_LEFT = 'left';
const MYTRIM_RIGHT = 'right';
function mytrim(string $str, string $where): ?string
{
if ($where === MYTRIM_LEFT) return ltrim($str);
if ($where === MYTRIM_RIGHT) return rtrim($str);
}
You'd still need to know that these constants exist though. That's why I'd probably convert your mytrim to a Strings class and define the constants declarations in there by. And/Or you add a check into the function that throws an error if the $where isn't "left" or "right".
As of PHP 8.1 you could use enums to make it even more clear:
<?php declare(strict_types=1);
enum MyTrim {
case Left;
case Right;
}
function mytrim(string $str, MyTrim $where): ?string
{
if ($where === MyTrim::Left) return ltrim($str);
if ($where === MyTrim::Right) return rtrim($str);
}
echo mytrim(" test", MyTrim::Left); // prints "test"
Everything there is to know about how to use the code is now directly visible in the signature.
But coming back to my initial remark: you should not have this function in the first place. Since you need to specify whether it's a left or right trim, you don't win anything over directly using ltrim and rtrim in your code.