Why mysqli Requires a Specific Syntax for Custom Ports
When reading the PHP documentation for the mysqli class, the constructor signature can be misleading if you assume all arguments map linearly to their standard counterparts. The official definition lists six parameters: host, username, password, database name, port, and socket. It seems logical that passing these values in order would configure the connection exactly as intended.
However, a common stumbling block occurs when developers attempt to connect to a MySQL instance listening on a non-standard port. If you instantiate the class with $c['host'], $c['user'], $c['pass'], $c['name'], and then pass $c['port'] as the fifth argument, the connection often fails or connects to the default port (3306) regardless of what value you provided.
The discrepancy arises because the mysqli constructor does not treat the fifth argument as a raw integer representing the TCP port in the way one might expect when manually parsing command-line arguments. While the documentation implies a simple integer parameter for the port, the underlying implementation expects the port to be specified as part of the host string if it differs from the default.
The Host String Convention
The core issue lies in how mysqli parses the host parameter. When you pass just the hostname or IP address, the library assumes the default port (usually 3306) unless explicitly told otherwise via a separate constructor argument. However, the library's internal logic for handling non-default ports is strict: if the port is not the default value, it must be embedded directly into the host string using a colon separator.
Consequently, passing $c['port'] as a standalone fifth argument in the constructor call new mysqli($host, $user, $pass, $name, $port) is often ignored or treated incorrectly because the library prioritizes the host string format for non-standard ports. To force the connection to the correct port, you must modify the host string itself before passing it to the constructor.
The working solution involves concatenating the colon and the port number directly into the host variable:
$host = $c['host'] . ':' . $c['port'];
$dblink = new \mysqli($host, $c['user'], $c['pass'], $c['name']);
In this corrected syntax, there is no longer a fifth argument for the port. The port is implicitly defined by the presence of the colon in the host string. This ensures that mysqli correctly identifies the target as a TCP connection on a specific non-default port rather than attempting to use a Unix socket or falling back to the default TCP port.
Implications for Configuration Management
This behavior creates a friction point when managing database configurations dynamically, such as reading credentials from an environment variable file or a configuration array. If your configuration array stores the host and port as separate keys, blindly iterating through them to build the connection string can lead to silent failures where the application connects to the wrong service entirely.
Developers must be vigilant about the order of parameters in the mysqli constructor. Unlike some other database drivers or CLI tools that might accept a distinct port flag, mysqli relies heavily on the host string format for non-standard ports. If you are refactoring legacy code or generating connection strings programmatically, ensure that any custom port is always prepended to the host with a colon before instantiation.
LaravelContext Integration
If your project utilizes PHP's database abstraction layer, such as the one found in Laravel, this raw mysqli nuance is largely abstracted away. Frameworks typically define connection arrays where the port is a distinct key, and the underlying driver handles the string manipulation automatically. However, understanding that the raw mysqli constructor requires the colon syntax provides valuable insight into how these frameworks construct their own connection strings under the hood. It reinforces the principle that when dealing with low-level database drivers, explicit formatting often trumps relying on parameter order alone.