vmvarela/smbwebclient

Modern PHP 8 SMB/CIFS web client using icewind/smb library

v3.0.0 2025-12-10 13:00 UTC

Requires

• php: ^8.2
• icewind/smb: ^3.7
• vlucas/phpdotenv: ^5.6

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11

MIT

• Victor M. Varela

README

SMB Web Client

A modern PHP 8 web-based file browser for SMB/CIFS network shares, powered by FrankenPHP and the icewind/smb library.

Features

• 🚀 PHP 8.2+ with modern syntax (typed properties, constructor promotion, strict typing)
• 🔥 FrankenPHP powered by Go and Caddy for high performance
• 📦 icewind/smb library for native SMB/CIFS support
• 🎨 Multiple themes (Windows, macOS, Ubuntu)
• 🔒 Session-based authentication with credential management
• 🌍 Multi-language support (40+ languages with auto-detection)
• 📁 File operations: upload, download, create folders, delete, rename
• 🖱️ Drag & drop file uploads
• 🔄 Sortable columns (name, size, date, type)
• 🐳 Docker ready with docker-compose

Requirements

• PHP 8.2 or higher
• libsmbclient library and PHP extension
• Composer

Quick Start with Docker

Using GitHub Container Registry (Recommended)

# Pull the image
docker pull ghcr.io/vmvarela/smbwebclient:latest

# Run with environment variables
docker run -d \
  -p 8080:80 \
  -e SMB_DEFAULT_SERVER=your-smb-server \
  ghcr.io/vmvarela/smbwebclient:latest

# Access at http://localhost:8080

Using Docker Compose

Create a docker-compose.yml file:

services:
  smbwebclient:
    image: ghcr.io/vmvarela/smbwebclient:latest
    ports:
      - "8080:80"
    volumes:
      - ./.env:/app/.env:ro
    environment:
      - SERVER_NAME=:80
    restart: unless-stopped

Then run:

# Create your .env file
cat > .env << EOF
SMB_DEFAULT_SERVER=your-smb-server
SMB_HIDE_SYSTEM_SHARES=true
APP_DEFAULT_LANGUAGE=en
EOF

# Start the container
docker-compose up -d

# Access at http://localhost:8080

Building from Source

# Clone the repository
git clone https://github.com/vmvarela/smbwebclient.git
cd smbwebclient

# Copy and configure environment
cp .env.example .env
# Edit .env with your SMB server settings

# Start with Docker Compose
docker-compose up -d

# Access at http://localhost:8080

Manual Installation

1. Install dependencies:

composer install

1. Configure environment:

cp .env.example .env
# Edit .env with your settings

1. Run with FrankenPHP:

frankenphp run --config Caddyfile

Or use PHP's built-in server for development:

php -S localhost:8080 -t public

Using as a Composer Package

You can integrate SMB Web Client into your own PHP application:

Installation

composer require vmvarela/smbwebclient

Basic Usage

<?php

require 'vendor/autoload.php';

use SmbWebClient\Config;
use SmbWebClient\SmbClient;

// Create configuration
$config = new Config(
    smbDefaultServer: 'your-smb-server',
    hideSystemShares: true,
    hideDotFiles: true,
);

// Create client with credentials
$client = new SmbClient($config, 'username', 'password');

// List available shares
$shares = $client->listShares('your-smb-server');
foreach ($shares as $share) {
    echo $share->getName() . "\n";
}

// List directory contents
$files = $client->listDirectory('your-smb-server', 'ShareName', '/path/to/folder');
foreach ($files as $file) {
    echo sprintf("%s - %s (%d bytes)\n", 
        $file->isDirectory() ? 'DIR' : 'FILE',
        $file->getName(),
        $file->getSize()
    );
}

// Download a file
$localPath = '/local/path/to/file.txt';
$client->downloadFile('your-smb-server', 'ShareName', '/remote/file.txt', $localPath);
echo file_get_contents($localPath);

// Upload a file
$client->uploadFile('your-smb-server', 'ShareName', '/remote/path', '/local/file.txt');

// Create a directory
$client->createDirectory('your-smb-server', 'ShareName', '/new/folder');
// Delete a file
$client->deleteFile('your-smb-server', 'ShareName', '/path/to/file.txt');
// Delete a directory
$client->deleteDirectory('your-smb-server', 'ShareName', '/path/to/folder');
// Rename/move a file
$client->rename('your-smb-server', 'ShareName', '/old/name.txt', '/new/name.txt');

Anonymous Access

// For anonymous/guest access, omit credentials
$client = new SmbClient($config);

// Or explicitly pass null
$client = new SmbClient($config, null, null);

Using Environment Variables

<?php

require 'vendor/autoload.php';

use Dotenv\Dotenv;
use SmbWebClient\Config;
use SmbWebClient\SmbClient;

// Load .env file
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();

// Create config from environment
$config = Config::fromEnv();

// Use the client
$client = new SmbClient($config, $_ENV['SMB_USER'] ?? null, $_ENV['SMB_PASS'] ?? null);

Requirements

When using as a library, ensure you have:

• PHP 8.2+
• libsmbclient system library
• PHP smbclient extension (pecl install smbclient)

On Debian/Ubuntu:

apt-get install libsmbclient-dev smbclient
pecl install smbclient

On macOS:

brew install samba
pecl install smbclient

Configuration

All configuration is managed through environment variables in the .env file:

SMB Settings

Variable	Description	Default
SMB_DEFAULT_SERVER	Default SMB server hostname	localhost
SMB_SERVER_LIST	Comma-separated list of allowed servers	(empty)
SMB_ROOT_PATH	Root path to restrict navigation (e.g., /server/share)	(empty)
SMB_HIDE_DOT_FILES	Hide files starting with dot	true
SMB_HIDE_SYSTEM_SHARES	Hide system shares (C$, ADMIN$, IPC$)	true
SMB_HIDE_PRINTER_SHARES	Hide printer shares	false

Application Settings

Variable	Description	Default
APP_DEFAULT_LANGUAGE	Default UI language	en
APP_DEFAULT_CHARSET	Character encoding	UTF-8
APP_CACHE_PATH	Directory for temporary files	(empty)
APP_SESSION_NAME	Custom session cookie name	SMBWebClientID
APP_ALLOW_ANONYMOUS	Allow anonymous access	false
APP_MOD_REWRITE	Enable clean URLs	false
APP_BASE_URL	Base URL for clean URLs	(empty)

Other Settings

Variable	Description	Default
LOG_LEVEL	Logging verbosity (0-3)	0
LOG_FACILITY	Syslog facility	LOG_DAEMON

Supported Languages

The application supports automatic language detection and includes translations for:

af, ar, az, bg, bs, ca, cs, da, de, el, en, eo, es, et, eu, fa, fi, fr, gl, he, hi, hr, hu, id, it, ja, ko, ka, lt, lv, ms, nl, no, pl, pt, pt-br, ro, ru, sk, sl, sq, sr, sv, th, tr, uk, zh, zh-tw

Available Themes

• Windows - Classic Windows Explorer style
• macOS - Apple Finder style
• Ubuntu - Nautilus file manager style

Architecture

├── public/
│   ├── index.php          # Application entry point
│   └── assets/            # CSS, images
├── src/
│   ├── Application.php    # Main application controller
│   ├── Config.php         # Configuration management
│   ├── SmbClient.php      # SMB operations wrapper
│   ├── Session.php        # Session and authentication
│   └── Translator.php     # Multi-language support
├── cache/                 # Temporary files (ZIP downloads)
├── .env                   # Configuration file
├── Caddyfile              # FrankenPHP/Caddy config
├── Dockerfile             # FrankenPHP container
└── docker-compose.yml     # Docker Compose setup

Docker Compose Services

The included docker-compose.yml provides:

• smbwebclient: Main application on port 8080
• samba1: Test Samba server with sample shares
• samba2: Additional test Samba server

Test credentials for Samba servers: user / pass

Development

# Install dependencies
composer install

# Run development server
php -S localhost:8080 -t public

# Static analysis
vendor/bin/phpstan analyse src

Code Standards

• PSR-4 autoloading
• PSR-12 coding style
• Strict typing enabled
• PHP 8.2+ features (constructor promotion, match expressions, named arguments)

License

MIT License - Copyright (c) 2003-2025 Victor M. Varela

See LICENSE file for details.

Author

Victor M. Varela [e-mail]

Troubleshooting

Connection Issues

• Verify SMB_DEFAULT_SERVER is accessible from the container/server
• Check that credentials have appropriate permissions
• Ensure libsmbclient and PHP smbclient extension are installed

Permission Issues

• Ensure the cache directory is writable
• Check SMB share permissions for the authenticating user

Performance Tips

• Use FrankenPHP for best performance
• Enable OPcache in production
• Consider using SMB_ROOT_PATH to limit browsing scope