No FTP on Native PHP

[mateusgalasso]

What were you trying to do?

FTP Extension Not Available in NativePHP Runtime Despite Configuration

🐛 Bug Report

Environment

• NativePHP Version: 1.1.2 (released 2025-07-03)
• Laravel Version: 11.x
• PHP CLI Version: 8.3.22 (with FTP extension ✅)
• NativePHP Runtime PHP Version: 8.3.21 (without FTP extension ❌)
• Node.js Version: 24.3.0
• npm Version: 11.4.2
• Electron Version: 32.3.3
• OS: macOS 14.5.0 (Darwin 24.5.0)
• Laravel Herd: Yes

Issue Description

The FTP extension is not available in the NativePHP runtime environment, despite being properly configured in NativeAppServiceProvider::phpIni() and working correctly in the CLI environment.

Expected Behavior

When configuring the FTP extension in NativeAppServiceProvider, it should be available in the NativePHP runtime, allowing FTP operations to work seamlessly.

Actual Behavior

• ✅ PHP CLI: extension_loaded('ftp') returns true
• ❌ NativePHP Runtime: extension_loaded('ftp') returns false

Configuration

NativeAppServiceProvider.php:

<?php

namespace App\Providers;

use Native\Laravel\Facades\Window;
use Native\Laravel\Contracts\ProvidesPhpIni;

class NativeAppServiceProvider implements ProvidesPhpIni
{
    public function boot(): void
    {
        Window::open()
            ->title('FluxCore Desktop')
            ->width(1200)
            ->height(800)
            ->minWidth(800)
            ->minHeight(600);
    }

    public function phpIni(): array
    {
        return [
            'extension=ftp',           // ⚠️ Not working in runtime
            'extension=pdo',
            'extension=pdo_sqlite',
            'extension=pdo_mysql',
            'extension=curl',
            'extension=zip',
            'extension=mbstring',
            'extension=openssl',
            'extension=json',
            'extension=fileinfo',
            'allow_url_fopen=1',
            'allow_url_include=0',
            'max_execution_time=300',
            'memory_limit=512M',
            'upload_max_filesize=100M',
            'post_max_size=100M',
            'default_socket_timeout=60',
            'user_agent="FluxCore Desktop"',
            'log_errors=1',
            'display_errors=0',
            'error_reporting=E_ALL',
            'auto_detect_line_endings=1'
        ];
    }
}

Evidence

1. CLI Environment (Working):

$ php -m | grep ftp
ftp

$ php -r "var_dump(extension_loaded('ftp'));"
bool(true)

2. NativePHP Runtime (Not Working):

{
    "FTP_BINARY": 2,
    "FTP_ASCII": 1,
    "extension_loaded": false,  // ❌ Problem here
    "php_version": "8.3.21",
    "sapi": "cli-server"
}

3. NativePHP Startup Logs:

Starting PHP server... /path/to/php artisan serve /project/path [
  'extension=ftp',              // ⚠️ Configured but not loaded
  'extension=pdo',
  'extension=pdo_sqlite',
  // ... other extensions
]

Impact

This issue prevents applications that rely on FTP functionality from working correctly in NativePHP, forcing developers to implement HTTP fallbacks or alternative solutions.

Workaround Implemented

We implemented an intelligent fallback system that detects available extensions and uses HTTP mirrors when FTP is not available:

public function getAvailableFiles(string $source, string $year, string $month, string $state): array
{
    $ftpAvailable = extension_loaded('ftp');
    $curlAvailable = extension_loaded('curl');
    
    if ($ftpAvailable) {
        return $this->fetchFilesFromFtp($source, $year, $month, $state);
    } elseif ($curlAvailable) {
        return $this->fetchFilesFromHttp($source, $year, $month, $state); // Fallback
    } else {
        throw new \Exception('Neither FTP nor cURL extensions are available');
    }
}

Questions

1. Is this a known limitation of the NativePHP PHP runtime?
2. Are there specific steps required to enable FTP beyond the phpIni() configuration?
3. Is the FTP extension bundled with the NativePHP PHP binary?
4. Should we expect all standard PHP extensions to work in NativePHP?

Debugging Information

Available Extensions in NativePHP Runtime:

// First 10 extensions from get_loaded_extensions()
["Core", "date", "libxml", "openssl", "pcre", "sqlite3", "zlib", "bcmath", "bz2", "ctype"]

PHP Configuration:

• CLI SAPI: cli (FTP available ✅)
• NativePHP SAPI: cli-server (FTP not available ❌)

Reproduction Steps

1. Create a fresh Laravel project with NativePHP
2. Configure FTP extension in NativeAppServiceProvider::phpIni()
3. Test extension_loaded('ftp') in both CLI and NativePHP runtime
4. Observe the difference in behavior

Additional Context

This issue was discovered while developing a DATASUS data integration application that requires FTP access to government servers. The application works perfectly in CLI/web environments but fails in NativePHP due to the missing FTP extension.

Technical Details

NativePHP Package Information:

name     : nativephp/laravel
versions : * 1.1.2
released : 2025-07-03, this week
source   : https://github.com/NativePHP/laravel.git
commit   : e784527ccd2cfed1e0ec2a7de6e54667d31e6cf7

PHP Binary Path:

/vendor/nativephp/php-bin/bin/mac/arm64/php-8.3.zip

Startup Configuration Logs:

Starting PHP server... [
  'extension=ftp',              // ⚠️ Configured but not effective
  'extension=pdo',              // ✅ Working
  'extension=curl',             // ✅ Working  
  'extension=zip',              // ✅ Working
  // ... other extensions
]

Extension Loading Behavior:

• Other extensions (pdo, curl, zip, etc.) load correctly via phpIni()
• Only FTP extension fails to load despite identical configuration syntax
• No error messages or warnings during startup about FTP extension

Possible Solutions

1. Bundle FTP extension with the NativePHP PHP runtime
2. Improve documentation about which extensions are available
3. Provide clearer error messages when configured extensions are not available
4. Add extension availability checks during NativePHP startup

---

Thank you for your time and consideration! 🙏

This issue significantly impacts applications that need FTP functionality, and any guidance or solution would be greatly appreciated by the NativePHP community.

What happened?

above

How to reproduce the bug

above

Debug Output

above

Which operating systems have you seen this occur on?

No response

Notes

No response

[gwleuverink]

Hi @mateusgalasso, I'll address your questions in order.

Is the FTP extension bundled with the NativePHP PHP binary?

We don't include the ftp extension in our prebuilt binaries. Here's the list of extensions that the binaries ship with: https://github.com/NativePHP/php-bin/blob/main/php-extensions.txt

Are there specific steps required to enable FTP beyond the phpIni() configuration?

You bet! You can build your own binaries & build your app using those:
https://nativephp.com/docs/desktop/1/digging-deeper/php-binaries

Should we expect all standard PHP extensions to work in NativePHP?

We use static-php-cli to build binaries with statically linked dependencies. You can check if the extension you need is supported by static-php here:
https://static-php.dev/en/guide/extensions.html

I'll remove the bug label, since it's not a bug. But I'll raise the question internally if it makes sense to add ftp to the default extensions