Easysql Sdk Laravel Package

Getting Started

1. Install the package:

   composer require clearsoft-net/easysql-php
   

2. If the package publishes configuration, publish it and review the connector settings:

   php artisan vendor:publish --tag=easysql-config
   

3. Configure a MySQL or PostgreSQL connection. As of v4.1.0, both connectors support Unix sockets, so you can point the connection at a local socket instead of a TCP host/port.

   Example MySQL socket configuration:

   // config/easysql.php or config/database.php, depending on package wiring
   'mysql' => [
       'driver' => 'mysql',
       'socket' => env('DB_SOCKET', '/var/run/mysqld/mysqld.sock'),
       // host/port can be omitted when using a socket
   ],
   

   Example PostgreSQL socket configuration:

   'pgsql' => [
       'driver' => 'pgsql',
       'socket' => env('DB_SOCKET', '/var/run/postgresql'),
       // host/port can be omitted when using a socket
   ],
   

4. First use case: connect through the local socket and run a simple query through the package’s normal API. This is most useful in local development, Docker/CI setups, or managed environments where TCP is disabled but a Unix socket is available.

Implementation Patterns

• Use sockets for local and containerized databases. Configure DB_SOCKET per environment and let the package’s MySQL/PostgreSQL connector consume it. This avoids hard-coding host/port values that differ between host and container.

• Keep environment-specific connection configs separate. For example:

  • Local: Unix socket
  • CI: Unix socket mounted into the job container
  • Production: TCP host/port, unless your provider exposes a socket

• Prefer a single connection factory/service. Wrap package usage in a small service class so connection selection stays out of controllers and jobs:

  final class ReportingConnection
  {
      public function __construct(private EasySql $db) {}
  
      public function dailyTotals(): array
      {
          return $this->db->connection('mysql')->select(/* ... */);
      }
  }
  

• Use socket support for read-only/local tooling. Reporting scripts, seeders, and local test fixtures can use the socket connection without changing application-level query code.

• Validate socket connectivity in deployment scripts. Add a quick check before running migrations or queue workers:

  php -r "new PDO('mysql:unix_socket=/var/run/mysqld/mysqld.sock;dbname=test', 'user', 'pass');"
  

• Keep TCP fallback available. If your config supports both, resolve socket first and fall back to host/port. This helps when a developer runs the app outside Docker.

Gotchas and Tips

• Socket path must be readable by the PHP process user. Permission errors often look like connection refused or “No such file or directory.” Check ownership and mode on the socket file and its parent directory.

• Do not set both socket and host/port unless the connector explicitly supports precedence. Many PDO drivers ignore host/port when a socket is supplied, but behavior can vary. Pick one transport per connection.

• Docker paths are container-local. A socket path that works on the host will not automatically work inside a container. Mount the socket or use the container’s own path, e.g. /var/run/mysqld/mysqld.sock.

• PostgreSQL socket configs often use a directory, not a file. The default is commonly /var/run/postgresql; MySQL typically uses a .sock file. Confirm the expected value for your platform.

• Clear Laravel config cache after changing socket settings:

  php artisan config:clear
  php artisan config:cache
  

• Check the PHP PDO extensions. Socket support depends on pdo_mysql / pdo_pgsql being installed and enabled:

  php -m | grep -E 'pdo_mysql|pdo_pgsql'
  

• Test both transports if you support them. A passing TCP test does not prove socket configuration works. Add a smoke test that opens the socket connection and runs SELECT 1.

• v4.1.0 is additive. The Unix socket feature is not a breaking change. Existing TCP-based configurations should continue to work; no migration is required unless you want to adopt socket connections.

• Debug with the underlying PDO exception. If the package wraps exceptions, log the previous exception message. Socket failures usually surface as PDO connection errors with path-specific details.