shiros / luna-sql
Luna Module - SQL
Requires
- php: >=8.2
- ext-pdo: *
- shiros/luna: ^4.8
Requires (Dev)
- composer/composer: ^2.8
- phpunit/phpunit: ^9.5
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 SQL 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:
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
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(
connexion: 'default', // a configured connection name or a connexion 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(
connexion: '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: 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.
📃 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
Contributors
We thank the following contributors for making this project better: