Getting Started

Minimal Setup

Install via Composer:

composer require jakoch/phantomjs-installer:^3.0

Add to require-dev if PhantomJS is only needed for testing:

"require-dev": {
    "jakoch/phantomjs-installer": "^3.0"
}

Autoload the Binary: Add this to your composer.json under scripts:

"scripts": {
    "post-install-cmd": [
        "Jakoch\\PhantomJsInstaller\\Installer::checkAndInstall"
    ],
    "post-update-cmd": [
        "Jakoch\\PhantomJsInstaller\\Installer::checkAndInstall"
    ]
}

Run:

composer install

PhantomJS will now be available in your project’s /bin directory.

First Use Case: Use PhantomJS in a Laravel command or test:

use Symfony\Component\Process\Process;
use Symfony\Component\Process\Exception\ProcessFailedException;

try {
    $process = new Process(['phantomjs', '--version']);
    $process->run();
    if (!$process->isSuccessful()) {
        throw new ProcessFailedException($process);
    }
} catch (\Jakoch\PhantomJsInstaller\Exception\PhantomJsNotFoundException $e) {
    // Handle missing PhantomJS (e.g., retry install or fail gracefully)
    throw new \RuntimeException("PhantomJS installation failed: " . $e->getMessage());
}

Implementation Patterns

Workflow Integration

Testing with Laravel Dusk: PhantomJS is a dependency for Laravel Dusk. Install it via this package to ensure consistency across environments:

// In a DuskTestCase or custom test setup
public function setUp(): void
{
    parent::setUp();
    try {
        $this->artisan('dusk:chrome-driver');
    } catch (\Jakoch\PhantomJsInstaller\Exception\PhantomJsNotFoundException $e) {
        $this->fail("PhantomJS not installed. Run `composer install` first.");
    }
}

Headless Screenshots: Generate screenshots in Laravel commands or jobs:

public function renderScreenshot($url, $outputPath)
{
    try {
        $process = new Process([
            'phantomjs',
            'render.js',
            $url,
            $outputPath
        ]);
        $process->run();
        if (!$process->isSuccessful()) {
            throw new \RuntimeException("PhantomJS process failed: " . $process->getErrorOutput());
        }
    } catch (\Jakoch\PhantomJsInstaller\Exception\PhantomJsNotFoundException $e) {
        throw new \RuntimeException("PhantomJS not available: " . $e->getMessage());
    }
}

CI/CD Pipelines: Ensure PhantomJS is installed in GitHub Actions, GitLab CI, or CircleCI by running composer install before tests. Handle failures explicitly:

# Example GitHub Actions step
- name: Install PhantomJS
  run: composer install --no-interaction --prefer-dist
- name: Run tests
  run: php artisan test
  continue-on-error: true  # Optional: Decide based on your needs

Configuration Tips

Custom Binary Path: Override the default /bin/phantomjs path in your composer.json:

"extra": {
    "phantomjs-installer": {
        "binary": "custom/path/phantomjs",
        "binary-name": "my-phantom"
    }
}

Version Pinning: Specify a version in composer.json to avoid unexpected updates:
```
"jakoch/phantomjs-installer": "3.0.3"
```

Gotchas and Tips

Common Pitfalls

Exception Handling for Missing Downloads: The installer now throws a PhantomJsNotFoundException if PhantomJS downloads are unavailable (e.g., due to network issues or missing releases). Handle this explicitly in your code:

try {
    $installer = new \Jakoch\PhantomJsInstaller\Installer();
    $installer->checkAndInstall();
} catch (\Jakoch\PhantomJsInstaller\Exception\PhantomJsNotFoundException $e) {
    // Log or notify the user
    \Log::error("PhantomJS installation failed: " . $e->getMessage());
    // Optionally retry or fail gracefully
}

Permission Issues:
- On Linux/Mac, ensure /bin is writable:
```
chmod -R 777 /path/to/project/bin
```
- On Windows, ensure the bin directory exists and is accessible.
CI/CD Failures: Some CI environments (e.g., Docker) may lack system libraries or network access to download PhantomJS. Use a pre-built image or install dependencies first:
```
RUN apt-get update && apt-get install -y g++ make
```
For offline environments, consider using a local mirror or pre-downloaded binaries.

Debugging

Verify Installation: Check if PhantomJS is installed:
```
./bin/phantomjs --version
```
If missing, ensure the installer ran successfully:
```
composer dump-autoload && composer install
```

Logs: Enable verbose output in composer.json:

"scripts": {
    "post-install-cmd": [
        "Jakoch\\PhantomJsInstaller\\Installer::checkAndInstall --verbose"
    ]
}

Network Issues: If the installer fails due to missing downloads, check:
- Internet connectivity in your environment.
- Firewall/proxy settings blocking access to the PhantomJS download URL.
- The PhantomJS releases page for available versions.

Extension Points

Custom Installer Logic: Extend the installer to handle edge cases (e.g., fallback URLs or offline modes):

use Jakoch\PhantomJsInstaller\Installer as BaseInstaller;

class CustomInstaller extends BaseInstaller
{
    protected function getBinaryUrl()
    {
        try {
            return parent::getBinaryUrl(); // Try default
        } catch (\Jakoch\PhantomJsInstaller\Exception\PhantomJsNotFoundException $e) {
            return 'https://custom-mirror.com/phantomjs'; // Fallback
        }
    }
}

Post-Install Hooks: Run additional commands after installation via post-install-cmd:

"scripts": {
    "post-install-cmd": [
        "Jakoch\\PhantomJsInstaller\\Installer::checkAndInstall",
        "@php artisan cache:clear"
    ]
}

Windows-Specific Quirks:
- Use absolute paths in Windows:
```
$process = new Process([
    'C:\\path\\to\\project\\bin\\phantomjs',
    'script.js'
]);
```
- Escape paths with str_replace('\\', '\\\\', $path).
- Ensure the bin directory is in your system PATH for global access.

Offline Mode: Pre-download PhantomJS binaries and reference them locally:

"extra": {
    "phantomjs-installer": {
        "binary": "/path/to/local/phantomjs",
        "skip-download": true
    }
}

Phantomjs Installer Laravel Package