Skip to main content

​
Overview

This guide will walk you through pulling a docker-php-mssql image, running a container, and connecting to a Microsoft SQL Server database using PHP.
1

Pull the Docker Image

Choose the image variant that matches your needs. For this example, we’ll use the PHP 8.4 CLI Alpine image.
docker pull namoshek/php-mssql:8.4-cli-alpine
Alpine images are smaller and faster to download. Use Debian-based images if you need broader compatibility or specific tools.
Available image tags:
  • 8.4-cli-alpine / 8.4-fpm-alpine - Alpine Linux
  • 8.4-cli / 8.4-fpm - Debian Bookworm
  • 8.4-cli-alpine-swoole / 8.4-fpm-alpine-swoole - With Swoole extension
Replace 8.4 with 8.3, 8.2, or 8.1 for other PHP versions.
2

Run a Test Container

Start an interactive container to verify the installation:
docker run -it --rm namoshek/php-mssql:8.4-cli-alpine php -v
You should see output similar to:
PHP 8.4.x (cli) (built: ...) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.4.x, Copyright (c) Zend Technologies
    with Zend OPcache v8.4.x, Copyright (c), by Zend Technologies
3

Verify SQL Server Extensions

Check that the SQL Server extensions are installed:
docker run -it --rm namoshek/php-mssql:8.4-cli-alpine php -m | grep sqlsrv
Expected output:
pdo_sqlsrv
sqlsrv
4

Create a Test PHP Script

Create a simple PHP script to test the SQL Server connection. Save this as test-connection.php:
test-connection.php
<?php

// Configuration
$serverName = 'your-server.database.windows.net';
$database = 'your_database';
$username = 'your_username';
$password = 'your_password';

// Connection options
$connectionOptions = [
    'Database' => $database,
    'Uid' => $username,
    'PWD' => $password,
    'Encrypt' => true,
    'TrustServerCertificate' => false,
];

// Test connection using sqlsrv
echo "Testing sqlsrv connection...\n";
$conn = sqlsrv_connect($serverName, $connectionOptions);

if ($conn === false) {
    echo "Connection failed!\n";
    die(print_r(sqlsrv_errors(), true));
}

echo "✓ Successfully connected using sqlsrv!\n";
echo "Server version: " . sqlsrv_server_info($conn)['SQLServerVersion'] . "\n";

sqlsrv_close($conn);

// Test connection using PDO
echo "\nTesting PDO connection...\n";
try {
    $dsn = "sqlsrv:server={$serverName};Database={$database};Encrypt=yes;TrustServerCertificate=no";
    $pdo = new PDO($dsn, $username, $password);
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    
    echo "✓ Successfully connected using PDO!\n";
    
    // Test query
    $stmt = $pdo->query('SELECT @@VERSION AS version');
    $result = $stmt->fetch(PDO::FETCH_ASSOC);
    echo "Database version: " . substr($result['version'], 0, 50) . "...\n";
} catch (PDOException $e) {
    echo "Connection failed: " . $e->getMessage() . "\n";
}

echo "\nConnection test completed!\n";
Update the connection parameters with your actual SQL Server credentials before running the script.
5

Run the Test Script

Execute the script in a container:
docker run -it --rm \
  -v $(pwd)/test-connection.php:/var/www/test-connection.php \
  namoshek/php-mssql:8.4-cli-alpine \
  php /var/www/test-connection.php
Successful output will look like:
Testing sqlsrv connection...
✓ Successfully connected using sqlsrv!
Server version: 16.00.1000

Testing PDO connection...
✓ Successfully connected using PDO!
Database version: Microsoft SQL Server 2022 (RTM) - 16.0.1000.6...

Connection test completed!

​
Using with Docker Compose

For a complete application setup, use Docker Compose to orchestrate your PHP application and SQL Server database:
docker-compose.yml
version: '3.8'

services:
  app:
    image: namoshek/php-mssql:8.4-fpm-alpine
    volumes:
      - ./src:/var/www
    networks:
      - app-network
    environment:
      - DB_HOST=sqlserver
      - DB_DATABASE=myapp
      - DB_USERNAME=sa
      - DB_PASSWORD=YourStrong@Passw0rd

  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./src:/var/www
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    networks:
      - app-network
    depends_on:
      - app

  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong@Passw0rd
      - MSSQL_PID=Developer
    ports:
      - "1433:1433"
    networks:
      - app-network
    volumes:
      - sqlserver-data:/var/opt/mssql

networks:
  app-network:
    driver: bridge

volumes:
  sqlserver-data:
Never use default passwords like shown above in production. Always use strong, unique passwords and consider using Docker secrets or environment-specific configuration.

​
Connection Examples

Here are practical examples for common PHP frameworks and libraries: 
DB_CONNECTION=sqlsrv
DB_HOST=your-server.database.windows.net
DB_PORT=1433
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Optional: Customize connection options
DB_ENCRYPT=yes
DB_TRUST_SERVER_CERTIFICATE=false

​
Using in Dockerfile

Extend the base image to create your own custom application image:
Dockerfile
FROM namoshek/php-mssql:8.4-fpm-alpine

# Copy application files
COPY . /var/www

# Install application dependencies
RUN composer install --no-dev --optimize-autoloader

# Set proper permissions
RUN chown -R www-data:www-data /var/www/storage /var/www/bootstrap/cache

# Expose port (if needed)
EXPOSE 9000

CMD ["php-fpm"]
Build and run your custom image: 
docker build -t myapp:latest .
docker run -d -p 9000:9000 myapp:latest

​
Troubleshooting Common Issues

If you encounter SSL certificate errors, you may need to adjust encryption settings:
// For development/testing only - not recommended for production
$connectionOptions = [
    'TrustServerCertificate' => true,
    'Encrypt' => true,
];
For production, ensure your SQL Server has a valid SSL certificate.
Increase connection timeout values:
$connectionOptions = [
    'LoginTimeout' => 30,
    'ConnectRetryCount' => 3,
    'ConnectRetryInterval' => 10,
];
Ensure proper character set configuration:
// For sqlsrv
$connectionOptions['CharacterSet'] = 'UTF-8';

// For PDO
$dsn = "sqlsrv:server={$serverName};Database={$database};charset=UTF-8";
When connecting to Azure SQL Database:
$serverName = 'your-server.database.windows.net';
$connectionOptions = [
    'Database' => 'your_database',
    'Uid' => 'your_username@your-server',  // Note: include @server-name
    'PWD' => 'your_password',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
];

​
Next Steps

PHP Configuration

Learn how to customize PHP settings and optimize your container

Available Tags

Explore all available image tags and versions

Building Locally

Build your own custom images with additional tools and extensions

Image Variants

Compare Debian, Alpine, and Swoole image variants

Build docs developers (and LLMs) love

Get started for freeTalk to us