README

# Luna Module - Curl A PHP **Curl Module** designed for enhancing HTTP request management in the **Luna Framework**. **Lightweight**, **Flexible**, and **OOP-focused** - Simplifying your curl operations in PHP.

[[TOC]]

ℹ️ About the Project

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

The Luna Curl Module facilitates Curl integration by encapsulating PHP's native curl methods in an Object-Oriented Programming (OOP) approach. This enables structured and reusable Curl workflows.

Detailed documentation is available in the Wiki: Luna Wiki.

Key Features

OOP Curl Management: Encapsulates PHP Curl functions into an ease-of-use wrapper.
Error Handling: Custom exception classes streamline error detection and debugging.
Reusable Design: Define and reuse Curl configurations easily.
PSR-4 Autoloading: Clean and autoloaded code structure.
PHP 8.2 Typed Syntax: Leverages the latest PHP features, promoting clean and maintainable code.

🔧 Dependencies

It uses PHP 8.2+, ensuring support for the latest features, and requires minimal setup to get started.

This module depends on the following:

Luna Framework: The Luna framework's core. (MIT License)
Development tools:
- PHPUnit

Refer to the composer.json file for additional details.

🤖 AI Assistance

This project's .claude/CLAUDE.md only contains repository-specific overrides. The generic Luna rules (repository conventions, documentation, unit tests, releases, refactoring) are provided by the luna-agent sub-agent and its luna-* skills, maintained separately and installed globally:

shiros/ai/luna-agent

⚙️ Setup and Installation

To use the Luna Curl module in your project, follow these steps:

Step 1: Install via Composer

First, ensure you have Composer installed in your system.
Run the following command in your project's root directory:

composer require shiros/luna-curl

Step 2: Ensure PHP Dependencies Are Met

Ensure your installation has Curl support enabled in PHP. Check by running:

php -m | grep curl

If not installed, refer to the PHP Manual to enable it based on your OS.

Step 3: Autoload the Module

The module supports PSR-4 autoloading. If you're using the Luna Framework, it's automatically available. 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.

Handling Curl request

Here's a quick example of how to use the Curl class to perform a Curl request :

// Create the curl instance
$curl = new Curl();

// Create the request
$request = new \Luna\Curl\Entity\CurlRequest(
    url    : 'http://api.example.com',
    method : \Luna\Curl\Entity\CurlMethod::GET,
    headers: [ 'Authorization' => 'Bearer <TOKEN>' ],
    options: [ 
        CURLOPT_TIMEOUT => 30 * 60 // Timeout of 30 min
    ]
);

/**
 * Execute the request and get a response.
 * 
 * To avoid the request's creation, you could use shortcut and call these methods instead.
 * - get(url, headers, options)
 * - post(url, data, headers, options)
 * - put(url, data, headers, options)
 * - patch(url, data, headers, options)
 * - delete(url, data, headers, options)
 */
$response = $curl->request(request: $request);

Handling JSON request

Here's a quick example of how to use the JSONCurl class perform a Curl request :

// Create the curl instance
$curl = new Curl();

// Create the request
$request = new \Luna\Curl\Entity\CurlRequest(
    url    : 'http://api.example.com',
    method : \Luna\Curl\Entity\CurlMethod::POST,
    data   : [
        'firstname' => 'Alexandre',
        'lastname'  => 'Caillot'
    ],
    headers: [ 'Authorization' => 'Bearer <TOKEN>' ],
    options: [ 
        CURLOPT_TIMEOUT => 30 * 60 // Timeout of 30 min
    ]
);

/**
 * Execute the request and get a response.
 * 
 * To avoid the request's creation, you could use shortcut and call these methods instead.
 * - get(url, headers, options)
 * - post(url, data, headers, options)
 * - put(url, data, headers, options)
 * - patch(url, data, headers, options)
 * - delete(url, data, headers, options)
 */
$response = $curl->request(request: $request);

Curl as OOP

Here's a quick example of how to use the CurlWrapper class to initiate, execute, and close a curl request :

// Create the wrapper
$wrapper = new CurlWrapper(url: $url);

try {
    // Initialize & execute curl request
    $response = $wrapper
     ->init()
     ->execute()
    ;
    // You can access the handle later using '$wrapper->getHandle()'.
    
    // Get response's information
    $information = $wrapper->getInformation();
    $error       = $wrapper->getError();

   // Logs data
   var_dump($response);
   var_dump($information);
   var_dump($error);
} catch (Throwable $throwable) {
    echo "Error: " . $throwable->getMessage() . PHP_EOL;
} finally {
    // Close the curl instance
    $wrapper->close();
}

📄 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: Create the test environment file

The test suite reads its environment from the path configured as ENV_PATH in phpunit.xml (./env.test, extension auto-detected). This file isn't committed, so create it locally by copying the committed template env.php.dist:

cp env.php.dist env.test.php

The env.php.dist file contains %TOKEN%-style placeholders (e.g. %LUNA_ENV%) that are resolved from system environment variables at runtime.

From there, you have two options:

Use system environment variables (recommended, matches what CI does) — export the tokens referenced by env.test.php before running the tests:
```
export LUNA_ENV=test
```
Edit the copy directly — replace the placeholder (s) in env.test.php with a literal value, e.g. 'Environment' => '%LUNA_ENV%' becomes 'Environment' => 'test'. Since env.test.php is a local, untracked copy, this never risks committing the value.

The CI pipeline runs the exact same copy step, with LUNA_ENV (and any future token) declared as a CI/CD variable. This keeps the pipeline script immutable — the only file to maintain when adding a new environment key (or secret) is env.php.dist.

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 understanding 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

Alexandre Caillot (Shiroe_sama)

Contributors

We thank the following contributors for making this project better:

Maxime Mazet (ElBidouilleur)

shiros / luna-curl

Maintainers

Package info

Statistics

Security