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

This module depends on the following:

PHP >= 8.2 with ext-curl enabled
Luna Framework ^4.6
Developer tools for testing:
- PHPUnit ^9.5

Refer to the composer.json file for additional details.

⚙️ 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

Here's a quick example of how to use the Curl class to perform an 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);

Here's a quick example of how to use the JSONCurl class perform an 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);

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();
}

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

📄 Testing

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

Install development dependencies :
```
composer install
```

Execute the test suite :

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

You can explore unit tests in the /tests directory.

📃 License

This project is released under the MIT License.
For details, review the LICENSE file.

👨‍💻 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

Details