uuf6429/electron-installer

A Composer package which installs the Electron binary (Linux, Windows, Mac) into `/bin` of your project.

v2.0.0 2022-01-01 01:24 UTC

Requires

• php: ^7.2 || ^8.0
• ext-bz2: *
• ext-json: *
• ext-openssl: *

Requires (Dev)

• composer/composer: ^1 || ^2
• phpunit/phpunit: ^8

MIT

• Christian Sciberras
• Jens-André Koch

• headless
• binaries
• electron

README

A Composer package which installs the Electron binary (Linux, Windows, Mac) into /bin of your project.

Table of Contents

• Installation
• How to require a specific version of Electron?
• How does this work internally?
• How to access the binary easily by using ElectronInstaller\ElectronBinary?
• How to package for another platform by overriding platform requirements?
• How to use a Mirror or a custom CDN URL for downloading?

Installation

To install Electron as a local, per-project dependency to your project, simply add a dependency on uuf6429/electron-installer to your project's composer.json file.

{
  "require": {
    "uuf6429/electron-installer": "^2"
  },
  "scripts": {
    "post-install-cmd": [
      "ElectronInstaller\\Installer::installElectron"
    ],
    "post-update-cmd": [
      "ElectronInstaller\\Installer::installElectron"
    ]
  }
}

For a development dependency, change require to require-dev.

The default download source used is: https://github.com/electron/electron/releases/ You might change it by setting a custom CDN URL, which is explained in the section "Downloading from a mirror".

By setting the Composer configuration directive bin-dir, the vendor binaries will be installed into the defined folder. Important! Composer will install the binaries into vendor\bin by default.

The scripts section is necessary, because currently Composer does not pass events to the handler scripts of dependencies. If you leave it away, you might execute the installer manually.

Now, assuming that the scripts section is set up as required, the Electron binary will be installed into the /bin folder and updated alongside the project's Composer dependencies.

How to require specific versions of Electron?

The environment and server variable ELECTRON_VERSION enables you specify the version requirement at the time of packaging.

You can also set the electron-version in the extra section of your composer.json:

{
  "extra": {
    "uuf6429/electron-installer": {
      "electron-version": "16.0.0"
    }
  }
}

The search order for the version is $_ENV, $_SERVER, composer.json (extra section), fallback to the latest version on GitHub.

How does this work internally?

Fetching the Electron Installer

In your composer.json you require the package "electron-installer". The package is fetched by composer and stored into ./vendor/uuf6429/electron-installer. It contains only one file the ElectronInstaller\\Installer.

Platform-specific download of Electron

The ElectronInstaller\\Installer is run as a "post-install-cmd". That's why you need the "scripts" section in your " composer.json". The installer creates a new composer in-memory package "electron", detects your OS and downloads the correct Electron version to the folder ./vendor/uuf6429/electron. All Electron files reside there.

Installation into /bin folder

The binary is linked from ./vendor/uuf6429/electron to your composer configured bin-dir folder.

Generation of ElectronBinary

The installer generates a PHP file ElectronInstaller/ElectronBinary and inserts the path to the binary.

ElectronBinary

To access information about the binary, the class ElectronBinary is created automatically during installation.

The class defines the following constants:

• BIN is the full-path to the Electron binary file, e.g. /your_project/bin/electron
• DIR is the folder of the binary, e.g. /your_project/bin
• VERSION the version used during the installation, e.g. 16.1.2

Usage:

<?php 

use ElectronInstaller\ElectronBinary;

$bin = ElectronBinary::BIN;
$dir = ElectronBinary::DIR;
$version = ElectronBinary::VERSION;

Override platform requirements

The environment and server variables ELECTRON_PLATFORM and ELECTRON_ARCHITECTURE enable you to override the platform requirements at the time of packaging. This decouples the packaging system from the target system. It allows to package on Linux for MacOSX or on Windows for Linux.

Possible values for

• ELECTRON_PLATFORM are: darwin, win32, linux.
• ELECTRON_ARCHITECTURE are: ia32or x64.

Downloading from a mirror

You can override the default download location of the Electron binary file by setting it in one of these locations:

• The environment variable ELECTRON_CDNURL
• The server variable ELECTRON_CDNURL
• In your composer.json by using $['extra']['uuf6429/electron-installer']['cdnurl']:

{
 "extra": {
   "uuf6429/electron-installer": {
     "cdnurl": "https://github.com/company/electron/releases/download/v16.0.0/"
   }
 }
}

Default Download Location

The default download location is GitHub: https://github.com/electron/electron/releases/. You don't need to set it explicitly. It's used when ELECTRON_CDNURL is not set.

Automatic download retrying with version lowering on 404

In case downloading an archive fails with HttpStatusCode 404 (resource not found), the downloader will automatically lower the version to the next available version and retry.

A couple of notes on this behaviour:

• The number of retries is determined by the number of Electron versions in getElectronVersions().
• Since you can only request one specific version, it is possible to fall back to a very old version, if all others failed for some reason.
• On the next composer update/install, it will go through this process again. Therefore, it is possible that having a lot of broken versions could slow the installation process.