Skip to content

Commit

Permalink
Merge branch 'main' into as-resource
Browse files Browse the repository at this point in the history
  • Loading branch information
pascalbaljet committed Apr 3, 2024
2 parents b9236b0 + a277280 commit d0379ef
Show file tree
Hide file tree
Showing 8 changed files with 75 additions and 21 deletions.
27 changes: 18 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
<p align="center">
<img src="https://raw.githubusercontent.com/std-library/type-guard/master/docs/example.jpg" height="300" alt="Skeleton Php">
<img src="https://raw.githubusercontent.com/another-library/type-guard/master/docs/example.jpg" height="300" alt="Skeleton Php">
<p align="center">
<a href="https://github.com/std-library/type-guard/actions"><img alt="GitHub Workflow Status (master)" src="https://github.com/std-library/type-guard/actions/workflows/tests.yml/badge.svg"></a>
<a href="https://packagist.org/packages/std-library/type-guard"><img alt="Total Downloads" src="https://img.shields.io/packagist/dt/std-library/type-guard"></a>
<a href="https://packagist.org/packages/std-library/type-guard"><img alt="Latest Version" src="https://img.shields.io/packagist/v/std-library/type-guard"></a>
<a href="https://packagist.org/packages/std-library/type-guard"><img alt="License" src="https://img.shields.io/packagist/l/std-library/type-guard"></a>
<a href="https://github.com/another-library/type-guard/actions"><img alt="GitHub Workflow Status (master)" src="https://github.com/another-library/type-guard/actions/workflows/tests.yml/badge.svg"></a>
<a href="https://packagist.org/packages/another-library/type-guard"><img alt="Total Downloads" src="https://img.shields.io/packagist/dt/another-library/type-guard"></a>
<a href="https://packagist.org/packages/another-library/type-guard"><img alt="Latest Version" src="https://img.shields.io/packagist/v/another-library/type-guard"></a>
<a href="https://packagist.org/packages/another-library/type-guard"><img alt="License" src="https://img.shields.io/packagist/l/another-library/type-guard"></a>
</p>
</p>

------

> This library is a **work in progress**. Please, do not use it in production.
Type Guard module is part of the [PHP's Standard Library](https://github.com/std-library), and allows you to **narrow down the type** of a variable to a more specific type. Using the `type` function, you can perform specific checks to determine the type of an object and then use that object in a way that is **type-safe** according to the [PHPStan](https://phpstan.org/) and [Psalm](https://psalm.dev/) static analyzers.
Type Guard module is part of the [Another Library](https://github.com/another-library), and allows you to **narrow down the type** of a variable to a more specific type. Using the `type` function, you can perform specific checks to determine the type of an object and then use that object in a way that is **type-safe** according to the [PHPStan](https://phpstan.org/) and [Psalm](https://psalm.dev/) static analyzers.

Here is an example, where we use the `type` function to narrow down the type of a variable that previously had a `mixed` type:

Expand All @@ -36,7 +36,7 @@ $users = getUsers();
$users = type($users)->not()->null();
```

And one more example, where we narrow down the type of a variable to a Collection without loosing the type information:
And one more example, where we narrow down the type of a variable to a Collection without losing the type information:

```php
/** @var Collection<int, User>|null $users */
Expand All @@ -53,7 +53,7 @@ $users = type($users)->as(Collection::class);
You may use [Composer](https://getcomposer.org) to install Type Guard into your PHP project:

```bash
composer require std-library/type-guard
composer require another-library/type-guard
```

## Usage
Expand All @@ -68,6 +68,7 @@ composer require std-library/type-guard
- [`not()->null()`](#notnull)
- [`asArray()`](#asarray)
- [`asResource()`](#asresource)
- [`asIterable()`](#asiterable)

### `as`

Expand Down Expand Up @@ -140,6 +141,14 @@ Asserts and narrows down the type of the given variable to an array.
```php
$variable = type($variable)->asArray();
```
### `asIterable()`

Asserts and narrows down the type of the given variable to an iterable.

```php
$variable = type($variable)->asIterable();
```


### `asResource()`

Expand All @@ -151,4 +160,4 @@ $variable = type($variable)->asResource();

------

**Type Guard** is part of the [PHP's Standard Library](https://github.com/std-library) project. It was created by **[Nuno Maduro](https://twitter.com/enunomaduro)** and open-sourced under the **[MIT license](https://opensource.org/licenses/MIT)**.
**Type Guard** is part of the [Another Library](https://github.com/another-library) project. It was created by **[Nuno Maduro](https://twitter.com/enunomaduro)** and open-sourced under the **[MIT license](https://opensource.org/licenses/MIT)**.
18 changes: 9 additions & 9 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "std-library/type-guard",
"description": "Type Guard module is part of the PHP's Standard Library, and allows you to narrow down the type of an variable to a more specific type.",
"keywords": ["std-library", "type-guard", "assert", "narrow", "type", "php"],
"name": "another-library/type-guard",
"description": "Type Guard module is part of the Another Library, and allows you to narrow down the type of an variable to a more specific type.",
"keywords": ["another-library", "type-guard", "assert", "narrow", "type", "php"],
"license": "MIT",
"authors": [
{
Expand All @@ -22,17 +22,17 @@
},
"autoload": {
"psr-4": {
"StdLibrary\\TypeGuard\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"Tests\\": "tests/"
"AnotherLibrary\\TypeGuard\\": "src/"
},
"files": [
"src/Functions.php"
]
},
"autoload-dev": {
"psr-4": {
"Tests\\": "tests/"
}
},
"minimum-stability": "dev",
"prefer-stable": true,
"config": {
Expand Down
Binary file modified docs/example.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion src/Functions.php
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

declare(strict_types=1);

use StdLibrary\TypeGuard\Type;
use AnotherLibrary\TypeGuard\Type;

if (! function_exists('type')) {
/**
Expand Down
2 changes: 1 addition & 1 deletion src/Not.php
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

declare(strict_types=1);

namespace StdLibrary\TypeGuard;
namespace AnotherLibrary\TypeGuard;

use TypeError;

Expand Down
18 changes: 17 additions & 1 deletion src/Type.php
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

declare(strict_types=1);

namespace StdLibrary\TypeGuard;
namespace AnotherLibrary\TypeGuard;

use TypeError;

Expand Down Expand Up @@ -161,6 +161,22 @@ public function asCallable(): callable
return $this->variable;
}

/**
* Asserts and narrow down the type to an iterable.
*
* @phpstan-assert-if-true iterable $this->variable
*
* @return (TVariable is iterable ? TVariable : never)
*/
public function asIterable(): iterable
{
if (! is_iterable($this->variable)) {
throw new TypeError('Variable is not a [iterable].');
}

return $this->variable;
}

/**
* Creates a not type instance.
*
Expand Down
17 changes: 17 additions & 0 deletions tests/AsIterableTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?php

declare(strict_types=1);

test('iterable type', function (): void {
$variable = [];

$value = type($variable)->asIterable();

expect($value)->toBeIterable();
});

test('not iterable type', function (): void {
$variable = 1;

type($variable)->asIterable();
})->throws(TypeError::class, 'Variable is not a [iterable].');
12 changes: 12 additions & 0 deletions types/AsIterableTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<?php

declare(strict_types=1);

use function PHPStan\Testing\assertType;

/** @var array<int, int>|string $variable */
$variable = random_int(0, 1) !== 0 ? 'string' : [1, 2];
assertType('array<int, int>', type($variable)->asIterable());

$variable = random_int(0, 1) !== 0 ? 'string' : [];
assertType('array{}', type($variable)->asIterable());

0 comments on commit d0379ef

Please sign in to comment.