2. Quickstart Guide
This section shows the basic steps for creating a new project and encoding files. There are also a few example projects included that can be opened and encoded immediately. Available features are described in depth in later sections. A separate document, the User Guide PDF, explains all of the Encoder command line options, as well as other topics such as the Loader API, and is recommended to read as well. If you are using the full version of the Encoder rather than the evaluation and have not yet licensed the product, the section Licensing the Encoder will explain that process.
Having started the application from the item provided in the Windows Start Menu, the following window will appear:
Note: News articles and the default window size will vary.
Creating a new Encoder project (method 1)
An Encoder project stores all the settings necessary to encode a PHP project in the way that you want. Typically there would be one Encoder project for each PHP project, or variation of a project, that you have.
To create a new project, either click the Create New Project... item
on the left of the startup window, choose the File/New Project... menu
item or click the first toolbar icon
.
An unconfigured project will
be created and the Project Settings dialog will soon appear. The
Encoder has many features, and the available project settings are
grouped on different tabs according to their function. For now we will
just configure the options present on the Quickstart tab, which
allows for quick setup of the minimum settings required to encode
a project.
The Quickstart tab
With the project settings dialog open, first select the Quickstart tab if it is not currently active. This tab combines the minimum settings that need to be configured for a project.
Setting the project source files folder
Enter the location of your project source files in the Project source folder field. You can also use the Browse... button to browse for a location.
Setting the target folder name and location
Click or tab-into the Target folder name field. If the field is empty it will then be auto-filled with the name of the source folder set previously. This is the name of the folder where encoded files will be created. It can be changed if you wish.
The location of the target folder should also be set in
the Location of project target folder field, for example,
C:\encoded-projects
Selecting the Encoder version
In addition to the current version, the previous two major versions of the Encoder are also provided. This gives you flexibility in case you want to produce older generations of encoded files. Selecting Current ensures that the project will be encoded using the latest Encoder version of the GUI that opens the project, i.e. a newer Encoder will be used if opening the project with a newer GUI version. Alternatively, an explicit version can be selected instead. This is useful if wanting to encode with a specific Encoder version even after upgrading the product, allowing you to choose when to move to a project to a newer Encoder, independently to the GUI.
PHP language range
Finally, you should select the minimum and maximum PHP runtime version you wish to support for the generated files. The selection determines which encodings will be performed, with files in some cases containing a Bundle of more than one encoding. Below the selection, the GUI shows which runtime versions of PHP are supported by the selection.
The default is based on saved preferences, and in version 14 will default to PHP 8.3 if this is the first installation of the software on the machine.
The minimum version should be chosen to be no lower than the PHP language version used by the source files. For example, files cannot be encoded for PHP 7 if they use syntax only available in PHP 8.
Example 1: your source code uses only PHP 7 syntax, and you know that your end users will have at least PHP 7.2 and not PHP 8. You could select the range as PHP 7.2 to PHP 7.4, to produce files that can run on PHP 7.2 or higher, but not PHP 8. There will be a single encoding in each file.
Example 2: your source code uses only PHP 7 syntax, it is compatible with PHP 8, and you want it to run up to the current maximum supported PHP version of 8.3. You might select PHP 7.1 to PHP 8.3. This will produce files with a bundle containing an encoding for PHP 7.1, 8.1 and 8.2. The PHP 7.1 encoding will cover PHP 7.1 to 7.4, a PHP 8.1 encoding targets PHP 8.1, and the 8.2 encoding targets both PHP 8.2 and 8.3; this is because the ionCube runtime for PHP 8.3 can process files encoded for PHP 8.2 as well.
As a guide for choosing a minimum PHP version, estimated usage of different PHP versions is available at w3techs
Final steps
The steps above are the minimal steps for setting up a project. Before moving on to encoding the project, take a moment to look at the Source tab.
If the source folder exists, the Project files section
on the Source tab will show your project files as a hierarchical
tree, with different icons to indicate how the Encoder will process each file
and folder. Files that match the default PHP extensions will be
encoded (
), others will be
copied (
), and any files or
folders matching the default excluded item patterns will not be
processed (
). If you
right click on files and folders in the tree,
a popup menu is displayed with actions to change how the Encoder will process the item. If multiple
items in the tree are selected, an action will be applied to all selected items.
The icon buttons above the tree can also be
used for this purpose.
Clicking OK will close the project settings.
The title bar will now be similar to the following.
The project has not yet been saved so the titlebar shows that the project is untitled, and
the * character indicates that the project has been modified. The PHP version to be
used for encoding is also shown to help reduce the chance of opening a project configured for the wrong PHP version,
which might happen if you have similar projects set with different versions.
The title also confirms that the software is licensed.
Project creation (method 2) - the project Wizard
An alternative to the process above is to use the project Wizard 
. This also collects the minimal information required to have a usable project, and having used the Wizard,
the project settings dialog can be opened to configure other settings as required.
Building (encoding) your project
You are now ready to build your project. Choose
the Build/Build (Rebuild) menu option, press the F5 key, or click the Start Building
toolbar icon 
. The precise behaviour of the build option
can be set within project settings on the Target tab, and by default will do a full rebuild by first
deleting the target folder if it already exists. Other options are to replace existing
files in the target folder without deleting (merge), or only to process files where
the source file either is new, or has a timestamp newer than that of the target file (Update).
A backup option also exists that renames any existing target before creating a new one.
The exact behaviour is also indicated in the name of the Build menu item.
Single PHP version encoding
The screenshot below is an example where encoding was for a single PHP version. Depending on the PHP language version, this may produce files that run only on that version, or a range of PHP versions may be covered with the single encoding. Files will be processed after starting a build, and the first status indicator icon in the bottom right corner of the window will turn yellow while the Encoder is running. The Event Log tree in the main window will show how items have been processed as well as any warnings or errors. The encoding indicator will be blinking green if encoding was successful (example below), or blink red if there were errors. Clicking the encoding indicator returns it to solid green; this can be done if desired but is merely a visual change. Once building is complete, your encoded files can be tested, packaged or deployed as required.
Multiple PHP version (Bundle) encoding
The screenshot below is an example of a bundle encoding, where files contain several encoded versions of a file to cover a wide range of target PHP versions. In this example, encoding was selected to cover PHP 7.1 to 8.2. Three separate encodings are performed, which cover the range 7.1 to 8.3, with 8.3 supported as well because files encoded for PHP 8.2 can also run on PHP 8.3. Where possible, the ionCube Loader runtime component uses complex translation and dynamic recompilation techniques to support running files compiled for earlier versions of PHP, which is one of the unique advantages of ionCube over alternatives.
Now that you have completed the Quickstart guide, a good place to continue reading is with the project settings. The PDF User Guide is also a useful source for reference. As well as describing every Encoder command line option in detail, which may be useful even though you are using the GUI, the licensing features of the Pro and Cerberus Encoder are given. The Loader API is also explained.