Phantomjs Installer Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require jakoch/phantomjs-installer
   

   Add to composer.json under require-dev if PhantomJS is only needed for testing:

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

2. 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.

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

   use Symfony\Component\Process\Process;
   use Symfony\Component\Process\Exception\ProcessFailedException;
   
   $process = new Process(['phantomjs', '--version']);
   $process->run();
   if (!$process->isSuccessful()) {
       throw new ProcessFailedException($process);
   }
   

Implementation Patterns

Workflow Integration

1. 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();
       $this->artisan('dusk:chrome-driver');
   }
   

2. Headless Screenshots: Generate screenshots in Laravel commands or jobs:

   public function renderScreenshot($url, $outputPath)
   {
       $process = new Process([
           'phantomjs',
           'render.js',
           $url,
           $outputPath
       ]);
       $process->run();
   }
   

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

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": "2.1.0"
  

Gotchas and Tips

Common Pitfalls

1. 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.

2. Missing Dependencies:

   • PhantomJS requires g++ on Linux. Install via:

     sudo apt-get install g++
     

   • On macOS, use Homebrew:

     brew install phantomjs
     

     But disable auto-install in this package to avoid conflicts.

3. CI/CD Failures:

   • Some CI environments (e.g., Docker) may lack system libraries. Use a pre-built image or install dependencies first:

     RUN apt-get update && apt-get install -y g++ make
     

Debugging

• Verify Installation: Check if PhantomJS is installed:

  ./bin/phantomjs --version
  

  If missing, run:

  composer dump-autoload && composer install
  

• Logs: Enable verbose output in composer.json:

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

Extension Points

1. Custom Installer Logic: Extend the installer by subclassing Jakoch\PhantomJsInstaller\Installer:

   use Jakoch\PhantomJsInstaller\Installer as BaseInstaller;
   
   class CustomInstaller extends BaseInstaller
   {
       protected function getBinaryUrl()
       {
           return 'https://custom-cdn.com/phantomjs';
       }
   }
   

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

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

3. 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).