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.
Setting the project source files folder
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. Enter the location of your project source files in the Project source folder field. You can also use the Browse... button to browse for and select 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,
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. The default is the latest version.
PHP source language version
Finally, you should select the minimum PHP language version for the generated files. The default is based on saved preferences, and in version 12 will default to PHP 8.1. Tne setting should be chosen to be no lower than the PHP language version used by the source files. It will also determine the minimum PHP language version required to run files. Note: If you are upgrading from an earlier version or have used the evaluation version, the default will be different if user preferences have been adjusted. You can always reset preferences in the Preferences dialog if necessary.
For example, if your source code uses only PHP 5 syntax and you know that your end users will have at least PHP 7.2, selecting PHP 7.2 would be best as this is closest to the expected target PHP versions. If the source files use any PHP 8.1 language features then PHP 8.1 should be selected, and would be the minimum version required to run encoded files. If the Encoder reports parsing errors during encoding then the language version setting may be incorrect. As a guide for choosing a minimum PHP version, estimated usage of different PHP versions is available at w3techs and is updated daily.
If needing to produce files that can run on both PHP 5.6 and 7, there is also a "PHP 5.6 & 7.1" encoding option that produces a bundled encoding. In this case, encoded files contain both an encoding with PHP 5.6 as the source language and also an encoding based on PHP 7.1. The encoded files will then run on both PHP 5.6 and 7 with the appropriate ionCube Loader installed. Note that the source files must be language compatible with both PHP 5.6 and 7.1 for the bundled encoding to complete successfully.
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
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 Encode/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.
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 green if encoding was successful (example below), or blink red if there were errors. Once building is complete, your encoded files can be tested, packaged or deployed as required.
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, and the Loader API is also explained.
Copyright 2002-2022 ionCube Ltd. All rights reserved.