README

# Luna Module - SQL A PHP **SQL Module** designed for managing database access in the **Luna Framework**. **Robust**, **Flexible**, and **Developer-Friendly** - Simplifying SQL operations and data access in your PHP projects.

[[TOC]]

ℹ️ About the Project

This project is developed in PHP 8.2 and is part of the Luna Framework ecosystem.

The Luna SQL Module provides a structured way to handle SQL connections, execute queries, manage transactions, and build repositories for data access.

Detailed documentation is available in the Wiki: Luna Wiki.

Key Features

• Connection and Execution: Manage connections and execute SQL queries through a dedicated manager.
• Repository Pattern: Build repositories to encapsulate data access.
• Transactions: Orchestrate transactional workflows for safe database operations.
• Dependency Injection: Seamless integration with Luna’s DI for service wiring.
• PSR-4 Autoloading: Clean and autoloaded code structure.
• PHP 8.2 Features: Implements the latest PHP features, promoting clean, predictable code.

🔧 Dependencies

It uses PHP 8.2+, ensuring compatibility with modern features.

This module depends on the following:

• Luna Framework: The Luna framework's core. (MIT License)
• PHP extensions:
  • PDO (database access)
• Development tools:
  • PHPUnit

Refer to the composer.json file for additional details.

⚙️ Setup and Installation

To use the Luna SQL module, follow the steps below:

Step 1: Install via Composer

Ensure Composer is installed, then execute the following in your root project folder:

composer require shiros/luna-sql

Autoloading is handled by Composer (PSR‑4). When used within a Luna application, the module is auto‑discovered via composer.json → luna.module:

{
    "luna": {
        "module": "Luna\\SQL\\Module"
    }
}

Step 2: Autoload the Module

The module supports PSR-4 autoloading. If you're using the Luna Framework, it’s automatically available via the Luna module declaration. Otherwise, make sure to include Composer’s autoloader:

require 'vendor/autoload.php';

🚀 Usage Example

Refer to the official documentation for advanced examples and further details.

Configure a connection

Configure a connection to your database in the file config/storage/sql.
Here's a quick example of how to configure the SQL connection:

return [
    'Databases' => [
        'default' => [
            'driver'   => 'mysql',
            'host'     => 'localhost',
            'port'     => 3306,
            'database' => 'my_database',
            'username' => 'my_username',
            'password' => '*my_password*',
        ],
        
        // You can add as many connections as you want.
    ]
];

Execute a query

Here's a quick example of how to use the SQL manager to execute a query:

// Generate the SQL manager instance
$sqlManager = new SqlManager();

// Execute the query
$results = $sqlManager->execute(
    connection: 'default', // a configured connection name or a connection instance
    query     : 'SELECT * FROM users WHERE id = :id', 
    variables : ['id' => 42]
); 

// Output: The '$result' contains driver-specific data or a normalized result depending on your configuration.

Use a repository

Create a repository to encapsulate queries and reuse them across your application:

class UserRepository extends AbstractSQLRepository {
    /**
     * Find a user by its ID.
     * 
     * @param int $id
     * @return array|null
     */
    public function findById(int $id) : ?array {
        return $this->execute(
            connection: 'default', 
            query     : 'SELECT * FROM users WHERE id = :id',
            variables : ['id' => $id]
        );
    }
}

Note: Services and repositories can be wired through the DI configuration (see your config/services and DI module configuration).

📄 Testing

This project uses PHPUnit for testing, you can run the test suite as follows.

Step 1: Install development dependencies

Before running the test suite, ensure all project dependencies, including development dependencies, are installed. Use Composer to handle this:

composer install

This command will fetch all the required libraries and ensure your project setup is complete.

Step 2 (optional): Start local databases for real-connection tests

Most of the suite runs without any external service. A few tests in tests/Connection open a real connection against MySQL and PostgreSQL to validate SQLConnection end-to-end; when no database is reachable, these tests are skipped rather than failed.

See the Docker section below for the containerized flow that runs these tests against real databases.

Step 3: Execute the Test Suite

Once dependencies are installed, you can execute the test suite using PHPUnit.
This ensures all the functionality of the framework is working as expected:

vendor/bin/phpunit --configuration phpunit.xml --colors=always

The test results will be displayed in your console. Colored output simplifies understandièng the testing status:

• Green: Tests passed successfully.
• Red: Tests failed.
• Yellow: Warnings or skipped tests.

For more details on the tests, explore the /tests directory. It contains comprehensive unit tests covering various parts of the framework.

🐳 Docker

A Docker Compose setup is available under .docker/.

None of the services publish ports to the host; everything runs on Compose's internal network, so the suite is run through the php service.

Build the image

docker compose -f .docker/compose.yml build php

Run the test suite

docker compose -f .docker/compose.yml run --rm php vendor/bin/phpunit --configuration phpunit.xml --colors=always

The run automatically starts mysql/postgres as dependencies of php, so the real-connection tests in tests/Connection run against actual databases instead of being skipped. The php container reaches them over their service aliases, using the same SQL_TEST_* variable names GitLab CI injects (see .gitlab-ci.yml):

Variable	Value (docker-compose network)
SQL_TEST_MYSQL_HOST	mysql
SQL_TEST_MYSQL_PORT	3306
SQL_TEST_MYSQL_DATABASE	luna_test
SQL_TEST_MYSQL_USER	luna
SQL_TEST_MYSQL_PASSWORD	secret
SQL_TEST_POSTGRES_HOST	postgres
SQL_TEST_POSTGRES_PORT	5432
SQL_TEST_POSTGRES_DATABASE	luna_test
SQL_TEST_POSTGRES_USER	luna
SQL_TEST_POSTGRES_PASSWORD	secret

Update dependencies

The vendor/ is baked into the image at build time. If you change composer.json/composer.lock, either rebuild the image or run Composer inside the running dependency graph:

docker compose -f .docker/compose.yml run --rm php composer install

Stop the services

docker compose -f .docker/compose.yml down

📃 License

This project is licensed under the MIT License, allowing you to use and modify this project freely.
See the LICENSE file for more details.

👨‍💻 Authors and Contributors

This project was created and is maintained by Alexandre Caillot (Shiroe_sama), with contributions from the community.

Authors

• Alexandre Caillot (Shiroe_sama)

Contributors

We thank the following contributors for making this project better:

• Maxime Mazet (ElBidouilleur)