README

A powerful, lightweight PHP library for making HTTP/HTTPS requests with a simple, elegant API. Built on top of cURL with full PSR-7 compliance, security-first design, and comprehensive error handling.

Developed by Broos Action - Your trusted partner for API development, cloud services, and digital transformation solutions.

📋 Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Basic Usage
• Advanced Features
• API Reference
• Security
• Error Handling
• Contributing
• Support
• License

✨ Features

• 🔒 Secure by Default - SSL verification enabled, includes CA certificate bundle
• 🚀 Simple & Elegant API - Intuitive static methods for all HTTP operations
• 📦 PSR-7 Compliant - Full implementation of PSR-7 HTTP message interfaces
• 🔄 Automatic JSON Handling - Seamless JSON encoding/decoding
• 🌐 Comprehensive HTTP Support - All standard methods plus WebDAV extensions
• 🔐 Authentication Built-in - Basic, Digest, NTLM authentication support
• 🔌 Proxy Support - HTTP, SOCKS4, SOCKS5 proxy configuration
• 🍪 Cookie Management - Persistent cookie storage and handling
• 📤 File Uploads - Easy multipart file upload support
• 🎯 UTF-8 URL Handling - Proper internationalized domain name (IDN) support
• ⚡ Performance Optimized - Efficient request handling with cURL
• 📊 Detailed Response Info - Access to all cURL transfer information

📋 Requirements

• PHP: >= 7.4
• Extensions:
  • ext-curl (required)
  • ext-json (required)
  • ext-pcre (required)
  • ext-openssl (recommended for HTTPS)

📥 Installation

Via Composer (Recommended)

composer require broosaction/php-https

Manual Installation

1. Download the library
2. Include the autoloader in your project:

require_once 'vendor/autoload.php';

🚀 Quick Start

<?php

use Https\Target\Request;
use Https\Target\Request\Body;

// Simple GET request
$response = Request::get('https://api.example.com/users');
echo $response->code;        // 200
print_r($response->body);    // Parsed response body

// POST with JSON
$headers = ['Content-Type' => 'application/json'];
$body = Body::Json(['name' => 'John Doe', 'email' => 'john@example.com']);
$response = Request::post('https://api.example.com/users', $headers, $body);

// Check response
if ($response->code === 200) {
    echo "Success!";
}

📖 Basic Usage

Making GET Requests

use Https\Target\Request;

// Simple GET
$response = Request::get('https://api.example.com/data');

// GET with headers
$headers = [
    'Authorization' => 'Bearer YOUR_TOKEN',
    'Accept' => 'application/json'
];
$response = Request::get('https://api.example.com/data', $headers);

// GET with query parameters
$params = ['page' => 1, 'limit' => 10];
$response = Request::get('https://api.example.com/data', [], $params);

Making POST Requests

use Https\Target\Request;
use Https\Target\Request\Body;

// POST with JSON body
$headers = [
    'Authorization' => 'Bearer YOUR_API_KEY',
    'Content-Type' => 'application/json'
];

$body = Body::Json([
    'transactionName' => 'Payment',
    'amount' => 100.00,
    'currency' => 'USD',
    'customerEmail' => 'customer@example.com',
    'customerPhone' => '+1234567890',
    'metadata' => ['order_id' => '12345']
]);

$response = Request::post('https://api.example.com/payments', $headers, $body);

// Parse response
$result = json_decode($response->getRawBody(), true);

Making PUT/PATCH Requests

// Update resource with PUT
$body = Body::Json(['name' => 'Updated Name']);
$response = Request::put('https://api.example.com/users/123', $headers, $body);

// Partial update with PATCH
$body = Body::Json(['status' => 'active']);
$response = Request::patch('https://api.example.com/users/123', $headers, $body);

Making DELETE Requests

$headers = ['Authorization' => 'Bearer YOUR_TOKEN'];
$response = Request::delete('https://api.example.com/users/123', $headers);

Other HTTP Methods

// HEAD request (get headers only)
$response = Request::head('https://api.example.com/resource');

// OPTIONS request
$response = Request::options('https://api.example.com/resource');

// TRACE request
$response = Request::trace('https://api.example.com/resource');

🔥 Advanced Features

Authentication

Basic Authentication

use Https\Target\Request;

// Global authentication (applies to all requests)
Request::auth('username', 'password', CURLAUTH_BASIC);

$response = Request::get('https://api.example.com/protected');

// Or inline authentication
$response = Request::get(
    'https://api.example.com/protected',
    [],
    null,
    'username',
    'password'
);

Other Authentication Methods

// Digest Authentication
Request::auth('username', 'password', CURLAUTH_DIGEST);

// NTLM Authentication
Request::auth('username', 'password', CURLAUTH_NTLM);

// Negotiate Authentication
Request::auth('username', 'password', CURLAUTH_NEGOTIATE);

Proxy Configuration

use Https\Target\Request;

// HTTP Proxy
Request::proxy('proxy.example.com', 8080, CURLPROXY_HTTP);

// SOCKS5 Proxy
Request::proxy('127.0.0.1', 1080, CURLPROXY_SOCKS5);

// Proxy with authentication
Request::proxy('proxy.example.com', 8080);
Request::proxyAuth('proxy_user', 'proxy_pass', CURLAUTH_BASIC);

// Enable tunneling
Request::proxy('proxy.example.com', 8080, CURLPROXY_HTTP, true);

SSL/TLS Configuration

use Https\Target\Request;

// Disable SSL verification (not recommended for production)
Request::verifyPeer(false);
Request::verifyHost(false);

// Enable SSL verification (default, recommended)
Request::verifyPeer(true);
Request::verifyHost(true);

⚠️ Security Warning: Only disable SSL verification in development environments. Always enable it in production.

Timeout Configuration

// Set timeout (in seconds)
Request::timeout(30);  // 30 seconds

// Make request with timeout
$response = Request::get('https://slow-api.example.com/data');

Default Headers

// Set default headers for all requests
Request::defaultHeaders([
    'User-Agent' => 'MyApp/1.0',
    'Accept' => 'application/json',
    'X-API-Version' => 'v2'
]);

// Add a single default header
Request::defaultHeader('X-Custom-Header', 'value');

// Clear all default headers
Request::clearDefaultHeaders();

Custom cURL Options

// Set custom cURL options
Request::curlOpts([
    CURLOPT_ENCODING => 'gzip',
    CURLOPT_VERBOSE => true,
    CURLOPT_CONNECTTIMEOUT => 10
]);

// Set single cURL option
Request::curlOpt(CURLOPT_FOLLOWLOCATION, false);

// Clear custom options
Request::clearCurlOpts();

Cookie Management

// Use cookie string
Request::cookie('session=abc123; token=xyz789');

// Use cookie file for persistence
Request::cookieFile('/tmp/cookies.txt');

// Cookies will be saved and loaded automatically
$response = Request::get('https://example.com/login');

File Uploads

use Https\Target\Request\Body;

// Single file upload
$body = Body::Multipart([
    'document' => Body::File('/path/to/file.pdf', 'application/pdf'),
    'description' => 'My document'
]);

$response = Request::post('https://api.example.com/upload', [], $body);

// Multiple files with metadata
$files = [
    'file1' => '/path/to/image.jpg',
    'file2' => '/path/to/document.pdf'
];

$data = [
    'title' => 'My Upload',
    'category' => 'documents'
];

$body = Body::Multipart($data, $files);
$response = Request::post('https://api.example.com/upload', [], $body);

Form Data

use Https\Target\Request\Body;

// URL-encoded form data
$formData = Body::Form([
    'username' => 'john',
    'password' => 'secret',
    'remember' => true
]);

$headers = ['Content-Type' => 'application/x-www-form-urlencoded'];
$response = Request::post('https://example.com/login', $headers, $formData);

JSON Options

// Configure JSON decoding
Request::jsonOpts(
    true,   // Associative arrays (instead of objects)
    512,    // Recursion depth
    JSON_BIGINT_AS_STRING  // Options
);

$response = Request::get('https://api.example.com/data');
// Response body will be decoded as associative array

📚 API Reference

Request Methods

Configuration Methods

Response Properties

Response Methods

Body Helper Methods

🔒 Security

Best Practices

1. Always use HTTPS in production

   // Good
   $response = Request::get('https://api.example.com/data');
   
   // Avoid in production
   $response = Request::get('http://api.example.com/data');

2. Keep SSL verification enabled

   // Default (recommended)
   Request::verifyPeer(true);
   Request::verifyHost(true);

3. Secure credential storage

   // Use environment variables
   Request::auth(
       getenv('API_USERNAME'),
       getenv('API_PASSWORD')
   );

4. Validate API responses

   $response = Request::get('https://api.example.com/data');
   
   if ($response->code !== 200) {
       throw new Exception("API request failed: " . $response->getReasonPhrase());
   }

5. Set appropriate timeouts

   // Prevent hanging requests
   Request::timeout(30);

⚠️ Error Handling

Basic Error Handling

use Https\Target\Request;
use Https\Target\Exception;

try {
    $response = Request::get('https://api.example.com/data');
    
    if ($response->code >= 400) {
        throw new Exception("HTTP Error: {$response->code} - {$response->getReasonPhrase()}");
    }
    
    // Process successful response
    $data = json_decode($response->getRawBody(), true);
    
} catch (Exception $e) {
    // Handle cURL errors
    error_log("Request failed: " . $e->getMessage());
}

Advanced Error Handling

use Https\Target\Request;

try {
    Request::timeout(10);
    $response = Request::post('https://api.example.com/payment', $headers, $body);
    
    switch ($response->code) {
        case 200:
        case 201:
            // Success
            $result = json_decode($response->getRawBody(), true);
            break;
            
        case 400:
            // Bad request
            throw new \InvalidArgumentException("Invalid request parameters");
            
        case 401:
            // Unauthorized
            throw new \RuntimeException("Authentication required");
            
        case 403:
            // Forbidden
            throw new \RuntimeException("Access denied");
            
        case 404:
            // Not found
            throw new \RuntimeException("Resource not found");
            
        case 429:
            // Rate limited
            throw new \RuntimeException("Rate limit exceeded");
            
        case 500:
        case 502:
        case 503:
            // Server errors
            throw new \RuntimeException("Server error, please try again later");
            
        default:
            throw new \RuntimeException("Unexpected HTTP status: {$response->code}");
    }
    
} catch (\Https\Target\Exception $e) {
    // cURL or network error
    error_log("Network error: " . $e->getMessage());
} catch (\Exception $e) {
    // Application error
    error_log("Application error: " . $e->getMessage());
}

Getting Response Explanations

$response = Request::get('https://api.example.com/data');

// Get explanation for status code
$explanation = $response->getResponseCodeExplanation($response->code);

echo "Status: {$explanation['meaning']}\n";
echo "Cause: {$explanation['cause']}\n";
echo "Next Actions: " . implode(', ', $explanation['next_actions']);

💡 Real-World Examples

RESTful API Integration

<?php

use Https\Target\Request;
use Https\Target\Request\Body;

class PaymentGateway
{
    private $apiKey;
    private $baseUrl;
    
    public function __construct(string $apiKey, string $baseUrl)
    {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
        
        // Configure default settings
        Request::timeout(30);
        Request::verifyPeer(true);
        Request::defaultHeaders([
            'Authorization' => 'Bearer ' . $this->apiKey,
            'Content-Type' => 'application/json',
            'Accept' => 'application/json'
        ]);
    }
    
    public function createPayment(array $data): array
    {
        $body = Body::Json([
            'amount' => $data['amount'],
            'currency' => $data['currency'],
            'customerEmail' => $data['email'],
            'reference' => $data['reference'],
            'metadata' => $data['metadata'] ?? []
        ]);
        
        $response = Request::post($this->baseUrl . '/payments', [], $body);
        
        if ($response->code !== 201) {
            throw new \RuntimeException("Payment creation failed: {$response->getRawBody()}");
        }
        
        return json_decode($response->getRawBody(), true);
    }
    
    public function getPayment(string $id): array
    {
        $response = Request::get($this->baseUrl . '/payments/' . $id);
        
        if ($response->code !== 200) {
            throw new \RuntimeException("Payment retrieval failed");
        }
        
        return json_decode($response->getRawBody(), true);
    }
}

// Usage
$gateway = new PaymentGateway('your-api-key', 'https://api.payment.com');

$payment = $gateway->createPayment([
    'amount' => 100.00,
    'currency' => 'USD',
    'email' => 'customer@example.com',
    'reference' => 'ORDER-12345'
]);

Webhook Handler

<?php

use Https\Target\Request;
use Https\Target\Request\Body;

class WebhookNotifier
{
    public static function notify(string $webhookUrl, array $data): bool
    {
        $headers = [
            'Content-Type' => 'application/json',
            'X-Webhook-Signature' => hash_hmac('sha256', json_encode($data), 'secret')
        ];
        
        $body = Body::Json($data);
        
        try {
            Request::timeout(10);
            $response = Request::post($webhookUrl, $headers, $body);
            
            return $response->code >= 200 && $response->code < 300;
        } catch (\Exception $e) {
            error_log("Webhook delivery failed: " . $e->getMessage());
            return false;
        }
    }
}

File Download

<?php

use Https\Target\Request;

function downloadFile(string $url, string $savePath): bool
{
    try {
        Request::timeout(300); // 5 minutes for large files
        $response = Request::get($url);
        
        if ($response->code !== 200) {
            return false;
        }
        
        return file_put_contents($savePath, $response->getRawBody()) !== false;
    } catch (\Exception $e) {
        error_log("Download failed: " . $e->getMessage());
        return false;
    }
}

// Usage
downloadFile('https://example.com/files/document.pdf', '/tmp/document.pdf');

🌐 Helpful Resources

PHP & HTTP Documentation

• PHP cURL Documentation
• HTTP Status Codes
• PSR-7: HTTP Message Interface
• RESTful API Best Practices

Related Libraries

• Guzzle HTTP Client
• Symfony HTTP Client
• PHP HTTP Foundation

Security Resources

• OWASP API Security
• SSL/TLS Best Practices

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone repository
git clone https://github.com/broosaction/php-https.git
cd php-https

# Install dependencies
composer install

# Run tests
composer test

Coding Standards

• Follow PSR-12 coding standards
• Write PHPDoc comments for all public methods
• Include unit tests for new features
• Update documentation for API changes

📞 Support

Need help? We're here for you!

🌟 Professional Support

For enterprise support, custom integrations, and consulting services, visit:

• Broos Action - Professional software development and consulting
• Client Support Portal - 24/7 technical support

📧 Contact Information

• Email: [email protected]
• Phone: +260954922329
• Average Response Time: 3 minutes

🐛 Bug Reports

Found a bug? Please open an issue on GitHub Issues

💬 Community

• GitHub Discussions
• Stack Overflow - Tag your questions with php-https

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 Broos Action

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🌟 About Broos Action

Broos Action is a leading technology solutions provider specializing in:

• ☁️ Cloud Services - AWS, Google Cloud, Microsoft Azure
• 🔌 API Development & Integration - RESTful APIs, GraphQL, WebSockets
• 📱 Mobile Development - iOS, Android applications
• 🤖 Artificial Intelligence - Machine learning, AI integration
• 🔐 Cybersecurity Solutions - Security audits, compliance
• 📊 Business Intelligence - Data analytics and insights

Industries We Serve

• Financial Services
• Healthcare & Life Sciences
• Manufacturing & Industrial
• Retail & E-commerce
• Government & Public Sector
• Technology & SaaS

Trusted by businesses worldwide with a proven track record of 3+ years, 98% customer satisfaction, and 3-minute average response time.

📊 Statistics

🙏 Acknowledgments

• Thanks to all contributors
• Built with ❤️ by Broos Action
• Special thanks to the PHP community

📝 Changelog

Version 1.0.0 (Current)

• Initial release
• Full PSR-7 compliance
• Support for all HTTP methods
• Authentication and proxy support
• File upload capabilities
• Comprehensive error handling

For detailed changelog, see CHANGELOG.md

Documentation • API Reference • Examples • Support

Made with ❤️ by Broos Action

⭐ Star us on GitHub — it motivates us a lot!