Skip to content

0.15.0

Latest
Latest

Choose a tag to compare

View all tags
@efebagri efebagri released this 30 Nov 04:37
· 3 commits to development since this release
0.15.0
ee29123
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release v0.15.0 - Security & Configuration Improvements

🎉 What's New

This release focuses on security improvements, better configurability, and code quality enhancements while maintaining backward compatibility for basic usage.

✨ New Features

🔒 Configurable SSL Verification

SSL certificate verification is now enabled by default for production security, but can be disabled for development environments:

// Production (default) - SSL verification enabled
$client = new MailCowAPI('https://mail.example.com', 'API_KEY');

// Development - SSL verification disabled for self-signed certificates
$client = new MailCowAPI('https://mail.local', 'API_KEY', null, false);

⏱️ Configurable Request Timeout

Customize request timeouts based on your needs (default: 120 seconds):

// Custom 60-second timeout
$client = new MailCowAPI('https://mail.example.com', 'API_KEY', null, true, 60);

// Longer timeout for slow connections
$client = new MailCowAPI('https://mail.example.com', 'API_KEY', null, true, 300);

🎨 Custom HTTP Client Injection

Inject your own configured Guzzle client for advanced use cases:

use GuzzleHttp\Client;

$httpClient = new Client([
    'proxy' => 'http://proxy.example.com:8080',
    'timeout' => 30
]);

$client = new MailCowAPI('https://mail.example.com', 'API_KEY', $httpClient);

🛠️ Code Quality Improvements

  • DRY Principle: Refactored request() method to eliminate code duplication across HTTP methods
  • Strict Type Hints: Added PHP 7.4+ typed properties for better type safety and IDE support
  • Enhanced PHPDoc: Complete documentation for all public methods and parameters
  • Better Error Messages: Improved validation with descriptive error messages for invalid HTTP methods
  • Nullable Handler Properties: Properly initialized handler properties with nullable types

📚 Documentation

  • Updated README: Comprehensive examples for all new configuration options
  • Security Best Practices: Added section with production recommendations
  • API Endpoint Reference: Complete list of all available handler methods
  • Constructor Documentation: Full parameter documentation with examples

⚠️ Breaking Changes

Minimum PHP Version

  • New requirement: PHP 7.4+ (previously PHP 7.2+)
  • Reason: Support for typed properties and modern PHP features

Constructor Signature

The constructor now accepts additional optional parameters:

// Old (still works)
new MailCowAPI(string $url, string $token);

// New (backward compatible)
new MailCowAPI(
    string $url,
    string $token,
    ?Client $httpClient = null,
    bool $verifySSL = true,
    int $timeout = 120
);

Note: Basic usage remains unchanged and fully backward compatible.

📦 Upgrade Guide

For Most Users (Basic Usage)

No changes required! Your existing code will continue to work:

// This still works without any modifications
$client = new MailCowAPI('https://mail.example.com', 'YOUR_API_KEY');
$domains = $client->domains()->getDomains();

Requirements Check

Ensure you're running PHP 7.4 or higher:

php -v

If you're on PHP 7.2 or 7.3, please upgrade to PHP 7.4+ before updating to v0.15.0.

If You Disabled SSL Verification Before

Previously, you had to manually configure Guzzle to disable SSL verification:

// Old way (complex)
$httpClient = new Client(['verify' => false]);
$client = new MailCowAPI('https://mail.local', 'API_KEY', $httpClient);

Now it's much simpler:

// New way (simple)
$client = new MailCowAPI('https://mail.local', 'API_KEY', null, false);

Recommended: Environment-Based Configuration

Use environment variables for different environments:

$client = new MailCowAPI(
    getenv('MAILCOW_URL'),
    getenv('MAILCOW_API_KEY'),
    null,
    getenv('APP_ENV') === 'production'  // SSL only in production
);

🔒 Security Improvements

  • SSL verification enabled by default: Protects against man-in-the-middle attacks
  • Production-ready defaults: Secure configuration out of the box
  • Flexible for development: Easy to disable SSL for local testing with self-signed certificates

🐛 Bug Fixes

  • Fixed redundant parameter assignment in request() method
  • Improved error handling for invalid HTTP methods

📈 Technical Details

Changed Files

  • src/MailCowAPI.php - Core API client refactoring
  • README.md - Comprehensive documentation update

Code Statistics

  • Eliminated ~60 lines of duplicated code
  • Added 100+ lines of PHPDoc documentation
  • Improved type safety with 25+ type hints

🙏 Acknowledgments

Thank you to all users who provided feedback and reported issues!

📝 Full Changelog

Features:

  • feat: improve API client security and code quality
  • feat: add configurable SSL verification (default: enabled)
  • feat: add configurable request timeout (default: 120s)
  • feat: refactor request() method to follow DRY principle
  • feat: add strict type hints to all class properties (PHP 7.4+)
  • feat: improve PHPDoc documentation for all public methods
  • feat: add validation for HTTP methods with better error messages

Documentation:

  • docs: update README with new configuration options
  • docs: add security best practices section
  • docs: document SSL verification configuration
  • docs: add timeout configuration examples
  • docs: include custom HTTP client injection
  • docs: list all available API endpoints
  • docs: update PHP version requirement to 7.4+
  • docs: fix URL format in examples (add https://)
  • docs: add environment-based configuration example

Previous Release: [v0.14.2](https://github.com/Exbil/mailcow-php-api/releases/tag/v0.14.2)
Full Diff: v0.14.2...v0.15.0

💬 Questions or Issues?

If you encounter any problems or have questions about this release:

Assets 2
Loading