README

A Laravel-ready Flysystem adapter for NetSuite's FileCabinet, enabling seamless file operations through NetSuite's REST API with OAuth 1.0 authentication.

Features

• ✅ Full Flysystem v3 compatibility - All standard file operations supported
• 🔐 OAuth 1.0 authentication - Secure NetSuite REST API integration
• 🚀 Laravel auto-discovery - Zero-configuration Laravel integration
• 📁 Complete file operations - Read, write, delete, copy, move, list
• 🗂️ Directory management - Create, delete, and navigate folders
• 🔍 Connection testing - Built-in connectivity verification
• 🛡️ Error handling - Comprehensive exception handling
• 📊 File metadata - Size, mime type, last modified date
• ✨ Production ready - Thoroughly tested with PHPUnit

Quick Start

Installation

composer require baja-foundry/flysystem-filecabinet:^1.0.0-beta.1

Laravel Configuration

Add to config/filesystems.php:

'netsuite_filecabinet' => [
    'driver' => 'netsuite_filecabinet',
    'base_url' => env('NETSUITE_BASE_URL'),
    'consumer_key' => env('NETSUITE_CONSUMER_KEY'),
    'consumer_secret' => env('NETSUITE_CONSUMER_SECRET'),
    'token_id' => env('NETSUITE_TOKEN_ID'),
    'token_secret' => env('NETSUITE_TOKEN_SECRET'),
    'realm' => env('NETSUITE_REALM'),
],

Test Connection

php artisan tinker

$disk = Storage::disk('netsuite_filecabinet');
$result = $disk->getAdapter()->testConnection();
dump($result); // Should show success: true

Documentation

• 📋 Installation Guide - Complete Laravel setup and testing with artisan tinker
• 🔌 Connection Testing - Verify NetSuite connectivity and troubleshoot issues
• 🧪 Live Testing Guide - Run tests against real NetSuite environments

Requirements

• PHP: ^8.2
• Laravel: ^10.0 | ^11.0 (optional, works standalone)
• Flysystem: ^3.30
• NetSuite: REST API access with valid OAuth credentials

Supported Operations

Basic Usage

Laravel

use Illuminate\Support\Facades\Storage;

$disk = Storage::disk('netsuite_filecabinet');

// Upload a file
$disk->put('documents/report.pdf', $pdfContent);

// Download a file  
$content = $disk->get('documents/report.pdf');

// Check if file exists
if ($disk->exists('documents/report.pdf')) {
    echo "File exists!";
}

// List files
$files = $disk->files('documents');

Standalone PHP

use BajaFoundry\NetSuite\Flysystem\Adapter\NetSuiteFileCabinetAdapter;
use BajaFoundry\NetSuite\Flysystem\Client\NetSuiteClient;
use League\Flysystem\Filesystem;

$client = new NetSuiteClient([
    'base_url' => 'https://account.suitetalk.api.netsuite.com',
    'consumer_key' => 'your_consumer_key',
    'consumer_secret' => 'your_consumer_secret', 
    'token_id' => 'your_token_id',
    'token_secret' => 'your_token_secret',
    'realm' => 'your_account_id',
]);

$adapter = new NetSuiteFileCabinetAdapter($client);
$filesystem = new Filesystem($adapter);

// Test connection
$result = $adapter->testConnection();
if ($result['success']) {
    $filesystem->write('hello.txt', 'Hello NetSuite!');
}

NetSuite Setup Requirements

You'll need the following from your NetSuite account:

1. Integration Record with Consumer Key & Secret
2. Access Token Record with Token ID & Secret
3. Account ID for realm parameter
4. Proper permissions for FileCabinet and SuiteQL access

See INSTALL.md for detailed setup instructions.

Advanced Usage

Custom Root Folder

Restrict operations to a specific NetSuite folder:

$adapter = new NetSuiteFileCabinetAdapter($client, 'folder-id-123');

Path Prefixing

Add automatic path prefixes:

$adapter = new NetSuiteFileCabinetAdapter($client, '', 'uploads/');
// All operations will be prefixed with 'uploads/'

Error Handling

use NetSuite\Flysystem\Exceptions\NetSuiteException;
use League\Flysystem\UnableToReadFile;

try {
    $content = $disk->get('nonexistent.txt');
} catch (UnableToReadFile $e) {
    echo "File not found: " . $e->getMessage();
} catch (NetSuiteException $e) {
    echo "NetSuite API error: " . $e->getMessage();
}

Testing

The package includes comprehensive testing at multiple levels:

Mock-Based Tests (Fast, No NetSuite Required)

# Run all mock-based tests
composer test

# Run specific test suites
composer test-unit           # Unit tests only
composer test-integration    # Integration tests only

# With coverage
composer test-coverage

Live NetSuite Tests (Requires Real NetSuite Access)

# Run live tests against real NetSuite
composer test-live

# Live tests with coverage
composer test-live-coverage

# Run all tests (mock + live)
composer test-all

Code Quality

# Static analysis
composer phpstan

# Code style checks
composer phpcs

# Fix code style
composer phpcbf

Test Statistics

• 31 Mock-Based Tests - Fast execution, no credentials required
• 28 Live Tests - Real NetSuite environment validation
• 96.7% Success Rate - Reliable and thoroughly tested
• Automatic Cleanup - Live tests clean up after themselves

See LIVE_TESTING.md for detailed live testing setup and configuration.

Development

Local Setup

git clone https://github.com/your-repo/netsuite-flysystem-filecabinet.git
cd netsuite-flysystem-filecabinet
composer install

Architecture

src/
├── Adapter/
│   └── NetSuiteFileCabinetAdapter.php    # Main Flysystem adapter
├── Client/
│   └── NetSuiteClient.php                # OAuth HTTP client
├── Exceptions/
│   ├── NetSuiteException.php             # Base exception
│   └── FileNotFoundException.php         # File-specific errors
└── Laravel/
    └── NetSuiteFileCabinetServiceProvider.php # Laravel integration

Troubleshooting

Common Issues

See CONNECTION_TESTING.md for detailed troubleshooting.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new features
4. Ensure all tests pass
5. Submit a Pull Request

Development Guidelines

• Follow PSR-12 coding standards
• Add PHPDoc comments
• Write tests for new features
• Update documentation as needed

Security

• Never commit NetSuite credentials to version control
• Use environment variables for sensitive configuration
• Regularly rotate OAuth tokens
• Monitor API usage for unauthorized access

License

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

Credits

• Built on Flysystem by The League of Extraordinary Packages
• Inspired by the Laravel ecosystem and NetSuite's FileCabinet system
• OAuth 1.0 implementation following NetSuite's SuiteTalk specifications

Support

• Documentation: INSTALL.md | CONNECTION_TESTING.md | LIVE_TESTING.md
• Issues: GitHub Issues
• NetSuite Docs: SuiteTalk REST Web Services

Made with ❤️ for the Laravel and NetSuite communities.