first published here: https://suckup.de/2020/08/generics-in-php-via-phpdocs/
If you did not know that you can use Generics in PHP or you do not exactly know how to use it or why you should use it, then the next examples are for you.
Type variables via @template
The @template tag allows classes and functions to declare a generic type parameter. The next examples starts with simple functions, so that we understand how it works, and then we will see the power of this in classes.
A dummy function that will return the input.
⇾ https://phpstan.org/r/1922279b-9786-4523-939d-dddcfd4ebb86
<?php
/**
* @param \Exception $param
* @return \Exception
*
* @template T of \Exception
* @psalm-param T $param
* @psalm-return T
*/
function foo($param) { ... }
foo(new \InvalidArgumentException()); // The static-analysis-tool knows that
// the type is still "\InvalidArgumentException"
// because of the type variable.
@template T of \Exception // here we create a new type variable, and we force that it must be an instance of \Exception
@phpstan-param T $param // here we say that the static-analysis-tool need to remember the type that this variable had before (you can use @psalm-* or @phpstan-* both works with both tools)
@phpstan-return T // and that the return type is the same as the input type
A simple function that gets the first element of an array or a fallback.
In the @param PHPDocs we write “mixed” because this function can handle different types. But this information is not very helpful if you want to understand programmatically what the code does, so we need to give the static-analysis-tools some more information.
⇾ https://phpstan.org/r/1900a2af-f5c1-4942-939c-409928a5ac4a
<?php
/**
* @param array<mixed> $array
* @param mixed $fallback <p>This fallback will be used, if the array is empty.</p>
*
* @return mixed|null
*
* @template TFirst
* @template TFirstFallback
* @psalm-param TFirst[] $array
* @psalm-param TFirstFallback $fallback
* @psalm-return TFirst|TFirstFallback
*/
function array_first(array $array, $fallback)
{
$key_first = array_key_first($array);
if ($key_first === null) {
return $fallback;
}
return $array[$key_first];
}
array_first([1, 2, 3], null);
if ($a === 'foo') { // The static-analysis-tool knows that
// === between int|null and 'foo' will always evaluate to false.
// ...
}
@template TFirst // we again define your typed variables
@template TFirstFallback // and one more because we have two inputs where we want to keep track of the types
@psalm-param TFirst[] $array // here we define that $array is an array of TFirst types
@psalm-param TFirstFallback $fallback // and that $fallback is some other type that comes into this function
@psalm-return TFirst|TFirstFallback // now we define the return type as an element of the $array or the $fallback type
Very basic Active Record + Generics
The IDE support for generics is currently not there, :-/ so that we still need some hacks (see @method) for e.g. PhpStorm to have autocompletion.
⇾ https://phpstan.org/r/f88f5cd4-1bb9-4a09-baae-069fddb10b12
https://github.com/voku/phpstorm_issue_53352/tree/master/src/Framework/ActiveRecord
<?php
class ActiveRow
{
/**
* @var ManagedFactory<static>
*/
public $factory;
/**
* @param Factory<ActiveRow>|ManagedFactory<static> $factory
* @param null|array $row
*/
public function __construct(Factory $factory, array $row = null) {
$this->factory = &$factory;
}
}
/**
* @template T
*/
abstract class Factory
{
/**
* @var string
*
* @internal
*
* @psalm-var class-string<T>
*/
protected $classname;
/**
* @return static
*/
public static function create() {
return new static();
}
}
/**
* @template T
* @extends Factory<T>
*/
class ManagedFactory extends Factory
{
/**
* @param string $classname
*
* @return void
*
* @psalm-param class-string<T> $classname
*/
protected function setClass(string $classname): void
{
if (\class_exists($classname) === false) {
/** @noinspection ThrowRawExceptionInspection */
throw new Exception('TODO');
}
if (\is_subclass_of($classname, ActiveRow::class) === false) {
/** @noinspection ThrowRawExceptionInspection */
throw new Exception('TODO');
}
$this->classname = $classname;
}
// ...
}
final class Foo extends ActiveRow {
public int $foo_id;
public int $user_id;
// --------------------------------------
// add more logic here ...
// --------------------------------------
}
/**
* @method Foo[] fetchAll(...)
*
* @see Foo
*
* // warning -> do not edit this comment by hand, it's auto-generated and the @method phpdocs are for IDE support
* // -> https://gist.github.com/voku/3aba12eb898dfa209a787c398a331f9c
*
* @extends ManagedFactory<Foo>
*/
final class FooFactory extends ManagedFactory
{
// -----------------------------------------------
// add sql stuff here ...
// -----------------------------------------------
}
A more complex collection example.
In the end we can extend the “AbstractCollection” and the static-analysis-tools knows the types of all the methods.
https://github.com/voku/Arrayy/tree/master/src/Type
/**
* @template TKey of array-key
* @template T
* @template-extends \ArrayObject<TKey,T>
* @template-implements \IteratorAggregate<TKey,T>
* @template-implements \ArrayAccess<TKey|null,T>
*/
class Arrayy extends \ArrayObject implements \IteratorAggregate, \ArrayAccess, \Serializable, \JsonSerializable, \Countable
{ ... }
/**
* @template TKey of array-key
* @template T
* @template-extends \IteratorAggregate<TKey,T>
* @template-extends \ArrayAccess<TKey|null,T>
*/
interface CollectionInterface extends \IteratorAggregate, \ArrayAccess, \Serializable, \JsonSerializable, \Countable
{ ... }
/**
* @template TKey of array-key
* @template T
* @extends Arrayy<TKey,T>
* @implements CollectionInterface<TKey,T>
*/
abstract class AbstractCollection extends Arrayy implements CollectionInterface
{ ... }
/**
* @template TKey of array-key
* @template T
* @extends AbstractCollection<TKey,T>
*/
class Collection extends AbstractCollection
{ ... }
Links:
⇾ https://phpstan.org/blog/generics-in-php-using-phpdocs
⇾ https://psalm.dev/docs/annotating_code/templated_annotations/
⇾ https://stitcher.io/blog/php-generics-and-why-we-need-them
Top comments (0)