Download the PHP package visiaquantum/laravel-fattureincloud-php-sdk without Composer

Laravel Fatture in Cloud PHP SDK

A Laravel package that provides a clean, Laravel-native wrapper around the official Fatture in Cloud PHP SDK. This package abstracts the complexity of the base SDK and offers a simplified, Laravel-integrated developer experience for interacting with the Fatture in Cloud API.

The package follows Laravel ecosystem conventions with a clean, simplified architecture that provides OAuth2 authentication flows, token management, and service abstraction for seamless API integration.

Features

• 🚀 Laravel Native: Built following Laravel conventions and standards
• 🔐 OAuth2 Integration: Complete OAuth2 authorization code flow support
• 💾 Smart Token Management: Automatic token storage, refresh, and encryption
• 🏗️ Clean Architecture: Interfaces and dependency injection throughout
• 📦 All API Services: Full access to all Fatture in Cloud API endpoints
• 🛡️ Secure: Built-in security features and encrypted token storage
• 🧪 Well Tested: Comprehensive test coverage with Pest PHP

Requirements

• PHP 8.4 or higher
• Laravel 11.x or 12.x
• Fatture in Cloud Developer Account

Installation

You can install the package via Composer:

Publish the configuration file:

Configuration

Environment Variables

Add these variables to your .env file:

Configuration File

The published configuration file (config/fatture-in-cloud.php) includes comprehensive OAuth2 settings:

OAuth2 Callback Route

The package automatically registers the OAuth2 callback route at /fatture-in-cloud/callback (named fatture-in-cloud.callback) using a single action invokable controller. This route:

• Processes OAuth2 authorization callbacks from Fatture in Cloud
• Handles both successful authorizations and error responses
• Validates CSRF state parameters to prevent attacks
• Exchanges authorization codes for access/refresh tokens
• Stores tokens securely using Laravel's encrypted cache
• Returns structured JSON responses for success/error scenarios

The route is registered as: Route::get('/fatture-in-cloud/callback', OAuth2CallbackController::class)

Usage

Facade Usage

Dependency Injection

Available API Services

The package provides access to 13+ Fatture in Cloud API services through the factory pattern:

OAuth2 Authentication Flow

1. Generate Authorization URL

2. Handle Callback (Automatic Route)

The package automatically handles callbacks at /fatture-in-cloud/callback. You can customize the handling by creating your own controller:

3. Using API Services

Token Management

OAuth2 Scopes

The package supports all Fatture in Cloud OAuth2 scopes. Some common scopes include:

Manual Authentication

If you prefer to use a manually generated access token instead of OAuth2:

When an access token is configured, OAuth2 settings are ignored and the SDK will use the token directly. This is useful for:

• Server-to-server integrations
• Background jobs and scheduled tasks
• Applications that don't need user-specific authentication
• Development and testing scenarios

Architecture

The package follows clean architecture principles with dependency injection and contract-based design:

Key Architectural Features

• Clean Architecture: Separation of concerns with clear boundaries
• Dependency Injection: All dependencies are injected and easily testable
• Contract-Based Design: Interface-driven development for flexibility
• Factory Pattern: Service creation through factory for consistency
• Single Action Controllers: OAuth2 callback controller follows Laravel's invokable controller pattern using __invoke()
• Encrypted Token Storage: Secure token persistence using Laravel's encryption
• Automatic Route Registration: OAuth2 callback route registered automatically
• Laravel Integration: Full integration with Laravel's service container and facades

Development Commands

Testing

Run the full test suite using Pest:

Run tests directly:

Run tests with coverage report:

Run tests in CI mode:

Code Quality

Run PHPStan static analysis:

Run PHPStan directly:

Format code using Laravel Pint:

Format code directly:

Package Development

Discover package (runs automatically after autoload dump):

Security Features

• Encrypted Token Storage: All tokens are automatically encrypted before storage using Laravel's encryption
• CSRF Protection: Secure session-based state management for OAuth2 flows prevents CSRF attacks
• Environment Configuration: Credentials stored in environment variables prevent exposure in code
• Automatic Token Refresh: Transparent token refresh prevents expired token issues
• Secure Callback Handling: Built-in validation of OAuth2 callback parameters

Publishing Configuration

When ready to publish package assets:

Changelog

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

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 Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (composer test)
5. Run code quality checks (composer analyse && composer format)
6. Commit your changes (git commit -m 'Add some amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Security Vulnerabilities

If you discover a security vulnerability within this package, please send an email to the maintainers. All security vulnerabilities will be promptly addressed.

Credits

• Mattia Migliorini
• Visia Quantum
• All Contributors

License

The MIT License (MIT). Please see License File for more information.