Migrating to v2022

PHPMaker 2022 is another huge upgrade from previous version, it includes a long list of new features. If you upgrade from v2021, there are no big changes. However, if you upgrade from version prior to v2019, please be reminded that v2019-2021 introduced some new features which are not fully compatible with old versions, make sure you read the following first:

Migrating to v2019
Migrating to v2020
Migrating to v2021

When opening an old project in v2022, PHPMaker will try to convert the changes for you. However, the conversion cannot be 100% and you'll need to do some updates yourself. Please read the follows carefully, review your code, update and test it before deploying the new scripts to your production server.

PHP >= 7.3

Requires PHP 7.3 or higher. Since security support for PHP 7.3 will end on 2021/12/6 (see Supported Versions on PHP official site), using PHP 7.4 or PHP 8.x is highly recommended.

Database Abstraction Layer (DBAL 3)

DBAL has been upgrade to DBAL 3. The following database platforms are no longer supported:

MariaDB 10.1 and older,
PostgreSQL 9.3 and older,
SQL Server 2008 and older.

There are breaking changes in DBAL 3. If you use only PHPMaker global functions, e.g. ExecuteQuery(), there should be no changes. However, if you use DBAL directly, you need to update your code, see Upgrade to 3.1 for details.

We still see some users trying to use ExecuteQuery() or the deprecated Execute() for all SQL statements. Please note that there is an ExecuteStatement() function. (Since DBAL 3 has replaced the executeUpdate() method by executeStatement(), PHPMaker has also deprecated ExecuteUpdate() in favour of ExecuteStatement().)

To execute SELECT statement and get the Doctrine\DBAL\Result instance for accessing the results by fetch API, use ExecuteQuery(), e.g.

$result = ExecuteQuery("SELECT...");

To execute INSERT, UPDATE, DELETE statements (or other statements that don't yield a row set) and get the number of affected rows, use ExecuteStatement(), e.g.

$rowAffected = ExecuteStatement("INSERT...");

See Data Retrieval And Manipulation and Server Events and Client Scripts for details.

Internationalization (i18n)

PHPMaker 2022 uses PHP Internationalization extension (intl) on server side and native JavaScript Intl object on the client side.

Make sure you have installed the PHP intl extension, this extension is bundled with PHP, see Installation for details.

The PHP intl extension is a wrapper for ICU library, enabling PHP programmers to perform various locale-aware operations. Intl consists of several modules, v2022 uses the follows:

Locale - provides interaction with locale identifiers.
Number Formatter - allows to display number according to the localized format or given pattern or set of rules, and to parse strings into numbers.
Date formatter - allows to display date and time according to the localized format or given pattern or set of rules, and to parse strings into date and time.

As a result, there are some breaking changes in this regard:

The old locale files from previous versions are not used anymore.
No need for locale files anymore if you use the default PHP locale settings. (You still can change locale settings and save them in project as before.)
The number and date/time format are changed to ICU DecimalFormat (see the Patterns section) and Date/Time Format Syntax.
On the client side, Moment.js is not used anymore. v2022 uses Luxon which uses native JavaScript intl API. If you use the jQuery .fields() plugin's toDate() method, the returned value is now a Luxon object instead of a Moment object. If you use Moment.js in your JavaScript code, you need to update it to use Luxon, see For Moment users for details.
The new date/time format is also used by the Datetime Picker and Time Picker extensions. If you specified your own date/time format, you need to update your extension settings.

Language Files

Due to change in internationalization, the language ID of the language files must be a locale identifier using RFC 4646 language tags (which use hyphen, not underscore). The language ID should includes the region (e.g. "en-US", "de-DE"), if applicable. The language ID of the default language file (english.xml) has also been changed from "en" to "en-US".

As always there are many new phrases in new major version, make sure you update your non-English language files, otherwise some phrases will be missing. The new or changed phrases are marked with  in the default language file.

Installation Folders

Previous versions of PHPMaker installed all files under the ProgramFiles folder (e.g. C:\Program Files (x86)\PHPMaker 2022), but Windows user may not have write permission to that folder. A typical problem is that some users cannot update the default template automatically. v2022 installs updatable files (e.g. template and extensions) in the AppData folder (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker2022). The non-updatable files are still installed under ProgramFiles folder.

If you need to access the AppData folder, you can view it manually by going into your Users folder, e.g. C:\Users\<user> where <user> is your Windows user name. The AppData folder is hidden by default, go to the "View" tab at the top and check the "Hidden items" checkbox, you should be able to see the AppData folder in your Users folder.

You can also access the AppData folder directly using the AppData system variable, just type "%APPDATA%" (without double quotes) into File Explorer's address bar to go directly to the AppData\Roaming folder. The "PHPMaker2022" (no spaces) folder is under this folder (e.g. AppData\Roaming\PHPMaker2022).

Template, Extensions, Custom View Tags and Custom Edit Tags

The structure of template, extensions, Custom View Tags and Custom Edit Tags are unified as npm package format. All of them are now installed under the node_modules folder (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker2022\node_modules), so they can be easily updated by running npm update at the Roaming folder.

Creating extensions, Custom View Tags and Custom Edit Tags are same as Creating Node.js modules. You can share your packages by publishing them to npm registry.

The structure of an extension is basically same as before, but with a few minor changes. If you make extensions, read Making Extensions for details.

Since Node.js with npm is now a system requirement, PHPMaker 2022 does not shipped the node.exe alone anymore. Always install the Current (not LTS) version of Node.js with npm 7, you can use 32-bit or 64-bit version according to your version of Windows.

Bootstrap 5

PHPMaker 2022 uses Bootstrap 5, so the theme variables are different from previous versions. When opening an old project in v2022, PHPMaker will try to update the variables for you. In most cases it should be fine. If not, you should go to the HTML -> Theme tab to re-select a theme. If you have added any custom CSS styles in your project (under the HTML -> Styles -> User tab) for Bootstrap 4, you may need to update your styles.

There are many changes in Bootstrap 5, see Migrating to v5. Bootstrap 5 does not support Internet Explorer, do not use IE anymore. You are free to use JavaScript ES6 in client side events now!

Since the default preview window (under HTML tab) is based on IE, so the styles may not be displayed correctly. It is recommended that you install Webview2 Runtime so the preview window can show the styles correctly.

Chart.js 3.x

Chart.js has been upgraded from v2.x to v3.x, there are many breaking changes, see 3.x Migration Guide. If you have Chart_Rendered server event or "chart" client side event handler, you may need to upgrade your code.

Multiple Parent User ID

Now multiple parent user ID is supported, if you want to use, simply change your Parent User ID Field data type to varchar with sufficient field size and update the Edit Tag to multiple selection.

Documentation

PHPMaker 2022 uses online documention, the help file (.chm) is not shipped with PHPMaker anymore.

Also See

Migrating to v2021
Migrating to v2020
Migrating to v2019