Installation - PhpGt/WebEngine GitHub Wiki

The recommended installation technique is to use Composer to globally install PHP.Gt and run a local development server through the gt commands.

The automated installer will get your computer set up automatically and enable the gt commands in your terminal. It will explain what it is doing before each step. To run it, paste this into your Bash terminal:

curl https://install.php.gt | bash

Important! Never run the automated installer on a production server. Piping a command from the internet into your bash prompt could be used by a malicious user as a vector of attack. Even on a development computer it is a good idea to inspect the install script before executing. You can do this in three steps:

  1. wget https://install.php.gt -O install.sh
  2. less install.sh
  3. bash install.sh

This technique may not be possible or preferable to all developers, so this section will explain different approaches to installing the WebEngine development environment.

Manual global installation (for gt commands)

Composer can be used to globally require a package, exposing the package's bin commands to the PATH.

1. Install Composer

On Debian-based Linux systems, you can install Composer using apt install composer. On Macintosh using Homebrew, you can install Composer using brew install composer.

Without a package manager, installation instructions are provided on Composer's installation page, which allow you to control how and where Composer is installed.

2. Globally require PHP.Gt's installer

Once Composer is installed on your system, run the command composer global require phpgt/installer to download the installer repository to Composer's own directory (rather than the default behaviour of using the current directory).

3. Adding Composer's bin directory to your PATH

Assuming you have installed Composer somewhere like ~/.composer, to get access to the gt command, you will need to add Composer's bin directory to your PATH environment variable.

This can be achieved by placing export PATH=~/.composer/vendor/bin:$PATH as the last line of your ~/.bash_profile (or ~/.bashrc) files, for example. To learn more about adding directories to your PATH environment variable, check the documentation for your system.

Once Composer's bin directory is in your PATH environment variable, you should be able to run gt commands. Typing gt on its own will show a list of all available commands.

Manually installing per-project

There is no requirement to use WebEngine through the gt commands - it can be required through Composer per project. You won't get the convenience scripts of creating, releasing or deploying projects automatically from the terminal, but no functionality is lost doing it this way.

1) Require phpgt/webengine

In a new project directory, run composer require phpgt/webengine, or add the following block to your composer.json file:

"require": {
	"phpgt/webengine": "3.*"
}

2) Configure your project

You can control a lot of the internal mechanisms of WebEngine by adding lines to the config.ini file. This is optional, but you may want to develop your application in its own namespace named something other than App which is default. Read about configuring your project

General system requirements

The system requirements to run a WebEngine application are very minimal: PHP 7.2 with a few common extensions enabled. All other requirements will be managed by Composer automatically.

Requirements

  • ext-curl curl_multi is used by php.gt/fetch to perform asynchronous HTTP requests
  • ext-mbstring to work with php.gt/dom, different character encodings must be handled
  • ext-json for outputting API Views
  • ext-xml for loading and working with DOM Documents

Optional system requirements

  • ext-fpm if you are serving using Nginx or Apache
  • ext-pdo for connecting to databases - see Database setup for more information
  • ext-mysql for connecting PDO to MySQL
  • ext-sqlite for connecting PDO to SQLite

Non-PHP software:

  • scss for compiling Sass CSS - see SCSS compilation for more information
  • webpack with babel for compiling EcmaScript 6 - see ES6 compilation for more information
  • rsync for organising client-side assets - see Rsync setup for more information

Running locally on Windows, Linux or Mac

To serve your application, compile your client-side files and run your tests, you can use the gt commands from the terminal. If PHP.Gt is installed globally, these are available from the gt command, but if global installation isn't possible for you, you can still run them from within your project's vendor/bin directory.

First of all, your project needs to download WebEngine using Composer:

  • If Composer is installed globally, the composer command should be available from your terminal.
  • If Composer is not installed globally, you can download composer.phar into your project directory as described on the Composer download page.
  • Run composer require phpgt/webengine (or php ./composer.phar require phpgt/webengine if you have used the Phar option) to install the dependencies into the project's vendor/ directory.
  • Once the dependencies are installed, run php vendor/bin/serve and place some content within page/index.html to validate that you can view the response on http://localhost:8080.

Once you have a working installation, you can run the other gt commands to manage your project, in isolation from other software on your computer.

PHP.Gt requires a modern PHP 7 interpreter to run. If you have a clashing version of PHP installed already, you can install and pass a different interpreter to composer. For example: /usr/bin/php-7.2/php composer.phar require phpgt/webengine for Unix systems, or C:\etc\php\7.2\php.exe composer.phar require phpgt/webengine On Windows. See PHP environment setup for more information

Using a web server (Nginx, Apache or PHP's inbuilt server)

The request response lifecycle of WebEngine applications start at the webserver level and are all routed through the go.php script. For security, a nested www/ directory is required as the document root.

Any web server software can be used to serve WebEngine applications. Setting up Nginx, Apache or PHP's built in server is explained in the web servers section.

Compiling client-side assets yourself.

When running your application using the gt run command, a build watcher script is initiated that compiles SASS, ES6 and other client-side preprocessor languages, but when running your own server the client-side compilation has to be handled separately.

One method of doing this is to run gt build --watch (or `vendor/bin/gt build --watch), which performs the inbuilt client-side build script and keeps it running on files as they change, which can be configured to work with your client-side tools of choice as described in the client-side assets section.

Another method is to use your own tools, such as npm/gulp/grunt/etc. These can be configured yourself without getting in the way of WebEngine, as long as the compiled files always end up in the www/ directory.

The client-side assets section explains the process in more detail.

Running from Docker

Docker is a great tool for creating, deploying and running applications that have all of their infrastructure, tools, libraries and frameworks wrapped up in their own Container.

Docker is similar to a Virtual Machine, but without the overhead of running an entire virtual operating system within your development computer.

The process of running a WebEngine application in a fully containerised setup is described in the using Docker section.

Running from a Virtual machine

Virtualbox

Virtualbox is a tool for running entire virtualised operating systems within a host operating system. This allows you to configure local server environments without affecting the operating system on your physical computer.

Using Virtualbox on its own to run WebEngine allows developers to set up their virtual operating system exactly how they want to, in case they have any particular preferences that don't match the automated routes.

A guide to setting up Virtualbox for WebEngine development is in the using Virtualbox section.

Vagrant

Vagrant is a management tool for different types of virtual machine, including Virtualbox. It provides a scriptable and predictable way of setting up a machine.

A guide to setting up Virtualbox with Vagrant for WebEngine development is in the Using Vagrant section.