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” file contains all key/value settings that are needed to configure SimpleInvoices and is maintained as part of the SimpleInvoices code. The “custom.config” file is the runtime version that contains the same “config” 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.
Update to master_2020 from master_2019.2
- Save a copy of your “custom.config.php” file located in the config directory for use later in this process.
- Export your full database using phpMyAdmin or whatever administration tool you use.
- Backup your full SimpleInvoices implementation. Make a .zip or .gzip copy of your full SimpleInvoices directory path. Include the database extract from step 2 in the backup file.
- Save the backup file in a directory separate from your SimpleInvoices directories.
- If you have developed your own extension or custom hooks, they will be included in the backup file.
- Download the “master_2020” version of SimpleInvoices.
- Delete your SimpleInvoices root directory. This includes all sub-directories within it.
- 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 deleted in step 7.
- Copy the “custom.config.php” file saved in step 1 into your SimpleInvoices “config” 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 11, change the “$secure” setting back to “true” and save the file. You can also delete the old “custom.config.php” file from the “config” directory.
Proceed to the, First Use Of Update, topic instructions below.
- Select the Backup Database option on the 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 is preserved for easy recovery if needed.
Update Installation Instructions
Follow these steps to complete your update:
- Make sure you do what it says in the Backup First topic.
- Recreate the directory that your current SimpleInvoices was installed in that was renamed from in the Backup First step. We will call this the SimpleInvoices directory.
- In your browser, download the “master_2019.2” version for PHP 7.2 and greater, or the “master“ version for PHP 5.6, 7.0 or 7.1 from the Clone or Download button on that page.
- Unzip the download file. It will create a directory named the same as the zip file (assuming you didn’t rename it); typically, simpleinvoices-master.
- Copy the content of the directory created by the unzip process into the directory created in step 2.
- Copy the config/custom.config.php file from your previous SimpleInvoices directory and save it in the config/ directory of the new SimpleInvoice installation directory. Changes to the new version of the config/config.php file will be automatically added to the new copy of the config/custom.config.php file.
- If you have your own business invoice template, copy your company logos from the backup template/invoices/logos directory to the updated install template/invoices/logos directory. Next copy the directory your business template is in, from the template/invoices directory to the template/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 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; both applied and unapplied. Scroll down the list to see what unapplied patches are pending. They are at the bottom of the list. Scroll back to the top of the list and 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.
NOTE: If the patch process reports an error for foreign key update, refer to the Foreign Key Update error section below.
If You Have Special Code
- 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 the are current and work for the newly installed version.
- Extensions – Extensions 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 updated version do it as an Extension or via the Custom Hooks. 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 in the code 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.