Skip to content

Commit

Permalink
Merge pull request #351 from gsteel/v3/file-exists-refactor
Browse files Browse the repository at this point in the history 
Refactor `Exists` and `NotExists` validators
  • Loading branch information
@gsteel
gsteel authored Jul 11, 2024
2 parents eba19e6 + 41c41b3 commit 28b579e
Show file tree
Hide file tree
Showing 7 changed files with 319 additions and 576 deletions.
55 changes: 46 additions & 9 deletions docs/book/v3/validators/file/exists.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,27 +9,64 @@ This validator is inversely related to the [NotExists validator](not-exists.md).

The following set of options are supported:

- `directory`: Array of directories, or comma-delimited string of directories.
- `directory`: Array of directories, or comma-delimited string of directories.
- `all`: A boolean that when `true` _(default)_ requires that the filename is present in **all** the listed directories

## Usage Examples

```php
use Laminas\Validator\File\Exists;

// Only allow files that exist in ~both~ directories
$validator = new Exists('/tmp,/var/tmp');
$validator = new Exists(['directory' => '/tmp,/var/tmp']);

// ...or with array notation
$validator = new Exists(['/tmp', '/var/tmp']);
if ($validator->isValid('myfile.txt')) {
// file is present in all directories
} else {
// file was not present in at least 1 of the directories
}
```

```php
use Laminas\Validator\File\Exists;

// Perform validation
if ($validator->isValid('/tmp/myfile.txt')) {
// file is valid
// Allow files that exist in any of the listed directories
$validator = new Exists([
'directory' => ['/tmp', '/var/tmp'],
'all' => false,
]);

if ($validator->isValid('myfile.txt')) {
// file was found in at least 1 directory
} else {
// file was not found in one of the directories
}
```

```php
use Laminas\Validator\File\Exists;

// Check the value for existence without a directory option
$validator = new Exists();

if ($validator->isValid('/path/to/myfile.txt')) {
// file exists
}
```

> ### Checks against all directories
>
> This validator checks whether the specified file exists in **all** of the
> By default, this validator checks whether the specified file exists in **all** of the
> given directories; validation will fail if the file does not exist in one
> or more of them.
> or more of them. To change this behaviour, be sure to set the `all` option to false.
## Validating Uploaded Files

This validator accepts and validates 3 types of argument:

- A string that represents a path or a file name
- An array that represents an uploaded file as per PHP's [`$_FILES`](https://www.php.net/manual/reserved.variables.files.php) superglobal
- A PSR-7 [`UploadedFileInterface`](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface) instance

Without a `directory` option, the validator will check any of the listed argument types to ensure they exist.
For example, without a `directory` option, any successful upload will be deemed valid.
57 changes: 41 additions & 16 deletions docs/book/v3/validators/file/not-exists.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,22 @@ This validator is inversely related to the [Exists validator](exists.md).

The following set of options are supported:

- `directory`: Array of directories or comma-delimited string of directories
against which to validate.
- `directory`: Array of directories or comma-delimited string of directories against which to validate.

## Basic Usage

```php
use Laminas\Validator\File\NotExists;

// Only allow files that do not exist in ~either~ directories
$validator = new NotExists('/tmp,/var/tmp');
// Only allow files that do not exist in any of the given directories
$validator = new NotExists([
'directory' => ['/tmp', '/var/tmp'],
]);

// ... or with array notation:
$validator = new NotExists(['/tmp', '/var/tmp']);

// ... or using options notation:
$validator = new NotExists(['directory' => [
'/tmp',
'/var/tmp',
]]);

// Perform validation
if ($validator->isValid('/home/myfile.txt')) {
// file is valid
if ($validator->isValid('some-file.txt')) {
// File cannot be found in any of the directories provided
} else {
// A file with the given name was found
}
```

Expand All @@ -40,3 +33,35 @@ if ($validator->isValid('/home/myfile.txt')) {
> This validator checks whether the specified file does not exist in **any** of
> the given directories; validation will fail if the file exists in one (or
> more) of the given directories.
## Validating Uploaded Files

This validator accepts and validates 3 types of argument:

- A string that represents a path or a file name
- An array that represents an uploaded file as per PHP's [`$_FILES`](https://www.php.net/manual/reserved.variables.files.php) superglobal
- A PSR-7 [`UploadedFileInterface`](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface) instance

When provided with either a PSR-7 Uploaded File, or a normalised `$_FILES` upload, if the directory option is unset, validation will fail for successfully uploaded files, however, when a directory option is provided, the given directories are searched for the base name of the uploaded file path.

In the following example, assume `$files` is an array that represents a single, successful file upload in PHP's `$_FILES` array format.

```php
use Laminas\Validator\File\NotExists;

$validator = new NotExists();
$validator->isValid($files); // False - the uploaded file exists (Of course)

$validator = new NotExists([
'directory' => [
'/home/files',
'/tmp',
],
]);

if ($validator->isValid($files)) {
// The basename of the uploaded file could not be found in any of the directories
} else {
// The basename of the uploaded file was located in at least 1 of the directories
}
```
86 changes: 0 additions & 86 deletions psalm-baseline.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,48 +159,6 @@
<code><![CDATA[strrpos($fileInfo['filename'], '.')]]></code>
</PossiblyFalseOperand>
</file>
<file src="src/File/Exists.php">
<DocblockTypeContradiction>
<code><![CDATA[is_array($directory)]]></code>
</DocblockTypeContradiction>
<InvalidIterator>
<code><![CDATA[$directories]]></code>
</InvalidIterator>
<InvalidReturnStatement>
<code><![CDATA[$directory]]></code>
</InvalidReturnStatement>
<MixedArgument>
<code><![CDATA[$fileInfo['file']]]></code>
</MixedArgument>
<MixedArgumentTypeCoercion>
<code><![CDATA[$directories]]></code>
</MixedArgumentTypeCoercion>
<MixedAssignment>
<code><![CDATA[$dir]]></code>
<code><![CDATA[$directory]]></code>
<code><![CDATA[$directory]]></code>
</MixedAssignment>
<MixedInferredReturnType>
<code><![CDATA[string|null]]></code>
</MixedInferredReturnType>
<MixedOperand>
<code><![CDATA[$directory]]></code>
<code><![CDATA[$fileInfo['basename']]]></code>
</MixedOperand>
<MixedReturnStatement>
<code><![CDATA[$directory]]></code>
</MixedReturnStatement>
<MoreSpecificImplementedParamType>
<code><![CDATA[$value]]></code>
</MoreSpecificImplementedParamType>
<PossiblyInvalidArgument>
<code><![CDATA[$directories]]></code>
<code><![CDATA[$options]]></code>
</PossiblyInvalidArgument>
<RedundantCastGivenDocblockType>
<code><![CDATA[(bool) $asArray]]></code>
</RedundantCastGivenDocblockType>
</file>
<file src="src/File/Extension.php">
<MixedArgument>
<code><![CDATA[$ext]]></code>
Expand Down Expand Up @@ -264,32 +222,12 @@
<code><![CDATA[$value]]></code>
<code><![CDATA[$value]]></code>
<code><![CDATA[$value]]></code>
<code><![CDATA[$value]]></code>
<code><![CDATA[$value]]></code>
</PossiblyInvalidArgument>
<PossiblyInvalidCast>
<code><![CDATA[$fileInfo['file']]]></code>
<code><![CDATA[$value]]></code>
</PossiblyInvalidCast>
</file>
<file src="src/File/NotExists.php">
<InvalidIterator>
<code><![CDATA[$directories]]></code>
</InvalidIterator>
<MixedArgument>
<code><![CDATA[$fileInfo['file']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$directory]]></code>
</MixedAssignment>
<MixedOperand>
<code><![CDATA[$directory]]></code>
<code><![CDATA[$fileInfo['basename']]]></code>
</MixedOperand>
<MoreSpecificImplementedParamType>
<code><![CDATA[$value]]></code>
</MoreSpecificImplementedParamType>
</file>
<file src="src/File/Upload.php">
<DocblockTypeContradiction>
<code><![CDATA[null === $files]]></code>
Expand Down Expand Up @@ -581,20 +519,8 @@
</PossiblyUnusedMethod>
</file>
<file src="test/File/ExistsTest.php">
<ArgumentTypeCoercion>
<code><![CDATA[$value]]></code>
</ArgumentTypeCoercion>
<MixedArgument>
<code><![CDATA[$isValidParam['tmp_name']]]></code>
</MixedArgument>
<PossiblyNullArgument>
<code><![CDATA[$value]]></code>
</PossiblyNullArgument>
<PossiblyUnusedMethod>
<code><![CDATA[basicBehaviorDataProvider]]></code>
<code><![CDATA[getDirectoryProvider]]></code>
<code><![CDATA[invalidDirectoryArguments]]></code>
<code><![CDATA[setDirectoryProvider]]></code>
</PossiblyUnusedMethod>
</file>
<file src="test/File/ExtensionTest.php">
Expand Down Expand Up @@ -655,20 +581,8 @@
</PossiblyUnusedMethod>
</file>
<file src="test/File/NotExistsTest.php">
<ArgumentTypeCoercion>
<code><![CDATA[$value]]></code>
</ArgumentTypeCoercion>
<MixedArgument>
<code><![CDATA[$isValidParam['tmp_name']]]></code>
</MixedArgument>
<PossiblyNullArgument>
<code><![CDATA[$value]]></code>
</PossiblyNullArgument>
<PossiblyUnusedMethod>
<code><![CDATA[basicBehaviorDataProvider]]></code>
<code><![CDATA[getDirectoryProvider]]></code>
<code><![CDATA[invalidDirectoryArguments]]></code>
<code><![CDATA[setDirectoryProvider]]></code>
</PossiblyUnusedMethod>
</file>
<file src="test/File/SizeTest.php">
Expand Down
Loading

0 comments on commit 28b579e

Please sign in to comment.