Merge pull request #1 from jonjo-blur/develop

Merging to master for the v1.0 release

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Jonjo McKay and blur Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,7 +1,9 @@
 Quahog
 ======
 
-Quahog is a simple PHP library to interface with the clamd anti-virus daemon.
+Quahog is a simple PHP library to interface with the clamd anti-virus daemon. It was written as all of the libraries out
+there for interfacing with ClamAV from PHP use ```exec('clamscan')```, which isn't exactly an ideal solution, as
+```clamscan``` loads the entire database into memory each time it is run - this doesn't, so it scans a lot (lot!) faster.
 
 ## Installation
 
@@ -15,9 +17,52 @@ It is recommended to install Quahog through [composer](http://getcomposer.org).
 }
 ```
 
+## Usage
+
+```php
+$quahog = new \Quahog\Quahog();
+
+// Scan a file
+$result = $quahog->scanFile('/tmp/virusfile');
+
+// Scan a file or directory recursively
+$result = $quahog->contScan('/tmp/virusdirectory');
+
+// Scan a file or directory recursively using multiple threads
+$result = $quahog->multiscanFile('/tmp/virusdirectory');
+
+// Scan a stream, and optionally pass the maximum chunk size in bytes
+$result = $quahog->scanStream(file_get_contents('/tmp/virusfile'), 1024);
+
+// Ping clamd
+$result = $quahog->ping();
+
+// Get ClamAV version details
+$result = $quahog->version();
+
+// View statistics about the ClamAV scan queue
+$result = $quahog->stats();
+
+// Reload the virus database
+$quahog->reload();
+
+// Shutdown clamd cleanly
+$quahog->shutdown();
+```
+
 ## Testing
 
 To run the test suite you will need PHPUnit installed. Go to the project root and run:
 ````bash
 $ phpunit
-````
+````
+
+## Credits
+
+![blur Group](http://i.imgur.com/5kko4VT.png)
+
+[Jonjo McKay](mailto:[email protected]) and [blur Group](http://blurgroup.com)
+
+## License
+
+Quahog is released under the [MIT License](http://www.opensource.org/licenses/MIT)

src/Quahog/Exception/ConnectionException.php

@@ -1,6 +1,10 @@
 <?php
 namespace Quahog\Exception;
 
+/**
+ * Class ConnectionException
+ * @package Quahog\Exception
+ */
 class ConnectionException extends \Exception
 {
 

src/Quahog/Quahog.php

@@ -5,13 +5,22 @@
 use Quahog\Exception\ConnectionException;
 use Socket\Raw\Factory;
 
+/**
+ * Class Quahog
+ * @package Quahog
+ */
 class Quahog
 {
 
+    /**
+     * @var \Socket\Raw\Socket
+     */
     private $_socket;
 
     /**
-     * @param string $location
+     * Instantiate a Quahog\Quahog instance
+     *
+     * @param string $location The hostname and port, or socket location to connect to clamd
      * @throws Exception\ConnectionException
      */
     public function __construct($location)
@@ -26,6 +35,8 @@ public function __construct($location)
     }
 
     /**
+     * Ping clamd to see if we get a response
+     *
      * @throws Exception\ConnectionException
      * @return bool
      */
@@ -41,6 +52,8 @@ public function ping()
     }
 
     /**
+     * Retrieve the running ClamAV version information
+     *
      * @return string
      */
     public function version()
@@ -51,6 +64,8 @@ public function version()
     }
 
     /**
+     * Fetch stats for the ClamAV scan queue
+     *
      * @return string
      */
     public function stats()
@@ -61,6 +76,8 @@ public function stats()
     }
 
     /**
+     * Reload the ClamAV virus definition database
+     *
      * @return string
      */
     public function reload()
@@ -71,6 +88,8 @@ public function reload()
     }
 
     /**
+     * Shutdown clamd cleanly
+     *
      * @return string
      */
     public function shutdown()
@@ -81,7 +100,9 @@ public function shutdown()
     }
 
     /**
-     * @param string $file
+     * Scan a single file
+     *
+     * @param string $file The location of the file to scan
      * @return string
      */
     public function scanFile($file)
@@ -92,7 +113,9 @@ public function scanFile($file)
     }
 
     /**
-     * @param string $file
+     * Scan a file or directory recursively using multiple threads
+     *
+     * @param string $file The location of the file or directory to scan
      * @return string
      */
     public function multiscanFile($file)
@@ -103,7 +126,9 @@ public function multiscanFile($file)
     }
 
     /**
-     * @param string $file
+     * Scan a file or directory recursively
+     *
+     * @param string $file The location of the file or directory to scan
      * @return string
      */
     public function contScan($file)
@@ -114,8 +139,10 @@ public function contScan($file)
     }
 
     /**
-     * @param $stream
-     * @param int $maxChunkSize
+     * Scan a stream
+     *
+     * @param string $stream A file stream in string form
+     * @param int $maxChunkSize The maximum chunk size in bytes to send to clamd at a time
      * @return string
      */
     public function scanStream($stream, $maxChunkSize = 1024)
@@ -140,6 +167,8 @@ public function scanStream($stream, $maxChunkSize = 1024)
     }
 
     /**
+     * A wrapper to send a command to clamd
+     *
      * @param string $command
      */
     private function _sendCommand($command)
@@ -148,6 +177,8 @@ private function _sendCommand($command)
     }
 
     /**
+     * A wrapper to cleanly read a response from clamd
+     *
      * @return string
      */
     private function _receiveResponse()

tests/QuahogTest.php

@@ -3,6 +3,9 @@
 
 include_once __DIR__ . '/../vendor/autoload.php';
 
+/**
+ * Class QuahogTest
+ */
 class QuahogTest extends PHPUnit_Framework_TestCase
 {
 
@@ -34,7 +37,7 @@ public function testConstruct()
     {
         $this->setExpectedException('Quahog\Exception\ConnectionException');
 
-        $quahog = new Quahog('not-a-real-clam-instance');
+        new Quahog('not-a-real-clam-instance');
     }
 
     public function testPingOK()