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,99 @@ 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());
+```
+
+* `anExistingFileOrDirectory` - evaluates to true if the file exists and is a regular file or a directory
+```php
+$directory = new \SplFileInfo('/var/log');
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($directory, anExistingFileOrDirectory());
+assertThat($file, anExistingFileOrDirectory());
+
+assertThat('/var/log', anExistingFileOrDirectory());
+assertThat('/var/log/php-fpm.log', anExistingFileOrDirectory());
+```
+
+* `aReadableFile` - evaluates to true if the file is readable
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, aReadableFile());
+
+assertThat('/var/log/php-fpm.log', aReadableFile());
+```
+
+* `aWritableFile` - evaluates to true if the file is writable
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, aWritableFile());
+
+assertThat('/var/log/php-fpm.log', aWritableFile());
+```
+
+* `aFileWithSize` - evaluates to true if the file size is equal to given value or the provided matcher matches the file size
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, aFileWithSize(42));
+assertThat($file, aFileWithSize(greaterThan(42)));
+
+assertThat('/var/log/php-fpm.log', aFileWithSize(42));
+assertThat('/var/log/php-fpm.log', aFileWithSize(greaterThan(42)));
+```
+
+* `anEmptyFile` - evaluates to true if the file is empty
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, anEmptyFile());
+
+assertThat('/var/log/php-fpm.log', anEmptyFile());
+```
+
+* `aNonEmptyFile` - evaluates to true if the file is not empty
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, aNonEmptyFile());
+
+assertThat('/var/log/php-fpm.log', aNonEmptyFile());
+```
+
+* `aFileNamed` - evaluates to true if the file name is equal to given value or the provided matcher matches the file name
+```php
+$file = new \SplFileInfo('/var/log/php-fpm.log');
+assertThat($file, aFileNamed('php-fpm.log'));
+assertThat($file, aFileNamed(startsWith('php')));
+
+assertThat('/var/log/php-fpm.log', aFileNamed('php-fpm.log'));
+assertThat('/var/log/php-fpm.log', aFileNamed(startsWith('php')));
+```
+
+* `aFileWithCanonicalPath` - evaluates to true if the file canonical path is equal to given value or the provided matcher matches the canonical path of the file
+```php
+$file = new \SplFileInfo('/var/log/./php-fpm.log');
+assertThat($file, aFileWithCanonicalPath('/var/log/php-fpm.log'));
+assertThat($file, aFileWithCanonicalPath(endsWith('log/php-fpm.log')));
+
+assertThat('/var/log/./php-fpm.log', aFileWithCanonicalPath('/var/log/php-fpm.log'));
+assertThat('/var/log/./php-fpm.log', aFileWithCanonicalPath(endsWith('log/php-fpm.log')));
+```
+
 ### Object
 
 * `hasToString` - check `__toString` or `toString` method

hamcrest/Hamcrest.php

@@ -507,6 +507,142 @@ 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('anExistingFileOrDirectory')) {
+    /**
+     * Evaluates to true if the file exists and is a regular file or a directory.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsExistingFileOrDirectory
+     */
+    function anExistingFileOrDirectory()
+    {
+        return \Hamcrest\File\IsExistingFileOrDirectory::anExistingFileOrDirectory();
+    }
+}
+
+if (!function_exists('aFileNamed')) {
+    /**
+     * Does file name satisfy a given matcher?
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @param \Hamcrest\Matcher|string $name as a {@link \Hamcrest\Matcher} or a value.
+     *
+     * @return \Hamcrest\File\IsFileNamed
+     */
+    function aFileNamed($name)
+    {
+        return \Hamcrest\File\IsFileNamed::aFileNamed($name);
+    }
+}
+
+if (!function_exists('aFileWithCanonicalPath')) {
+    /**
+     * Does canonical path satisfy a given matcher?
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @param \Hamcrest\Matcher|string $path as a {@link \Hamcrest\Matcher} or a value.
+     *
+     * @return \Hamcrest\File\IsFileWithCanonicalPath
+     */
+    function aFileWithCanonicalPath($path)
+    {
+        return \Hamcrest\File\IsFileWithCanonicalPath::aFileWithCanonicalPath($path);
+    }
+}
+
+if (!function_exists('aFileWithSize')) {
+    /**
+     * Does file size satisfy a given matcher?
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @param \Hamcrest\Matcher|int $size as a {@link \Hamcrest\Matcher} or a value.
+     *
+     * @return \Hamcrest\File\IsFileWithSize
+     */
+    function aFileWithSize($size)
+    {
+        return \Hamcrest\File\IsFileWithSize::aFileWithSize($size);
+    }
+}
+
+if (!function_exists('anEmptyFile')) {
+    /**
+     * Matches an empty file.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\Core\DescribedAs
+     */
+    function anEmptyFile()
+    {
+        return \Hamcrest\File\IsFileWithSize::anEmptyFile();
+    }
+}
+
+if (!function_exists('aNonEmptyFile')) {
+    /**
+     * Matches a non-empty file.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\Core\DescribedAs
+     */
+    function aNonEmptyFile()
+    {
+        return \Hamcrest\File\IsFileWithSize::aNonEmptyFile();
+    }
+}
+
+if (!function_exists('aReadableFile')) {
+    /**
+     * Evaluates to true if the file is readable.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsReadableFile
+     */
+    function aReadableFile()
+    {
+        return \Hamcrest\File\IsReadableFile::aReadableFile();
+    }
+}
+
+if (!function_exists('aWritableFile')) {
+    /**
+     * Evaluates to true if the file is writable.
+     * Accepts only <code>\SplFileInfo</code> objects or <code>string</code> paths.
+     *
+     * @return \Hamcrest\File\IsWritableFile
+     */
+    function aWritableFile()
+    {
+        return \Hamcrest\File\IsWritableFile::aWritableFile();
+    }
+}
+
 if (!function_exists('closeTo')) {
     /**
      * Matches if value is a number equal to $value within some range of

hamcrest/Hamcrest/Core/DescribedAs.php

@@ -51,6 +51,11 @@ public function describeTo(Description $description)
         }
     }
 
+	public function describeMismatch($item, Description $description)
+	{
+		$this->_matcher->describeMismatch($item, $description);
+	}
+
     /**
      * Wraps an existing matcher and overrides the description when it fails.
      *

hamcrest/Hamcrest/File/FileMatcher.php

@@ -0,0 +1,91 @@
+<?php
+
+/**
+ * @author Vasek Brychta <vaclav@brychtovi.cz>
+ */
+
+namespace Hamcrest\File;
+
+use Hamcrest\BaseMatcher;
+use Hamcrest\Description;
+
+abstract class FileMatcher extends BaseMatcher
+{
+	/**
+	 * Description of the matcher that will be returned from the {@link describeTo()} method.
+	 *
+	 * @var string
+	 */
+	private $ownDescription;
+
+	/**
+	 * Description of a mismatch for the matcher, it will be prepended by the actual value that does not match.
+	 *
+	 * @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);
+		}
+	}
+
+	/**
+	 * Implement this method to provide the actual functionality of the matcher.
+	 * It is guaranteed that the {@link $file} parameter is always {@code \SplFileInfo}.
+	 *
+	 * @param \SplFileInfo $file
+	 * @return bool
+	 */
+	abstract protected function matchesFile(\SplFileInfo $file);
+
+	protected function describeFileMismatch(\SplFileInfo $file, Description $mismatchDescription)
+	{
+		$mismatchDescription->appendValue($file)->appendText(' ')->appendText($this->failureDescription);
+	}
+
+	/**
+	 * @param $value
+	 * @return bool
+	 */
+	private function isSafeType($value)
+	{
+		return $value instanceof \SplFileInfo || is_string($value);
+	}
+
+	/**
+	 * @param string|\SplFileInfo $item
+	 * @return \SplFileInfo
+	 */
+	private function createSplFileInfoObjectFromPath($item)
+	{
+		if (is_string($item))
+			return new \SplFileInfo($item);
+
+		return $item;
+	}
+}

hamcrest/Hamcrest/File/IsExistingDirectory.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * @author Vasek Brychta <vaclav@brychtovi.cz>
+ */
+
+namespace Hamcrest\File;
+
+class IsExistingDirectory extends FileMatcher
+{
+	public function __construct()
+	{
+		parent::__construct('an existing directory', 'is not a directory');
+	}
+
+	protected function matchesFile(\SplFileInfo $file)
+	{
+		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();
+	}
+}