Upgrade Guide

To 5.0.0 from 4.0.0

This is a major version. The entire codebase has been modernized for PHP 8, dependencies were upgraded (including a major PHPMailer jump), every user-facing string was moved into the translation system, and a full automated test suite was added. Most files in the project changed, but the bulk of those changes are automated coding-style normalization (Laravel Pint / Rector) and are not breaking. The breaking and behavioral changes are listed below — review those carefully and treat the rest as cosmetic.

Because nearly every file was touched, do not copy your old files over the new release. Start from the 5.0.0 release and re-apply your customizations one file at a time, using the sections below as a checklist.

Requirements changed

Before upgrading, confirm your server runs PHP 8.0 or newer and has the curl, mbstring and pdo_mysql extensions enabled. The installer's requirement check (install/check.php) has been updated to enforce PHP >= 8.0, so a sub-8.0 environment will be blocked at install time.

Key files

Breaking & behavioral changes

1. How ASConfig.php is loaded

In 4.0.0, ASEngine/ASConfig.php was loaded automatically through Composer's files autoloader. In 5.0.0 it has been removed from the Composer autoload and is now required explicitly inside ASEngine/AS.php:

$configFile = getenv('AS_CONFIG_FILE') ?: dirname(__FILE__).'/ASConfig.php';
if (! file_exists($configFile)) {
    header('Location: install/index.php');
    exit;
}

include_once dirname(__FILE__).'/../vendor/autoload.php';
require_once $configFile;

What this means for you:

• The default behavior is unchanged — ASEngine/ASConfig.php is still the config file and a fresh install will create it there.
• You can now point the application at an alternate config file by setting the AS_CONFIG_FILE environment variable (useful for staging/testing or keeping config outside the web root).
• If you previously relied on ASConfig.php being autoloaded by Composer anywhere other than through AS.php (for example in custom scripts or your own bootstrap), load it explicitly there now, because composer.json no longer lists it under autoload.files.

2. PHPMailer upgraded from 6.x to 7.x

phpmailer/phpmailer was bumped from ^6.6 to ^7.1. The application's own email code (ASEngine/ASEmail.php) only changed cosmetically and continues to work, but if you customized email sending, added attachments, or configured SMTP options directly against the PHPMailer instance, review the PHPMailer 7.0 release notes for any API differences and re-test sending the confirmation and password-reset emails after upgrading.

3. All UI strings are now translatable

Previously many strings were hardcoded in the templates and pages. In 5.0.0 they have been extracted into the language files (Lang/en.php, de.php, es.php, fr.php, it.php, ru.php, sr.php, sv.php) and the views render them with trans('key').

What this means for you:

• If you translated or edited the UI text by hand in the template/page files, those edits will be lost when you take the new files. Move your changes into the appropriate Lang/*.php entries instead.
• If you maintain a custom language file, copy the new keys from Lang/en.php into your file so nothing renders as a missing/empty string.
• The trans() and respond() helper signatures are unchanged, so existing calls keep working.

4. New .htaccess (Apache)

A new .htaccess at the project root blocks web access to composer.json, composer.lock, phpunit.xml.dist, and the entire /tests directory (returns 403). This hardens the deployment so source/test files cannot be downloaded.

• On Apache, make sure AllowOverride permits .htaccess so these rules take effect.
• On Nginx or other servers, .htaccess is ignored — add the equivalent rules to your server config to deny access to composer.*, phpunit.xml.dist, and /tests.

Development tooling & tests (optional)

5.0.0 ships a development workflow that is not required to run the application but is recommended if you modify the code:

• composer install will pull the new require-dev packages (PHPUnit 9.6, PHPStan 2.1, Laravel Pint, Rector 2.x, Guzzle, symfony/process). On production use composer install --no-dev to skip them.
• Useful scripts:
  • composer check — validates composer.json, lints all PHP files, runs PHPStan.
  • composer test / test:unit / test:feature — run the test suites.
  • composer test:db:up / test:db:down — start/stop the Dockerized MySQL used by the feature/database tests (tests/compose.yml).

Upgrade checklist

1. Verify the server runs PHP 8.0+ with the curl, mbstring, and pdo_mysql extensions.
2. Back up your database and your existing ASEngine/ASConfig.php.
3. Deploy the 5.0.0 files (do not overwrite them with your old copies).
4. Run composer install --no-dev to refresh vendor/.
5. Restore/keep your ASEngine/ASConfig.php (or set AS_CONFIG_FILE).
6. Re-apply UI text customizations through Lang/*.php, adding any new keys to custom language files.
7. Confirm the new .htaccess rules are active (or replicate them on non-Apache servers).
8. Re-test login, registration, email confirmation, password reset, and social login.

To 4.0.0 from 3.0.1

In this release, the whole codebase is refreshed and updated to support the latest version of PHP. A lot of files have been changed, but for some of them, there are some minor cosmetic updates, like adding return types to class functions, so you don't have to update those files if you don't want to.

The list of modified files:

 ASEngine/AS.php                                            |   25 +-
 ASEngine/ASAjax.php                                        |   46 +-
 ASEngine/ASComment.php                                     |   54 ++-
 ASEngine/ASCsrf.php                                        |   42 +-
 ASEngine/ASDatabase.php                                    |   37 +-
 ASEngine/ASEmail.php                                       |   18 +-
 ASEngine/ASHelperFunctions.php                             |   29 +-
 ASEngine/ASLang.php                                        |   65 +--
 ASEngine/ASLogin.php                                       |  236 +++++-----
 ASEngine/ASPasswordHasher.php                              |   25 +-
 ASEngine/ASRegister.php                                    |  151 ++++---
 ASEngine/ASResponse.php                                    |   36 +-
 ASEngine/ASRole.php                                        |   60 +--
 ASEngine/ASSession.php                                     |   27 +-
 ASEngine/ASUser.php                                        |  139 +++---
 ASEngine/ASValidator.php                                   |   60 +--
 assets/css/bootstrap.min.css                               |   12 +-
 assets/css/bootstrap.min.css.map                           |    2 +-
 assets/js/app/index.js                                     |   16 +-
 assets/js/vendor/bootstrap.bundle.min.js                   |    7 -
 assets/js/vendor/bootstrap.bundle.min.js.map               |    1 -
 assets/js/vendor/bootstrap.min.css.map                     |    2 +-
 assets/js/vendor/bootstrap.min.js                          |    7 +
 assets/js/vendor/bootstrap.min.js.map                      |    1 +
 assets/js/vendor/dataTables.bootstrap4.js                  |  184 ++++++++
 assets/js/vendor/dataTables.bootstrap5.js                  |   14 -
 assets/js/vendor/jquery-validate/additional-methods.js     | 2462 +-
 assets/js/vendor/jquery-validate/additional-methods.min.js |    6 +-
 assets/js/vendor/jquery-validate/jquery.validate.js        | 3230 +-
 assets/js/vendor/jquery-validate/jquery.validate.min.js    |    6 +-
 assets/js/vendor/jquery.dataTables.min.js                  |  354 +++++++--------
 assets/js/vendor/jquery.min.js                             |    4 +-
 assets/js/vendor/popper.min.js                             |    5 +
 assets/js/vendor/popper.min.js.map                         |    1 +
 composer.json                                              |   10 +-
 composer.lock                                              |  405 +++++++++--------
 confirm.php                                                |    4 +-
 index.php                                                  |   18 +-
 install/check.php                                          |    2 +-
 install/stubs/config.stub                                  |    8 +-
 login.php                                                  |   74 ++--
 passwordreset.php                                          |    4 +-
 profile.php                                                |   14 +-
 socialauth.php                                             |  148 ++++++-
 socialauth_callback.php                                    |  148 +------
 templates/footer.php                                       |    3 +-
 templates/header.php                                       |    2 +-
 templates/languages.php                                    |   16 +-
 templates/navbar.php                                       |   14 +-
 user_roles.php                                             |    4 +-
 users.php                                                  |   54 +--
 51 files changed, 4031 insertions(+), 4261 deletions(-)

To 3.0.1 from 3.0.0

This is a bug-fix release. You will need to update the modified application files given below to the latest versions and run composer update (or just overwrite the vendor folder if you are not using composer).

Modified files:

 ASEngine/AS.php     |   2 +-
 ASEngine/ASUser.php |   2 +-
 assets/css/app.css  |   8 ++++++++
 composer.json       |   2 +-
 composer.lock       | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------
 login.php           |   2 +-
 socialauth.php      |   2 +-
 7 files changed, 126 insertions(+), 21 deletions(-)

To 3.0.0 from 2.4

Version 3, as another major version, has a lot of mainly frontend breaking changes and the only way to update it is to do do it manually and to update one file at the time.

The app now uses Bootstrap 4 and all frontend files are updated to match the new bootstrap classes. All javascript files are updated as well, so you will need to manually update your old javascript files.

Here are some guidelines that might help you in the update process:

• All JavaScript files are moved from ASLibrary folder to assets/js/app folder and ASLibrary folder is removed from the app.

• All application CSS files are now in assets/css folder.

• You can overwrite the complete install folder if you haven't removed it from the app. This will make sure that all future installations of the app work properly.

• Some of the backend files from ASEngine directory have been refactored, so it is recommended to update them too.

• The app now uses jQuery Validation plugin for frontend validation, which has it's own language files. The files are located inside assets/js/vendor/jquery-validate/localization directory in case you want to customize them.

• Overwrite your vendor folder with latest one. In case you modified something inside the vendor folder, just copy new files instead of overwriting. This version is using the most recent packages (which you can update by running composer update btw) so it is important that you update them so application can work properly (especially for social authentication feature).

• Update all files from Lang directory to the latest version, since version 3 of the app have a few more translation strings added.

To 2.4 from 2.3

This version contains few bug fixes from previous release. Here is what you wound need to do:

• Overwrite your vendor folder with latest one. In case you modified something inside the vendor folder, just copy new files instead of overwriting. This version is using the most recent packages (which you can update by running composer update btw) so it is important that you update them so application can work properly (especially for social authentication feature).

• Copy new file called socialauth_callback.php to your AS root directory.

• Update socialauth.php file with the latest one.

• Update your social callback url to look like following: http://yourdomain.com/socialauth_callback.php

• Update ASEngine/ASCsrf.php file to the latest version.

• Overwrite complete install folder if you haven't removed it from the app. This will make sure that all future installations of the app work properly.

• Make sure that your ASEngine/ASDatabase.php file is up to date with latest version.

• Update ASEngine/ASLang.php file to match the latest version.

• Update ASEngine/ASEmail.php file to match the latest version.

• Make sure that you have de.php file inside your Lang folder and then update templates\languages.php file to add German language to the top list of available languages. Also, if you want to display German flag there, you can copy it from the latest version where it is located inside assets\img folder.

To 2.3 from 2.2

This update contains a lot of changes comparing to previous version, and in order to properly do the update, I recommend you to go through all files and carefully update them. In case you haven't modified any of AS files, just overwrite everything and there should not be any issues.

Here are some guidelines on how you should perform the update:

Vendor Folder

Overwrite your vendor folder with latest one. In case you modified something inside the vendor folder, just copy new files instead of overwriting.

Install Folder

Completely replace the install folder. This is not required if you have app in production, since you won't install it again.

ASConfig

Since SESSION_REGENERATE_ID constant is removed, and session is regenerated always when some critical actions occur (after successful authentication, after user update his password etc), you can remove the constant from your ASConfig.php file.

Add following constants to ASConfig.php file:

// Name used when emails are sent from your server. 
// Default is your website name.
define('MAIL_FROM_NAME', "your_mail_from_name_here");

// Email used when emails are sent from your server.
// The recepients will see this as an email from
// which they receive their emails.
define('MAIL_FROM_EMAIL', "your_from_email_here");

PHP Classes

Copy new classes into ASEngine folder Update ASEngine\AS.php file to the latest version

Go through all PHP classes, one by one, and move all dependencies to the constructor. For example, if somewhere inside ASUser class you have $validator = new ASValidator(); you will create new protected $validator; property and move the ASValidator instance to be passed through the constructor (check latest version of ASUser class). Now, everywhere inside ASUser class you will use validator instance like $this->validator

This has to be done with all dependencies in every PHP class that AS has, and the easiest way to find all dependencies is to simply search the file for "new" keyword. This is simple preparation for some future updates that will modernize the code structure and make script testable and easier to maintain.

Assets

You should update assets folder to match the latest version. This basically means that you must copy all new files and folders from latest version, but you don't have to remove old files if you don't want to. Script will just ignore them if they are not included on your pages.

Update ASLibrarly/js/users.js, ASLibrarly/js/roles.js and ASLibrarly/js/register.js to the latest version that contains few fixes. Other JavaScript files located inside ASLibrary/js folder are not modified.

Copy newly created js-bootstrap.php file into ASLibrary/js directory.

Pages

Go through all pages (login.php, index.php...) and apply all changes from latest version. If you haven't modified those files, you can just overwrite them.

In case that you are using your own design, you probably don't need to change anything that is HTML/CSS/JavaScript related. All you have to do in that case is to update the query that is responsible for fetching data and displaying it to database (usually located on top of every file).

Update templates/footer.php to include some common scripts as well as newly created js-bootstrap.php file that is now used to initialize $_lang variable and set up jQuery AJAX to send CSRF token automatically. This means that you should now remove $_lang variable initialization from any other files than js-bootstrap.php.