1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
SMB
===
[](https://github.com/icewind1991/SMB/actions/workflows/ci.yaml)
[](https://codecov.io/gh/icewind1991/SMB)
PHP wrapper for `smbclient` and [`libsmbclient-php`](https://github.com/eduardok/libsmbclient-php)
- Reuses a single `smbclient` instance for multiple requests
- Doesn't leak the password to the process list
- Simple 1-on-1 mapping of SMB commands
- A stream-based api to remove the need for temporary files
- Support for using libsmbclient directly trough [`libsmbclient-php`](https://github.com/eduardok/libsmbclient-php)
Examples
----
### Connect to a share ###
```php
<?php
use Icewind\SMB\ServerFactory;
use Icewind\SMB\BasicAuth;
require('vendor/autoload.php');
$serverFactory = new ServerFactory();
$auth = new BasicAuth('user', 'workgroup', 'password');
$server = $serverFactory->createServer('localhost', $auth);
$share = $server->getShare('test');
```
The server factory will automatically pick between the `smbclient` and `libsmbclient-php`
based backend depending on what is available.
### Using anonymous authentication ###
```php
$serverFactory = new ServerFactory();
$auth = new AnonymousAuth();
$server = $serverFactory->createServer('localhost', $auth);
```
### Using kerberos authentication ###
```php
$serverFactory = new ServerFactory();
$auth = new KerberosAuth();
$server = $serverFactory->createServer('localhost', $auth);
```
Note that this requires a valid kerberos ticket to already be available for php
### Upload a file ###
```php
$share->put($fileToUpload, 'example.txt');
```
### Download a file ###
```php
$share->get('example.txt', $target);
```
### List shares on the remote server ###
```php
$shares = $server->listShares();
foreach ($shares as $share) {
echo $share->getName() . "\n";
}
```
### List the content of a folder ###
```php
$content = $share->dir('test');
foreach ($content as $info) {
echo $info->getName() . "\n";
echo "\tsize :" . $info->getSize() . "\n";
}
```
### Using read streams
```php
$fh = $share->read('test.txt');
echo fread($fh, 4086);
fclose($fh);
```
### Using write streams
```php
$fh = $share->write('test.txt');
fwrite($fh, 'bar');
fclose($fh);
```
**Note**: write() will truncate your file to 0bytes. You may open a writeable stream with append() which will point
the cursor to the end of the file or create it if it does not exist yet. (append() is only compatible with libsmbclient-php)
```php
$fh = $share->append('test.txt');
fwrite($fh, 'bar');
fclose($fh);
```
### Using notify
```php
$share->notify('')->listen(function (\Icewind\SMB\Change $change) {
echo $change->getCode() . ': ' . $change->getPath() . "\n";
});
```
### Changing network timeouts
```php
$options = new Options();
$options->setTimeout(5);
$serverFactory = new ServerFactory($options);
```
### Setting protocol version
```php
$options = new Options();
$options->setMinProtocol(IOptions::PROTOCOL_SMB2);
$options->setMaxProtocol(IOptions::PROTOCOL_SMB3);
$serverFactory = new ServerFactory($options);
```
Note, setting the protocol version is not supported with php-smbclient version 1.0.1 or lower.
### Customizing system integration
The `smbclient` backend needs to get various information about the system it's running on to function
such as the paths of various binaries or the system timezone.
While the default logic for getting this information should work on most systems, it is possible to customize this behaviour.
In order to customize the integration you provide a custom implementation of `ITimezoneProvider` and/or `ISystem` and pass them as arguments to the `ServerFactory`.
## Testing SMB
Use the following steps to check if the library can connect to your SMB share.
1. Clone this repository or download the source as [zip](https://github.com/icewind1991/SMB/archive/master.zip)
2. Make sure [composer](https://getcomposer.org/) is installed
3. Run `composer install` in the root of the repository
4. Edit `example.php` with the relevant settings for your share.
5. Run `php example.php`
If everything works correctly then the contents of the share should be outputted.
|
