Improve phpdoc

src/IShare.php

@@ -8,34 +8,6 @@
 namespace Icewind\SMB;
 
 interface IShare {
-	public function connect();
-
-	/**
-	 * Create a folder on the share
-	 *
-	 * @param string $path
-	 * @return bool
-	 */
-	public function mkdir($path);
-
-	/**
-	 * Download a remote file
-	 *
-	 * @param string $source remove file
-	 * @param string $target local file
-	 * @return bool
-	 */
-	public function get($source, $target);
-
-	/**
-	 * Rename a remote file
-	 *
-	 * @param string $from
-	 * @param string $to
-	 * @return bool
-	 */
-	public function rename($from, $to);
-
 	/**
 	 * Get the name of the share
 	 *
@@ -43,15 +15,75 @@ interface IShare {
 	 */
 	public function getName();
 
+	/**
+	 * Download a remote file
+	 *
+	 * @param string $source remove file
+	 * @param string $target local file
+	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
+	 */
+	public function get($source, $target);
+
 	/**
 	 * Upload a local file
 	 *
 	 * @param string $source local file
 	 * @param string $target remove file
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function put($source, $target);
 
+	/**
+	 * Open a readable stream top a remote file
+	 *
+	 * @param string $source
+	 * @return resource a read only stream with the contents of the remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
+	 */
+	public function read($source);
+
+	/**
+	 * Open a writable stream to a remote file
+	 *
+	 * @param string $target
+	 * @return resource a write only stream to upload a remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
+	 */
+	public function write($target);
+
+	/**
+	 * Rename a remote file
+	 *
+	 * @param string $from
+	 * @param string $to
+	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
+	 */
+	public function rename($from, $to);
+
+	/**
+	 * Delete a file on the share
+	 *
+	 * @param string $path
+	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
+	 */
+	public function del($path);
+
 	/**
 	 * List the content of a remote folder
 	 *
@@ -67,38 +99,31 @@ interface IShare {
 	 *
 	 * @param $path
 	 * @return array[]
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function dir($path);
 
+	/**
+	 * Create a folder on the share
+	 *
+	 * @param string $path
+	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
+	 */
+	public function mkdir($path);
+
 	/**
 	 * Remove a folder on the share
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function rmdir($path);
-
-	/**
-	 * Delete a file on the share
-	 *
-	 * @param string $path
-	 * @return bool
-	 */
-	public function del($path);
-
-	/**
-	 * Open a readable stream top a remote file
-	 *
-	 * @param string $source
-	 * @return resource a read only stream with the contents of the remote file
-	 */
-	public function read($source);
-
-	/**
-	 * Open a writable stream to a remote file
-	 *
-	 * @param string $target
-	 * @return resource a write only stream to upload a remote file
-	 */
-	public function write($target);
 }

src/NativeShare.php

@@ -58,9 +58,11 @@ class NativeShare implements IShare {
 	}
 
 	/**
-	 * @throws ConnectionError
+	 * @throws \Icewind\SMB\ConnectionError
+	 * @throws \Icewind\SMB\AuthenticationException
+	 * @throws \Icewind\SMB\InvalidHostException
 	 */
-	public function connect() {
+	protected function connect() {
 		if ($this->state and is_resource($this->state)) {
 			return;
 		}
@@ -130,6 +132,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param $path
 	 * @return array[]
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function dir($path) {
 		$this->connect();
@@ -166,6 +171,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
 	 */
 	public function mkdir($path) {
 		$this->connect();
@@ -180,6 +188,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function rmdir($path) {
 		$this->connect();
@@ -194,6 +205,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function del($path) {
 		$this->connect();
@@ -209,6 +223,9 @@ class NativeShare implements IShare {
 	 * @param string $from
 	 * @param string $to
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
 	 */
 	public function rename($from, $to) {
 		$this->connect();
@@ -249,6 +266,9 @@ class NativeShare implements IShare {
 	 * @param string $source local file
 	 * @param string $target remove file
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function put($source, $target) {
 		$sourceHandle = fopen($source, 'rb');
@@ -269,6 +289,9 @@ class NativeShare implements IShare {
 	 * @param string $source remove file
 	 * @param string $target local file
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function get($source, $target) {
 		$sourceHandle = $this->fopen($source, 'r');
@@ -287,6 +310,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param string $source
 	 * @return resource a read only stream with the contents of the remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function read($source) {
 		$handle = $this->fopen($source, 'r');
@@ -304,6 +330,9 @@ class NativeShare implements IShare {
 	 *
 	 * @param string $source
 	 * @return resource a read only stream with the contents of the remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function write($source) {
 		$handle = $this->create($source);

src/Server.php

@@ -27,7 +27,7 @@ class Server {
 	protected $password;
 
 	/**
-	 * Check if the smblcient php extension is available
+	 * Check if the smbclient php extension is available
 	 *
 	 * @return bool
 	 */
@@ -76,6 +76,7 @@ class Server {
 
 	/**
 	 * @return \Icewind\SMB\IShare[]
+	 *
 	 * @throws \Icewind\SMB\AuthenticationException
 	 * @throws \Icewind\SMB\InvalidHostException
 	 */

src/Share.php

@@ -30,14 +30,18 @@ class Share implements IShare {
 	/**
 	 * @param Server $server
 	 * @param string $name
-	 * @throws ConnectionError
 	 */
 	public function __construct($server, $name) {
 		$this->server = $server;
 		$this->name = $name;
 	}
 
-	public function connect() {
+	/**
+	 * @throws \Icewind\SMB\ConnectionError
+	 * @throws \Icewind\SMB\AuthenticationException
+	 * @throws \Icewind\SMB\InvalidHostException
+	 */
+	protected function connect() {
 		if ($this->connection and $this->connection->isValid()) {
 			return;
 		}
@@ -88,6 +92,9 @@ class Share implements IShare {
 	 *
 	 * @param $path
 	 * @return array[]
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function dir($path) {
 		$path = $this->escapePath($path);
@@ -122,6 +129,9 @@ class Share implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
 	 */
 	public function mkdir($path) {
 		return $this->simpleCommand('mkdir', $path);
@@ -132,6 +142,9 @@ class Share implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function rmdir($path) {
 		return $this->simpleCommand('rmdir', $path);
@@ -142,6 +155,9 @@ class Share implements IShare {
 	 *
 	 * @param string $path
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function del($path) {
 		//del return a file not found error when trying to delete a folder
@@ -167,6 +183,9 @@ class Share implements IShare {
 	 * @param string $from
 	 * @param string $to
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\AlreadyExistsException
 	 */
 	public function rename($from, $to) {
 		$path1 = $this->escapePath($from);
@@ -182,6 +201,9 @@ class Share implements IShare {
 	 * @param string $source local file
 	 * @param string $target remove file
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function put($source, $target) {
 		$path1 = $this->escapeLocalPath($source); //first path is local, needs different escaping
@@ -196,6 +218,9 @@ class Share implements IShare {
 	 * @param string $source remove file
 	 * @param string $target local file
 	 * @return bool
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function get($source, $target) {
 		$path1 = $this->escapePath($source);
@@ -209,6 +234,9 @@ class Share implements IShare {
 	 *
 	 * @param string $source
 	 * @return resource a read only stream with the contents of the remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function read($source) {
 		$source = $this->escapePath($source);
@@ -230,6 +258,9 @@ class Share implements IShare {
 	 *
 	 * @param string $target
 	 * @return resource a write only stream to upload a remote file
+	 *
+	 * @throws \Icewind\SMB\NotFoundException
+	 * @throws \Icewind\SMB\InvalidTypeException
 	 */
 	public function write($target) {
 		$target = $this->escapePath($target);

tests/Share.php

@@ -133,7 +133,6 @@ class Share extends \PHPUnit_Framework_TestCase {
 
 		foreach ($names as $name) {
 			$this->share->mkdir($this->root . '/' . $name);
-			$this->share->connect();
 			$dir = $this->share->dir($this->root);
 			$this->assertArrayHasKey($name, $dir);
 			$this->assertEquals('dir', $dir[$name]['type']);