Installation

The recommended installation technique is to use Composer to globally install PHP.Gt and run a local development server. This approach is described in the quick start section.

However, that technique may not be possible or preferable to all developers, so this section will explain how to install different environments for WebEngine development.

Composer's autoloader is required to load all the classes of WebEngine and your application, but can be utilised without global installation of Composer or PHP.Gt's installer. Follow the guide for your particular platform to get developing.

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.