The master_2020 version can only be loaded over a database that was previously updated to master_2019.2. So please make sure you are running on the most current version of master_2019.2 before you upgrade to master_2020. Note that an error will be reported if an attempt is made to update from a pervious version.
Needless to say, master_2020 is a major update for SimpleInvoices. For one thing, it requires that you are running on a version of PHP 7.4 or greater. Although it might work on previous versions, there is no guarantee that will always be the case. The benefit of of PHP 7.4 is faster processing and greater security. From a development perspective it provides better features to use in development of applications such as SimpleInvoices.
The most major change made in the master_2020 is the removal of Zend Framework 1 libraries. Areas affected by this change include:
- Session handling
- Access Control List (ACL) logic that determines what you can access based on the user type you are logged in as
- Formatting libraries used for numbers, currencies and dates
- Application logging
- Access to configuration file settings
Additionally, this update uses Composer and Node for vendor and jQuery library maintenance. This change helps automate the process of keeping support libraries up to date.
master_2020 has an updated report generation system. In previous versions, only the Statement of Invoices report presented buttons to Print, Export to PDF, XLS or DOC files and an Email option. The new report framework supports these options for all reports. Also, the presentation of the reports was standardized so the look of all reports is the same.
There are two configuration files in master_2019.2: config.php & custom.config.php. In master_2020 these are changed to the .ini files: config.ini & custom.config.ini. The config.ini file contains all key/value settings that are needed to configure SimpleInvoices and is maintained as part of the SimpleInvoices code. The custom.config.ini file is the runtime version that contains the same config.ini file keys but with values set for your implementation (DB name, user & password, etc). A process is included in the master_2020 update to convert your “custom.config.php” file to the new “custom.config.ini” file format.
Additionally, logic now exists to assure that any new command key lines in config.ini are automatically added to the custom.config.ini file. Additionally, any lines in the custom.config.ini file that are not in the config.ini file are set within comments that indicate they are not used by the current update. These options will be ignored by the standard code and if you don’t have special code that uses them, they should be removed from the custom.config.ini file.
Also worth noting is the the current version information in the updated config.ini file is copied to the custom.config.ini file and can be viewed via the About menu option in the SI header. You can also view the Change Log file to see what has changed in each version.
Update SimpleInvoices version
The version update process is fairly straight forward:
- Export and save a copy of the full database.
- Save a backup copy of the whole directory by renaming it.
- Download the update zip file from GitHub.
- Extract the zip file in your document root directory.
- Rename the extracted directory to what you had before.
- Copy the custom.config.ini file from the old to the new config directory. Note that if converting from master_2019.2 to master_2020, you will be copying that custom.config.php file. In this case, you must follow the instructions in the Update to master_2020 from master_2019.2 instructions below.
- Run SimpleInvoices.
There are special instructions for updating from a previous SI version to the current version. These basically follow the same steps.
There are two backup steps to perform:
- Select the Backup Database option on the SimpleInvoices Settings tab and follow the instructions to backup your database. This will store the backup in the tmp/database_backup directory. You can leave the backup there.
- Rename your SimpleInvoices directory to something like, simple_invoices_yyyymmdd_b4_update. The rename moves all content of your current SimpleInvoices directories, preserved for easy recovery if needed.
Update to master_2019.2 from old SimpleInvoices version
- Make sure you have performed the actions in the Backup First topic.
- Download the “master_2019.2” version of SimpleInvoices.
- Extract the content of the downloaded “simpleinvoices-master_2019.2.zip” file into the “document root” directory of your webserver.
- Rename the new directory, “simpleinvoices-master_2019.2“, to the name of the SimpleInvoices directory you renamed in the Backup First topic.
- From the renamed/old SI config directory, check if you have a file named “custom.config.php“. If so, copy it to the new SI config directory. If not, make a copy of the old config.php file, naming it “custom.config.php“, then copy this file to the new SI config directory. Note that updates only overlay the config file which is then used by SI to update your custom.config.php file.
- Verify that you have both a config.php and a custom.config.php file in the new directory. From this point forward, all your configuration changes will be made to the custom.config.php file.
- If you have your own business invoice template, copy your company logos from the backup templates/invoices/logos directory to the updated install template/invoices/logos directory. Next copy the directory your business template is in, from the templates/invoices directory of your old version to the templates/invoices directory of the new version.
Proceed to the, First Use Of Update, topic instructions below.
NOTE: This update modifies the database to implement the use of Foreign Key logic to assure database consistency. If upon First Use Of Update, the patch process reports an error for foreign key update, refer to the Foreign Key Update error section below.
Update to master_2020 from master_2019.2
- Make sure you have performed the actions in the Backup First topic.
- Download the “master_2020” version of SimpleInvoices.
- Extract the content of the downloaded simpleinvoices-master_2020.zip file into the document root directory of your webserver.
- Rename the new directory, simpleinvoices-master_2020, to the name of the SimpleInvoices directory you backed up in step 1.
- Copy the custom.config.php file backed up in step 1 into your SimpleInvoices config directory. Note: Leave this file named custom.config.php. It will be updated to custom.config.ini by the si2020Converter.php program executed in the following steps.
- If you have your own business invoice template, copy your company logos from the backup templates/invoices/logos directory to the updated install template/invoices/logos directory. Next copy the directory your business template is in, from the templates/invoices directory to the templates/invoices directory.
- Using a text editor (notepad, Notepad++, etc.), open the file, si2020Converter.php file located in your SimpleInvoices root directory, and change the setting of the “$secure” variable on line 2, from “true” to “false“. Save the file.
- In your browser run this program. For example, if your root directory is simple_invoices then in the browser address line enter, simple_invoices/si2020Converter.php. If this runs successfully, a green result line will be displayed. This program makes the new custom.config.ini file from the content of the old custom.config.php file.
- Now in your text editor used in step 7, change the “$secure” setting of the si2020Converter.php file back to “true” and save the change. You can also delete the old custom.config.php file from the config directory. The “$secure” setting of “true” prevents this program from being run again.
Proceed to the, First Use Of Update, topic instructions below.
Update to the current, minor version/update Instructions
The version number is found in the versionName field of the config/config.ini file. It is in the form of MAJORVERSION.MINORVERSION.UPDATE. For example, 2020.3.19 is the major version, 2020, minor version, 3, and update, 19.
The change in a minor version and/or update does not alter the basic requirements (typically PHP version) of the application. A minor version/update does not change the name of the update on GitHub, Whereas a major version change does. For example, master_2020 is a major version update from master_2019.2. Which is why there are special instruction needed when updating from one to the other.
For minor version/update updates, follow these steps:
- Make sure you do what it says in the Backup First topic.
- In your browser, download the current version you wish to update to.
- Unzip the download file. It will create a directory named the same as the zip file .
- Rename this new directory to the name of original directory for your SI implementation.
- Copy the custom.config.ini file from your previous SimpleInvoices directory and save it in the config directory of the updated SimpleInvoice installation. Note that any changes to the content of the new version of the config/config.ini file will be automatically added to the config/custom.config.ini file when you first access the updated version.
- If you have your own business invoice template, copy your company logos from the backup templates/invoices/logos directory to the updated templates/invoices/logos directory. Next copy the directory your business template is in, from the templates/invoices directory you backed up, to the updated templates/invoices directory.
Proceed to the next topic, First Use Of Update.
First Use Of Update
- Access the updated SimpleInvoices site. If authentication is enabled, log in as your normal administrative user. If at this point you have a page that says you need to set up your database, then the custom.config.ini file has not been properly set up. This issue must be fixed before you proceed. Note: One common problem when converting from master_2019.2 to master_2020, is the databasePassword value needs to be withing quotes. Check if this is the case, fix it and try again.
- If there are NO database updates (aka patches) to perform, just start using SimpleInvoices.
- If there ARE database updates, you have two quick actions to perform.
- You will be on the patch page at this point. This page lists all SimpleInvoices patches that need to be applied. Scroll down the list to see what unapplied patches are pending. They are at the bottom of the list. Select the button to apply the patches.
- You will now be on the page that lists all the patches, showing that they have all been applied.
- Click the button on the applied patches review page and begin using your updated SimpleInvoices.
If You Have Special Code
There are three types of special code other than custom invoices templates. They are:
- Custom Hooks – These are changes made to the hooks.tpl file in the custom directory. You need to transfer these changes to the same file in the new installation. Verify they are current and work for the new version.
- Extensions – These are the proper way to add new functionality to SimpleInvoices. You will need to copy the directory containing your extension to the extensions directory of the new install. You will then need to review your extension code to make sure it is current for any changes to the standard files that need to be incorporated into your extension file. Test your extension to make sure it functions correctly.
- Changes to the standard code – Hopefully you kept copious notes and comments on these changes because you have to track them down and implement them in the new version. HOWEVER, when you incorporate it into the new version, do it as an Extension or via the Custom Hooks feature. Then your life will be more simple the next time you update.
Test your changes and you are ready to us the updated version of SimpleInvoices.
Unable to set Foreign Keys Error Handling
One of the major changes with master-2019.2 is the implementation of foreign key support in the database. This replaces the partial support implemented in prior versions. If you want to know more about foreign key support, please refer to this topic in the How To … menu option.
Foreign key support is implemented in patch #318. If you get the error, “Unable to set Foreign Keys,” the update process will stop after applying all patches up to #318 and will report pertinent error information in the tmp/log/php.log file. Look in this file to see what error(s) have been found. The first part of the error information is an explanation of what has been found. Here is the explanatory text:
Unable to apply patch 318. Found foreign key table columns with values not in
the reference table column. The following list shows what values in foreign
key columns are missing from reference columns.
There two ways to fix this situation. Either change the row columns to reference
an existing record in the REFERENCE TABLE, or delete the rows that contain
the invalid columns.
To do this, the following example of the SQL statements to execute for the test
case where the ‘cron_log’ table contains invalid values ‘2’ and ‘3’ in the
‘cron_id’ column. The SQL statements to consider using are:
UPDATE si_cron_log SET cron_id = 6 WHERE cron_id IN (2,3);
—- or —-
DELETE FROM si_cron_log WHERE cron_id IN (2,3);
The pertinent information to your system then follows in a table that displays all the information you need to correct the error. The following example shows a case where there are orphaned si_invoice_items table record(s) relative to the invoice_id column with a value of “1” that ties back to the id column of the si_invoices table. Here is the example of this:
invoice_items invoice_id invoices id 1
Using this information, you can decide to perform an UPDATE or a DELETE to resolve the orphaned records after reviewing your database records. In this case, the likely decision is to delete the orphaned records from the si_invoice_items table. Using the DELETE example above, the SQL command you construct would be:
DELETE FROM si_invoice_items WHERE invoice_id = 1
After resolving the foreign key errors, access your SI application again to complete the update process.
Note that the table shown for the FOREIGN KEY TABLE column is “invoice_items” but the delete command references the “si_invoice_items” table. This is because the “si_” prefix is automatically added by the database SQL build logic and the application only knows the “invoice_items” part of the table name.