Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add phpstan typing annotations #250

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
"require-dev": {
"squizlabs/php_codesniffer": "~3.0",
"phpunit/phpunit": "^7.0 || ^8.0 || ^9.5",
"friendsofphp/php-cs-fixer": "^2.17"
"friendsofphp/php-cs-fixer": "^2.17",
"phpstan/phpstan": "^1.10"
},
"autoload": {
"psr-4": {
Expand Down
12 changes: 10 additions & 2 deletions src/Functional/Ary.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,19 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Call $func with only abs($count) arguments, taken either from the
* left or right depending on the sign
*
* @template V
* @template T
*
* @param callable(T...):V $func
* @param non-zero-int $count
*
* @return callable(T...):V
*
* @no-named-arguments
*/
function ary(callable $func, int $count): callable
Expand All @@ -25,7 +33,7 @@ function ary(callable $func, int $count): callable
return function (...$args) use ($func, $count) {
if ($count > 0) {
return $func(...take_left($args, $count));
} else if ($count < 0) {
} else {
return $func(...take_right($args, -$count));
}
};
Expand Down
11 changes: 8 additions & 3 deletions src/Functional/Average.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,18 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Returns the average of all numeric values in the array or null if no numeric value was found
*
* @param Traversable|array $collection
* @return null|float|int
* @param iterable<mixed> $collection
*
* @return ($collection is iterable<int> ? float|int : (
* $collection is iterable<float> ? float : (
* $collection is iterable<int|float|numeric-string> ? float|int : null
* )
* ))
KmeCnin marked this conversation as resolved.
Show resolved Hide resolved
*
* @no-named-arguments
*/
function average($collection)
Expand Down
9 changes: 6 additions & 3 deletions src/Functional/ButLast.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,16 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Returns an array containing the elements of the list without its last element.
*
* @param Traversable|array $collection
* @return array
* @template T
*
* @param iterable<T> $collection
*
* @return iterable<T>
*
* @no-named-arguments
*/
function but_last($collection)
Expand Down
12 changes: 8 additions & 4 deletions src/Functional/Capture.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,15 @@
namespace Functional;

/**
* Return a new function that captures the return value of $callback in $result and returns the callbacks return value
* Return a new function that captures the return value of $callback in $result and returns the callback's return value
*
* @template T
*
* @param callable():T $callback
* @param T $result
*
* @return callable():T
Comment on lines +16 to +21
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be great to indicate with types that the callback given is type-wise identical. But this depends on phpstan/phpstan#8964 and phpstan/phpstan#8214

*
* @param callable $callback
* @param mixed $result
* @return callable
* @no-named-arguments
*/
function capture(callable $callback, &$result)
Expand Down
11 changes: 8 additions & 3 deletions src/Functional/CompareObjectHashOn.php
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,14 @@
/**
* Returns a comparison function that can be used with e.g. `usort()`
*
* @param callable $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
* @param callable $keyFunction A function that takes an argument and returns the value that should be compared
* @return callable
* @template V
* @template R of int
KmeCnin marked this conversation as resolved.
Show resolved Hide resolved
*
* @param callable(string,string):R $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
* @param null|callable(V):string $keyFunction A function that takes an argument and returns the value that should be compared
*
* @return callable(object,object):R
*
* @no-named-arguments
*/
function compare_object_hash_on(callable $comparison, callable $keyFunction = null)
Expand Down
12 changes: 9 additions & 3 deletions src/Functional/CompareOn.php
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,15 @@
/**
* Returns a comparison function that can be used with e.g. `usort()`
*
* @param callable $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
* @param callable $reducer A function that takes an argument and returns the value that should be compared
* @return callable
* @template V
* @template V2
* @template R of int
*
* @param callable(V,V):R $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
* @param null|callable(V2):V $reducer A function that takes an argument and returns the value that should be compared
*
* @return ($reducer is null ? callable(V,V):R : callable(V2,V2):R)
*
* @no-named-arguments
*/
function compare_on(callable $comparison, callable $reducer = null)
Expand Down
4 changes: 3 additions & 1 deletion src/Functional/Concat.php
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@
/**
* Concatenates zero or more strings
*
* @param string[] ...$strings
* @param string ...$strings
*
* @return string
*
* @no-named-arguments
*/
function concat(string ...$strings)
Expand Down
8 changes: 6 additions & 2 deletions src/Functional/ConstFunction.php
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,12 @@
/**
* Wrap value within a function, which will return it, without any modifications.
*
* @param mixed $value
* @return callable
* @template V
*
* @param V $value
*
* @return callable():V
*
* @no-named-arguments
*/
function const_function($value)
Expand Down
10 changes: 7 additions & 3 deletions src/Functional/Contains.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,20 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Returns true if the collection contains the given value. If the third parameter is
* true values will be compared in strict mode
*
* @param Traversable|array $collection
* @param mixed $value
* @template V
* @template V2 of V
*
* @param iterable<V> $collection
* @param V2 $value
* @param bool $strict
*
* @return bool
*
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be a bit more complicated, to properly type the strictness.

We need a conditional type here where V2 is of V if strict is true but otherwise V2 is independent of V

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch.
Here is what I ended with: https://phpstan.org/r/c7d1770b-678b-446f-a285-095557fb6b3e

* @no-named-arguments
*/
function contains($collection, $value, $strict = true)
Expand Down
12 changes: 9 additions & 3 deletions src/Functional/Converge.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,15 @@
* The results of each branching function are passed as arguments
* to the converging function to produce the return value.
*
* @param callable $convergingFunction Will be invoked with the return values of all branching functions as its arguments
* @param callable[] $branchingFunctions A list of functions
* @return callable A flipped version of the given function
* @template V
* @template R
* @template R2
*
* @param callable(R...):R2 $convergingFunction Will be invoked with the return values of all branching functions as its arguments
* @param array<callable(V):R> $branchingFunctions A list of functions
*
* @return callable(V...):R2 A flipped version of the given function
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is tricky again as callable(R...) means that all args must be of type R, which is not the actual type. So it also depends on phpstan/phpstan#8214

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, so while we are waiting for 8214 to be merged, I ended up by up-typing to mixed args:

/**
 * Accepts a converging function and a list of branching functions and returns a new function.
 *
 * The results of each branching function are passed as arguments
 * to the converging function to produce the return value.
 *
 * @template R
 * @template R2
 *
 * @param callable(mixed...):R2 $convergingFunction Will be invoked with the return values of all branching functions as its arguments
 * @param array<callable(mixed...):R> $branchingFunctions A list of functions
 *
 * @return callable(mixed...):R2
 *
 * @no-named-arguments
 */
function converge($convergingFunction, array $branchingFunctions)

*
* @no-named-arguments
*/
function converge($convergingFunction, array $branchingFunctions)
Expand Down
13 changes: 9 additions & 4 deletions src/Functional/Curry.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,17 @@
use Closure;

/**
* Return a curryied version of the given function. You can decide if you also
* Return a curried version of the given function. You can decide if you also
* want to curry optional parameters or not.
*
* @param callable $function the function to curry
* @param bool $required curry optional parameters ?
* @return callable a curryied version of the given function
* @template V
* @template R
*
* @param callable(V...):R $function the function to curry
* @param bool $required curry optional parameters?
*
* @return callable(V...):R a curried version of the given function
KmeCnin marked this conversation as resolved.
Show resolved Hide resolved
*
* @no-named-arguments
*/
function curry(callable $function, $required = true)
Expand Down
11 changes: 8 additions & 3 deletions src/Functional/CurryN.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,20 @@
namespace Functional;

/**
* Return a version of the given function where the $count first arguments are curryied.
* Return a version of the given function where the $count first arguments are curried.
*
* No check is made to verify that the given argument count is either too low or too high.
* If you give a smaller number you will have an error when calling the given function. If
* you give a higher number, arguments will simply be ignored.
*
* @template R
* @template V
*
* @param int $count number of arguments you want to curry
* @param callable $function the function you want to curry
* @return callable a curryied version of the given function
* @param callable(V...):R $function the function you want to curry
*
* @return callable(V...):R a curried version of the given function
KmeCnin marked this conversation as resolved.
Show resolved Hide resolved
*
* @no-named-arguments
*/
function curry_n($count, callable $function)
Expand Down
12 changes: 8 additions & 4 deletions src/Functional/Difference.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,18 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Takes a collection and returns the difference of all elements
*
* @param Traversable|array $collection
* @param integer|float $initial
* @return integer|float
* @template V
* @template I of int|float
*
* @param iterable<V> $collection
* @param I $initial
*
* @return (V is int ? ($initial is int ? int : float) : (V is float ? float : int|float))
*
* @no-named-arguments
*/
function difference($collection, $initial = 0)
Expand Down
12 changes: 8 additions & 4 deletions src/Functional/DropFirst.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,18 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Drop all elements from a collection until callback returns false
*
* @param Traversable|array $collection
* @param callable $callback
* @return array
* @template K of array-key
* @template V
*
* @param iterable<K, V> $collection
* @param callable(V, K, iterable<K, V>):bool $callback
*
* @return array<K,V>
*
* @no-named-arguments
*/
function drop_first($collection, callable $callback)
Expand Down
12 changes: 8 additions & 4 deletions src/Functional/DropLast.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,18 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Drop all elements from a collection after callback returns true
*
* @param Traversable|array $collection
* @param callable $callback
* @return array
* @template K of array-key
* @template V
*
* @param iterable<K, V> $collection
* @param callable(V, K, iterable<K, V>):bool $callback
*
* @return ($collection is list<V> ? list<V> : array<K,V>)
*
* @no-named-arguments
*/
function drop_last($collection, callable $callback)
Expand Down
12 changes: 8 additions & 4 deletions src/Functional/Each.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,19 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Iterates over a collection of elements, yielding each in turn to a callback function. Each invocation of $callback
* is called with three arguments: (element, index, collection)
*
* @param Traversable|array $collection
* @param callable $callback
* @return null
* @template K
* @template V
*
* @param iterable<K,V> $collection
* @param callable(V,K,iterable<K,V>):void $callback
*
* @return void
*
* @no-named-arguments
*/
function each($collection, callable $callback)
Expand Down
13 changes: 9 additions & 4 deletions src/Functional/Entries.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,21 @@
namespace Functional;

use Functional\Exceptions\InvalidArgumentException;
use Traversable;

/**
* Inspired by JavaScript’s `Object.entries`, and Python’s `enumerate`,
* convert a key-value map into an array of key-value pairs
*
* @see Functional\from_entries
* @param Traversable|array $collection
* @see \Functional\from_entries
*
* @template K
* @template V
*
* @param iterable<K,V> $collection
* @param int $start
* @return array
*
* @return array<int, array{K,V}>
KmeCnin marked this conversation as resolved.
Show resolved Hide resolved
*
* @no-named-arguments
*/
function entries($collection, int $start = 0)
Expand Down
3 changes: 2 additions & 1 deletion src/Functional/Equal.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@
*
* @param mixed $b the value to compare to
*
* @return callable the function to perform the comparison
* @return callable(mixed):bool the function to perform the comparison
*
* @no-named-arguments
*/
function equal($b)
Expand Down
Loading
Loading