icewind / smb
php wrapper for smbclient and libsmbclient-php
Installs: 730 489
Dependents: 4
Suggesters: 0
Security: 0
Stars: 135
Watchers: 15
Forks: 53
Open Issues: 35
Requires
- php: >=7.2
- icewind/streams: >=0.7.3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.16
- phpstan/phpstan: ^0.12.57
- phpunit/phpunit: ^8.5|^9.3.8
- psalm/phar: ^4.3
- dev-master
- v3.6.0
- v3.5.4
- v3.5.3
- v3.5.2
- v3.5.1
- v3.5.0
- v3.4.1
- v3.4.0
- v3.3.1
- v3.3.0
- v3.2.7
- v3.2.6
- v3.2.5
- v3.2.4
- v3.2.3
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.2
- v3.0.1
- v3.0.0
- v2.0.7
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.3a
- 1.0.2
- v1.0.1
- v1.0.0
- dev-kerberos-tickets
This package is auto-updated.
Last update: 2024-11-05 15:34:10 UTC
README
SMB
PHP wrapper for smbclient
and 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
Examples
Connect to a share
<?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
$serverFactory = new ServerFactory(); $auth = new AnonymousAuth(); $server = $serverFactory->createServer('localhost', $auth);
Using kerberos authentication
There are two ways of using kerberos to authenticate against the smb server:
- Using a ticket from the php server
- Re-using a ticket send by the client
Using a server ticket
Using a server ticket allows the web server to authenticate against the smb server using an existing machine account.
The ticket needs to be available in the environment of the php process.
$serverFactory = new ServerFactory(); $auth = new KerberosAuth(); $server = $serverFactory->createServer('localhost', $auth);
Re-using a client ticket
By re-using a client ticket you can create a single sign-on setup where the user authenticates against the web service using kerberos. And the web server can forward that ticket to the smb server, allowing it to act on the behalf of the user without requiring the user to enter his password.
The setup for such a system is fairly involved and requires roughly the following this
- The web server is authenticated against kerberos with a machine account
- Delegation is enabled for the web server's machine account
- The web server is setup to perform kerberos authentication and save the ticket in it's environment
- Php has the krb5 extension installed
- The client authenticates using a ticket with forwarding enabled
$serverFactory = new ServerFactory(); $auth = new KerberosAuth(); $auth->setTicket(KerberosTicket::fromEnv()); $server = $serverFactory->createServer('localhost', $auth);
Upload a file
$share->put($fileToUpload, 'example.txt');
Download a file
$share->get('example.txt', $target);
List shares on the remote server
$shares = $server->listShares(); foreach ($shares as $share) { echo $share->getName() . "\n"; }
List the content of a folder
$content = $share->dir('test'); foreach ($content as $info) { echo $info->getName() . "\n"; echo "\tsize :" . $info->getSize() . "\n"; }
Using read streams
$fh = $share->read('test.txt'); echo fread($fh, 4086); fclose($fh);
Using write streams
$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)
$fh = $share->append('test.txt'); fwrite($fh, 'bar'); fclose($fh);
Using notify
$share->notify('')->listen(function (\Icewind\SMB\Change $change) { echo $change->getCode() . ': ' . $change->getPath() . "\n"; });
Changing network timeouts
$options = new Options(); $options->setTimeout(5); $serverFactory = new ServerFactory($options);
Setting protocol version
$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.
- Clone this repository or download the source as zip
- Make sure composer is installed
- Run
composer install
in the root of the repository - Edit
example.php
with the relevant settings for your share. - Run
php example.php
If everything works correctly then the contents of the share should be outputted.