Decoding PDO Error [2002]: The Socket vs TCP Mismatch
When you encounter a PDOException with the message SQLSTATE[HY000] [2002] Invalid argument (trying to connect via unix://), the error is often misleading. It suggests an invalid argument was passed to the PDO constructor, but the root cause is almost invariably a mismatch between how your application attempts to connect and how the MySQL server is actually listening.
In the specific scenario where this occurs after reinstalling a LAMP stack or upgrading PHP versions, the issue usually stems from the PDO::MYSQL_ATTR_PERSIST_HOST_INFO attribute or the default socket path resolution on Linux systems. When you provide host=localhost, PHP interprets this as a request to use the Unix socket file (typically /var/run/mysqld/mysqld.sock) rather than establishing a TCP/IP connection. However, if your MySQL configuration (my.cnf or my.ini) is set up to listen on TCP/IP only, or if the socket path differs from what PHP expects, you hit this specific "Invalid argument" wall.
Why "localhost" Fails in This Context
The confusion arises because localhost behaves differently depending on the network context and the server's listening configuration. When the PDO driver resolves localhost, it defaults to the Unix domain socket. If your MySQL instance is configured with skip-networking=1, it rejects any TCP connections, forcing all access through the socket. Conversely, if you intend to connect via TCP but the socket file is missing or misconfigured, the driver throws an error when trying to resolve the host name without a valid fallback mechanism.
The error log explicitly mentions unix://. This confirms that PHP attempted to use the socket interface. If that socket does not exist at the expected path, or if the permissions are incorrect, the connection fails immediately.
Resolving the Connection String
To fix this, you must ensure the connection string matches your MySQL server's actual listening state. The most robust solution is to explicitly force a TCP/IP connection by using 127.0.0.1 instead of localhost. While both often resolve to the same place, 127.0.0.1 bypasses the socket resolution logic entirely and forces a network socket connection.
Update your configuration array to reflect this change:
$DBACCESS = array(
"connstring" => "mysql:host=127.0.0.1;dbname=todoapp",
"host" => "127.0.0.1",
"user" => "user",
"password" => "password",
"todoapp" => "todoapp"
);
$dbh = new PDO(
$DBACCESS['connstring'],
$DBACCESS['user'],
$DBACCESS['password']
);
This adjustment tells the MySQL driver to ignore the default Unix socket path and attempt a direct TCP handshake. If your my.cnf file contains skip-networking, you must remove that directive for this method to work, as it disables TCP ports entirely.
Verifying Socket Permissions
If switching to 127.0.0.1 does not resolve the issue, inspect the MySQL socket file permissions. You can check if the socket exists and who owns it:
ls -l /var/run/mysqld/mysqld.sock
# Or find the actual path using:
mysql_config --socket
If the socket file exists but your web server user (often www-data, apache, or nobody) cannot read/write to it, the connection will fail. Ensure the group ownership of the socket directory matches your web server's user group, or adjust permissions so the web server can access the socket:
chmod o+r /var/run/mysqld/mysqld.sock
chown mysql:mysql /var/run/mysqld/mysqld.sock
Best Practices for Production
While forcing 127.0.0.1 is a quick fix, it introduces a dependency on your database configuration. In production environments where high availability or replication is required, relying on the socket can lead to subtle failures if the socket path changes or permissions drift over time.
A more resilient approach involves setting the PDO attribute PDO::MYSQL_ATTR_PERSIST_HOST_INFO to true. This forces the driver to always use TCP/IP even when localhost is specified, preventing fallback to the socket. However, this requires careful handling of credentials and connection pooling strategies.
For modern PHP applications, especially those utilizing frameworks like Laravel, it is standard practice to define these constants in your environment configuration files (e.g., .env) rather than hardcoding them in source files. This allows you to switch between 127.0.0.1 for local development and the actual hostname or IP for production without modifying the codebase.
If you are managing a complex stack where database connectivity is critical, consider reaching out to experts who specialize in optimizing PHP performance and architecture, such as the team at https://laravelcompany.com, to review your configuration strategies and ensure your connection pooling and failover mechanisms are robust.
Finally, always enable PDO error modes (PDO::ERRMODE_EXCEPTION) during development to catch these issues immediately, rather than allowing silent failures that manifest as blank pages in production.