The Illusion of UTF-8 in FreeTDS and MSSQL
You are encountering a fundamental misunderstanding of how data encoding works within the FreeTDS extension. Setting mssql.charset to UTF-8 does not magically convert binary streams into Unicode characters on the fly. The directive you are setting controls the character set used for client-side conversion between the protocol wire format and your PHP variables, but only if the underlying connection actually supports that charset negotiation.
In many legacy FreeTDS configurations, the default behavior is to use the SQL Server's native code page (often Windows-1252 or a specific regional setting) rather than UTF-8. When you set client charset = UTF-8 in your .freetds.conf, you are instructing the client library to expect UTF-8 data, but if the server is still sending binary data based on its configured code page, you will encounter garbled text or mojibake. The mismatch happens because the driver attempts to interpret the incoming bytes as UTF-8, while the server sent them as Latin-1.
To resolve this without switching to PDO or SQLSRV, you must ensure that the connection is explicitly established using UTF-8 before any data is exchanged. The mssql_connect function alone does not guarantee a UTF-8 session; it relies on the FreeTDS library configuration and the server's capabilities.
Explicitly Enabling Unicode Support
The most reliable method to force UTF-8 support with FreeTDS is to enable the client charset directive in your global or connection-specific FreeTDS configuration file. If you are using a custom .freetds.conf, ensure the [global] section explicitly sets this:
[global]
client charset = UTF-8
However, simply editing the config file is not always enough if the environment variable TDSCONFIG is not pointing to it, or if the application server overwrites these settings via php.ini. You verified with php -i that mssql.charset has "no value", which suggests your PHP configuration isn't overriding the FreeTDS default.
When using ini_set('mssql.charset', 'UTF-8'), you are setting a specific directive for the current request, but this only works if the FreeTDS library version supports it and if the connection is not already established with a different charset. If your code establishes the connection via mssql_connect immediately after setting the ini value, ensure that the extension actually picks up that runtime setting before opening the socket.
Server-Side Code Page Constraints
Even with the client configured for UTF-8, SQL Server itself must be willing to send UTF-8 data. By default, legacy SQL Server instances often operate in a specific code page (e.g., 1252) unless explicitly told otherwise. If your database columns are stored using NVARCHAR, the server will store Unicode data, but it might still transmit it using the active connection code page.
To verify this, check the current code page of your connection after connecting:
$resource = mssql_connect($config['servername'], $config['username'], $config['password']);
// Check the current charset
if (mssql_query("SELECT @@CONNECTIONPROPERTY('client_encoding') AS encoding", $resource)) {
$result = mssql_fetch_assoc($resource);
// Note: This property might not be available depending on FreeTDS version
}
If the server is configured to use a non-UTF-8 code page, it may strip high-bit characters or convert them. You must ensure that the SQL Server instance is set to use UTF-8 (or at least supports Unicode data retrieval). This often requires setting the database collation appropriately or ensuring that the connection string parameters passed to mssql_connect include any necessary charset flags supported by your specific FreeTDS build.
The Limitation of mssql_charset Directive
One critical detail often missed is that the mssql.charset directive in PHP's php.ini might be ignored if the FreeTDS library was compiled without support for dynamic charset switching, or if the connection is established before the extension reads the ini file. In some environments, the order of operations matters: you must set the charset before calling mssql_connect.
If you are running in a shared hosting environment where you cannot edit .freetds.conf or php.ini, your options are severely limited. You may need to rely on the server administrator to configure the FreeTDS library globally with client charset = UTF-8 and ensure that no conflicting settings exist in the Apache/Nginx configuration files.
Why This Matters for Legacy Codebases
For many applications, migrating from the old mssql_* functions to PDO is the "correct" modern solution. However, when legacy constraints prevent such a move, understanding these low-level details becomes vital. The issue isn't just about setting a variable; it's about ensuring the entire data pathâfrom the SQL Server's wire protocol to the PHP memory spaceâis speaking the same encoding language. Without alignment at both ends, data corruption is inevitable, regardless of how many ini_set calls you throw at the problem.