Adding file matchers

README.md

@@ -85,6 +85,8 @@ Available Matchers
 ------------------
 * [Array](../master/README.md#array)
 * [Collection](../master/README.md#collection)
+* [Core](../master/README.md#core)
+* [File](../master/README.md#file)
 * [Object](../master/README.md#object)
 * [Numbers](../master/README.md#numbers)
 * [Type checking](../master/README.md#type-checking)
@@ -227,6 +229,26 @@ assertThat([2, 4, 6], hasItem(equalTo(2)));
 assertThat([1, 3, 5], hasItems(equalTo(1), equalTo(3)));
 ```
 
+### File
+
+All file matchers accepts `\SplFileInfo` objects or `string` paths only.
+
+* `anExistingDirectory` - evaluates to true if the file exists and is a directory
+```php
+$directory = new \SplFileInfo('/var/log');
+assertThat($directory, anExistingDirectory());
+
+assertThat('/var/log', anExistingDirectory());
+```
+
+* `anExistingFile` - evaluates to true if the file exists and is a regular file
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, anExistingFile());
+
+assertThat('/var/log/php-fpm.log', anExistingFile());
+```
+
 ### Object
 
 * `hasToString` - check `__toString` or `toString` method

hamcrest/Hamcrest.php

@@ -507,6 +507,32 @@ function notSet($property)
     }
 }
 
+if (!function_exists('anExistingDirectory')) {
+    /**
+     * Evaluates to true if the file exists and is a directory.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsExistingDirectory
+     */
+    function anExistingDirectory()
+    {
+        return \Hamcrest\File\IsExistingDirectory::anExistingDirectory();
+    }
+}
+
+if (!function_exists('anExistingFile')) {
+    /**
+     * Evaluates to true if the file exists and is a regular file.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsExistingFile
+     */
+    function anExistingFile()
+    {
+        return \Hamcrest\File\IsExistingFile::anExistingFile();
+    }
+}
+
 if (!function_exists('closeTo')) {
     /**
      * Matches if value is a number equal to $value within some range of

hamcrest/Hamcrest/File/FileMatcher.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @author Vasek Brychta <[email protected]>
+ */
+
+namespace Hamcrest\File;
+
+use Hamcrest\BaseMatcher;
+use Hamcrest\Description;
+
+abstract class FileMatcher extends BaseMatcher
+{
+	/** @var string */
+	private $ownDescription;
+	/** @var string */
+	private $failureDescription;
+
+	/**
+	 * @param string $ownDescription
+	 * @param string $failureDescription
+	 */
+	public function __construct($ownDescription, $failureDescription)
+	{
+		$this->ownDescription = $ownDescription;
+		$this->failureDescription = $failureDescription;
+	}
+
+	public function describeTo(Description $description)
+	{
+		$description->appendText($this->ownDescription);
+	}
+
+	final public function matches($item)
+	{
+		return $this->isSafeType($item) && $this->matchesFile($this->createSplFileInfoObjectFromPath($item));
+	}
+
+	final public function describeMismatch($item, Description $mismatchDescription)
+	{
+		if ($this->isSafeType($item))
+		{
+			$this->describeFileMismatch($this->createSplFileInfoObjectFromPath($item), $mismatchDescription);
+		}
+		else
+		{
+			parent::describeMismatch($item, $mismatchDescription);
+		}
+	}
+
+	abstract protected function matchesFile(\SplFileInfo $file): bool;
+
+	protected function describeFileMismatch(\SplFileInfo $file, Description $mismatchDescription)
+	{
+		$mismatchDescription->appendValue($file)->appendText(' ')->appendText($this->failureDescription);
+	}
+
+	private function isSafeType($value): bool
+	{
+		return $value instanceof \SplFileInfo || is_string($value);
+	}
+
+	/**
+	 * @param string|\SplFileInfo $item
+	 * @return \SplFileInfo
+	 */
+	private function createSplFileInfoObjectFromPath($item): \SplFileInfo
+	{
+		if (is_string($item))
+			return new \SplFileInfo($item);
+
+		return $item;
+	}
+}

hamcrest/Hamcrest/File/IsExistingDirectory.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @author Vasek Brychta <[email protected]>
+ */
+
+namespace Hamcrest\File;
+
+class IsExistingDirectory extends FileMatcher
+{
+	public function __construct()
+	{
+		parent::__construct('an existing directory', 'is not a directory');
+	}
+
+	protected function matchesFile(\SplFileInfo $file): bool
+	{
+		return $file->isDir();
+	}
+
+	/**
+	 * Evaluates to true if the file exists and is a directory.
+	 * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+	 *
+	 * @return \Hamcrest\File\IsExistingDirectory
+	 * @factory
+	 */
+	public static function anExistingDirectory()
+	{
+		return new self();
+	}
+}

hamcrest/Hamcrest/File/IsExistingFile.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @author Vasek Brychta <[email protected]>
+ */
+
+namespace Hamcrest\File;
+
+use Hamcrest\BaseMatcher;
+use Hamcrest\Description;
+
+class IsExistingFile extends FileMatcher
+{
+	public function __construct()
+	{
+		parent::__construct('an existing file', 'is not a file');
+	}
+
+	protected function matchesFile(\SplFileInfo $file): bool
+	{
+		return $file->isFile();
+	}
+
+	/**
+	 * Evaluates to true if the file exists and is a regular file.
+	 * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+	 *
+	 * @return \Hamcrest\File\IsExistingFile
+	 * @factory
+	 */
+	public static function anExistingFile()
+	{
+		return new self();
+	}
+}

hamcrest/Hamcrest/Matchers.php

@@ -411,6 +411,28 @@ public static function notSet($property)
         return \Hamcrest\Core\Set::notSet($property);
     }
 
+    /**
+     * Evaluates to true if the file exists and is a directory.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsExistingDirectory
+     */
+    public static function anExistingDirectory()
+    {
+        return \Hamcrest\File\IsExistingDirectory::anExistingDirectory();
+    }
+
+    /**
+     * Evaluates to true if the file exists and is a regular file.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsExistingFile
+     */
+    public static function anExistingFile()
+    {
+        return \Hamcrest\File\IsExistingFile::anExistingFile();
+    }
+
     /**
      * Matches if value is a number equal to $value within some range of
      * acceptable error $delta.

tests/Hamcrest/File/IsExistingDirectoryTest.php

@@ -0,0 +1,136 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @author Vasek Brychta <[email protected]>
+ */
+
+namespace Hamcrest\File;
+
+use Hamcrest\AbstractMatcherTest;
+
+class IsExistingDirectoryTest extends AbstractMatcherTest
+{
+	private static $EXISTING_DIRECTORY_PATH;
+	private static $NON_EXISTING_DIRECTORY_PATH;
+	private static $EXISTING_FILE_PATH;
+
+	private static $EXISTING_DIRECTORY;
+	private static $NON_EXISTING_DIRECTORY;
+	private static $EXISTING_FILE;
+
+	/**
+	 * @beforeClass
+	 */
+	public static function initializeFiles()
+	{
+		self::$EXISTING_DIRECTORY_PATH = __DIR__;
+		self::$NON_EXISTING_DIRECTORY_PATH = __DIR__ . '/does-not-exist';
+		self::$EXISTING_FILE_PATH = __FILE__;
+
+		self::$EXISTING_DIRECTORY = new \SplFileInfo(self::$EXISTING_DIRECTORY_PATH);
+		self::$NON_EXISTING_DIRECTORY = new \SplFileInfo(self::$NON_EXISTING_DIRECTORY_PATH);
+		self::$EXISTING_FILE = new \SplFileInfo(self::$EXISTING_FILE_PATH);
+	}
+
+	protected function createMatcher()
+	{
+		return IsExistingDirectory::anExistingDirectory();
+	}
+
+	public function testMatchesAnExistingDirectory()
+	{
+		$this->assertMatches(
+			$this->createMatcher(),
+			self::$EXISTING_DIRECTORY,
+			"should match a directory that actualy exists"
+		);
+	}
+
+	public function testMatchesAnExistingDirectoryPath()
+	{
+		$this->assertMatches(
+			$this->createMatcher(),
+			self::$EXISTING_DIRECTORY_PATH,
+			"should match a path to directory that actualy exists"
+		);
+	}
+
+	public function testDoesNotMatchADirectoryThatDoesNotExist()
+	{
+		$this->assertDoesNotMatch(
+			$this->createMatcher(),
+			self::$NON_EXISTING_DIRECTORY,
+			"should not match a directory that does not exist"
+		);
+	}
+
+	public function testDoesNotMatchADirectoryPathThatDoesNotExist()
+	{
+		$this->assertDoesNotMatch(
+			$this->createMatcher(),
+			self::$NON_EXISTING_DIRECTORY_PATH,
+			"should not match a path to directory that does not exist"
+		);
+	}
+
+	public function testDoesNotMatchAnExistingFileThatIsNotADirectory()
+	{
+		$this->assertDoesNotMatch(
+			$this->createMatcher(),
+			self::$EXISTING_FILE,
+			"should not match an existing file that is not a directory"
+		);
+	}
+
+	public function testDoesNotMatchAnExistingFilePathThatIsNotADirectory()
+	{
+		$this->assertDoesNotMatch(
+			$this->createMatcher(),
+			self::$EXISTING_FILE_PATH,
+			"should not match a path to existing file that is not a directory"
+		);
+	}
+
+	public function testDoesNotMatchNull()
+	{
+		$this->assertDoesNotMatch(
+			$this->createMatcher(),
+			null,
+			'should not match null'
+		);
+	}
+
+	public function testHasAReadableDescription()
+	{
+		$this->assertDescription('an existing directory', $this->createMatcher());
+	}
+
+	public function testHasAReadableMissmatchDescription()
+	{
+		$this->assertMismatchDescription(
+			'<' . self::$NON_EXISTING_DIRECTORY . '> is not a directory',
+			$this->createMatcher(),
+			self::$NON_EXISTING_DIRECTORY
+		);
+	}
+
+	public function testHasAReadableMissmatchDescriptionForPath()
+	{
+		$this->assertMismatchDescription(
+			'<' . self::$NON_EXISTING_DIRECTORY_PATH . '> is not a directory',
+			$this->createMatcher(),
+			self::$NON_EXISTING_DIRECTORY_PATH
+		);
+	}
+
+	public function testHasAReadableTypeMissmatchDescription()
+	{
+		$this->assertMismatchDescription(
+			'was <stdClass>',
+			$this->createMatcher(),
+			new \stdClass()
+		);
+	}
+}