Download the PHP package mubbi/laravel-flysystem-huawei-obs without Composer

Laravel Flysystem Huawei OBS Adapter

A Laravel Flysystem v2/v3 adapter for Huawei Object Storage Service (OBS). This package provides seamless integration between Laravel's filesystem abstraction and Huawei Cloud OBS, allowing you to use Huawei OBS as a storage backend in your Laravel applications.

Multi-Version Compatibility

This package now supports multiple versions of both Flysystem and Guzzle:

• Flysystem: v3.0+ (primary) with v2.0+ compatibility through dependency constraints
• Guzzle: v6.3.0+, v7.0+, and v8.0+ (automatic detection)
• Laravel: 9.0+, 10.0+, 11.0+, and 12.0+
• PHP: 8.1+

Features

• ✅ Complete Flysystem v3 Compatibility: Full implementation of all required and optional Flysystem methods
• ✅ Laravel Integration: Seamless integration with Laravel's Storage facade
  • ✅ Huawei OBS SDK Integration: Uses mubbi/esdk-obs-php (Huawei OBS SDK compatible fork)
• ✅ Temporary Credentials: Support for session tokens (securityToken)
• ✅ Signed URLs: Generate pre-signed URLs for temporary object access
• ✅ Public URLs: Generate public URLs for objects with public read access
• ✅ Post Signatures: Create signatures for direct browser uploads to OBS
• ✅ Object Tagging: Add and manage metadata tags on OBS objects
• ✅ Object Restoration: Restore archived objects from OBS
• ✅ Credential Refresh: Update credentials during runtime
• ✅ Authentication Validation: Proactive checking of OBS credentials and bucket access
• ✅ Comprehensive Error Handling: Clear, actionable error messages
• ✅ Security-Focused Design: Private visibility by default, SSL verification
• ✅ Configuration Validation: Automatic validation of required configuration parameters
• ✅ Retry Logic: Automatic retry with exponential backoff for transient errors
• ✅ Authentication Caching: Cache authentication status to improve performance
• ✅ Logging Support: Optional operation and error logging
• ✅ Artisan Commands: Built-in testing command for connectivity verification
• ✅ Type Safety: PHPStan level 8 compliance with strict typing
• ✅ Code Quality: Laravel Pint compliance and PSR-12 standards
• ✅ Performance Optimized: Built-in timeout protection and infinite loop prevention
• ✅ Large Dataset Support: Optimized methods for handling large numbers of files

Security Features

This package includes robust security features:

• 🔐 Authentication Validation: Automatic authentication checks before all operations
• 🛡️ Secure Defaults: Private visibility by default, SSL verification enabled
• 🔑 Temporary Credentials: Support for security tokens and credential rotation
• 🌐 Signed URLs: Secure temporary access without exposing credentials
• 📝 Input Sanitization: Path normalization and validation
• 🚫 Error Handling: No sensitive data exposure in error messages
• 🔄 Infinite Loop Prevention: Built-in safety mechanisms to prevent timeouts

Requirements

• PHP 8.1+
• Laravel 9.0+ (supports Laravel 9, 10.48.29+, 11, and 12)
• Flysystem v3.0+ (primary) with v2.0+ compatibility
• Guzzle v6.3.0+, v7.0+, or v8.0+ (automatic detection)
• Huawei Cloud OBS account and credentials

⚠️ Security Notice: Laravel 10.0.0 to 10.48.28 contains a file validation bypass vulnerability (CVE-2025-27515). This package requires Laravel 10.48.29+ to ensure security. Please upgrade your Laravel installation if you're using an affected version.

Installation

Version Compatibility

This package automatically detects and adapts to your installed versions of Guzzle:

• Guzzle v6: Uses v6-specific client configurations
• Guzzle v7: Uses v7-specific client configurations
• Guzzle v8: Uses v8-specific client configurations (with PSR-18 compliance)

For Flysystem, the package uses v3 as the primary interface but maintains compatibility with v2 through dependency constraints. The package will automatically choose the correct HTTP client configuration based on your installed Guzzle version.

Installation Steps

1. Install the package via Composer:

2. Publish the configuration (optional):

3. Add your Huawei OBS credentials to your .env file:

4. Configure your filesystem in config/filesystems.php:

Basic Usage

Laravel Storage Facade

The package integrates seamlessly with Laravel's Storage facade:

Direct Adapter Usage

You can also use the adapter directly (Flysystem v3 interface):

Configuration Options

Required Configuration

These options are required for the adapter to function:

• key - Your Huawei OBS Access Key ID
• secret - Your Huawei OBS Secret Access Key
• bucket - The OBS bucket name
• endpoint - The OBS endpoint URL (e.g., https://obs.cn-north-1.myhuaweicloud.com)

Optional Configuration

• prefix - Optional path prefix for all operations
• security_token - Security token for temporary credentials

Advanced OBSClient Configuration

The adapter supports all OBSClient configuration options:

• signature - Signature version (v2, v4, obs) - Default: v4
• path_style - Use path-style URLs instead of virtual-hosted-style - Default: false
• region - OBS region (e.g., cn-north-1) - Optional
• ssl_verify - Enable/disable SSL certificate verification - Default: true
• ssl.certificate_authority - Path to custom CA certificate bundle - Optional
• max_retry_count - Maximum number of retry attempts - Default: 3
• timeout - Request timeout in seconds - Default: 120
• socket_timeout - Socket timeout in seconds - Default: 60
• connect_timeout - Connection timeout in seconds - Default: 30
• chunk_size - Chunk size for multipart uploads in bytes - Default: 8192
• exception_response_mode - Exception response mode (exception, response) - Default: exception
• is_cname - Whether the endpoint is a CNAME - Default: false

HTTP Client Configuration

• http_client.timeout - Request timeout in seconds - Default: 120
• http_client.connect_timeout - Connection timeout in seconds - Default: 30
• http_client.verify - SSL certificate verification - Default: true
• http_client.proxy - HTTP proxy configuration - Optional
• http_client.headers - Additional HTTP headers - Optional

Retry Configuration

• retry_attempts - Number of retry attempts for transient errors - Default: 3
• retry_delay - Base delay between retries in seconds - Default: 1

Logging Configuration

• logging_enabled - Enable/disable logging - Default: false
• log_operations - Log successful operations - Default: false
• log_errors - Log errors - Default: true

Examples

See the examples/ directory for concise, copy-pasteable snippets:

• examples/usage.php: basic write/read with Flysystem
• examples/url-usage.php: URL and temporary URL usage
• examples/advanced-usage.php: signed URLs, post signatures, tags, restore, optimized listing
• examples/controller-compatibility.php: controller-style listing example
• examples/laravel-compatibility-demo.php: Storage facade compatibility helpers

Advanced Features

Optimized Methods for Large Datasets

For applications with large numbers of files, the package provides optimized methods with built-in timeout protection:

Retry Logic and Error Handling

The adapter includes automatic retry logic with exponential backoff for transient errors:

The retry logic will automatically retry on transient errors but will not retry on:

• Authentication errors (AccessDenied, InvalidAccessKeyId, SignatureDoesNotMatch)
• Configuration errors (NoSuchBucket)

Authentication Caching

Authentication status is cached for 5 minutes to improve performance:

Logging

Enable operation and error logging:

Laravel Storage Facade Compatibility

This package provides full compatibility with Laravel's Storage facade. All the standard Laravel Storage methods are supported:

Directory Listing

File Information

Complete Example

Logged information includes:

• Operation name and duration
• File path and bucket
• Error details and codes
• Additional context (tags, headers, etc.)

Configuration Validation

The service provider automatically validates required configuration:

Custom Exceptions

The package provides custom exceptions for better error handling:

Authentication & Security

The adapter automatically validates authentication before operations and provides clear error messages:

Temporary Credentials (Security Token)

For applications using temporary credentials (like AWS STS or similar services):

URL Handling

The adapter supports both public URLs and signed URLs. For Laravel's Storage facade:

Public and Private URLs

The url() method automatically handles both public and private objects:

Temporary URLs

Generate temporary URLs with custom expiration times:

Object Tagging

Add and manage metadata tags on OBS objects:

Post Signatures

Create signatures for direct browser uploads to OBS:

Object Restoration

Restore archived objects from OBS:

Testing

Artisan Command

The package includes an Artisan command for testing connectivity and features:

This command will:

• Validate credentials and bucket access
• Test reads/writes, signed URLs, post signatures, and tagging
• Output a concise pass/fail report

Manual Testing

You can also test the adapter manually:

Error Handling

The package provides comprehensive error handling with clear, actionable error messages:

Common Error Scenarios

Custom Exceptions

The package provides specific exceptions for different error types used by advanced features:

Performance Considerations

Large Dataset Handling

For applications with large numbers of files, use the optimized methods:

Caching

Consider caching frequently accessed data:

Batch Operations

For multiple operations, consider batching:

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your access key and secret key
   • Check if your security token is still valid
   • Ensure your credentials have the necessary permissions

2. Bucket Access Errors

   • Verify the bucket name is correct
   • Check if the bucket exists in the specified region
   • Ensure your credentials have access to the bucket

3. Timeout Errors

   • Use optimized methods for large datasets
   • Increase timeout values in configuration
   • Consider using background processing for large operations
4. SSL Certificate Errors
   • Verify your endpoint URL is correct
   • Check if SSL verification is required in your environment
   • Consider disabling SSL verification for testing (not recommended for production)

Debug Mode

Enable debug mode to get more detailed error information:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: composer test
4. Static analysis: composer phpstan
5. Lint/format: composer pint

Code Quality

This package follows strict code quality standards:

• PHPStan Level 8: Maximum type safety
• Laravel Pint: PSR-12 coding standards
• PHPUnit: Comprehensive test coverage
• GitHub Actions: Automated CI/CD pipeline

License

This package is open-sourced software licensed under the MIT license.

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Credits

• Author: Mubbasher Ahmed
• Maintainer: Mubbasher Ahmed
• License: MIT

Made with ❤️ by Mubbasher Ahmed