SP Upgrade — User Guide

Table of Contents

1. Introduction
2. Quick Start
3. Installation & Uninstallation
4. Configuration
   • 4.1 General Tab
   • 4.2 Database Tab
   • 4.3 FTP Tab
   • 4.4 Live Update Tab
   • 4.5 Permissions Tab
5. Dashboard — Test Connection
6. Core Transfer View
7. Database Transfer View
8. History Log View
9. Migration Walkthroughs
   • Scenario A: Same Host, Different Database
   • Scenario B: Remote/Different Host
   • Scenario C: Local Development (XAMPP/WAMP)
10. Going Live
11. Troubleshooting & FAQ
12. Appendices
    • Appendix A: Full Configuration Reference
    • Appendix B: Transfer Log States
    • Appendix C: Supported Core Entities

1. Introduction

SP Upgrade copies data from a Joomla! 1.5 source site to a new Joomla! destination site. It never modifies or writes to the source database — your original site remains untouched.

Key Concepts

• Transfer — Copies items from the source database to the destination database. ID conflicts are handled according to your configuration (assign new IDs, skip, or replace).
• Finalize — A second pass that rebuilds relationships, fixes internal references, and updates asset tables. Always run Finalize after completing all transfers for a given entity.
• History Log — Every transferred item is tracked with its source ID, destination ID, and transfer state. If a transfer is interrupted (timeout, memory limit), simply run it again — it resumes where it left off.
• Batch Processing — Items are transferred in configurable batches to prevent memory exhaustion and timeouts on large datasets.

Supported Source Version

SP Upgrade migrates from Joomla! 1.5 only. The destination must be a fresh Joomla! installation.

⚠️ WARNING: Always back up your database before any transfer. The component keeps a history log, but a full database backup is the safest insurance.

2. Quick Start

For experienced users who want to jump straight in:

1. Install a fresh Joomla! site (the destination).
2. Install SP Upgrade on the destination site.
3. Configure the source database credentials in Options → Database tab.
4. Go to Dashboard, click Ping Source Database to confirm connectivity.
5. Go to Core Transfer, check the entities you need, and click Transfer All.
6. After transfer completes, click Finalize.
7. Copy images and files (via FTP or file manager), install your template and extensions.

The detailed walkthroughs in Section 9 cover three common scenarios.

3. Installation & Uninstallation

Installation

1. Download the SP Upgrade package from kainotomo.com.
2. In your destination site's backend, go to Extensions → Manage → Install.
3. Upload the package zip file and follow the installation process.
4. After installation, a new SP Upgrade menu item appears in the backend.

Uninstallation

1. Go to Extensions → Manage → Uninstall.
2. In the Filter area, type SP and click Search.
3. Several entries appear. Select the entry where Type is Package — the other entries are removed automatically.
4. Click Uninstall.

This will completely remove the extension, including all of its files.

4. Configuration

All configuration is accessed via the Options button in the SP Upgrade toolbar or through System → Global Configuration → SP Upgrade.

4.1 General Tab

4.2 Database Tab

Enter the credentials from your source Joomla! 1.5 site's configuration.php file.

Open the source site's configuration.php (e.g., /home/public_html/configuration.php) and look for lines like:

public $host = 'localhost';
public $user = 'db_username';
public $password = 'db_password';
public $db = 'db_name';
public $dbprefix = 'jos_';

Copy these values into the SP Upgrade options. When you save, the connection should be established — a green message will confirm success.

4.3 FTP Tab

Required for transferring files (images, templates, extension media).

4.4 Live Update Tab

4.5 Permissions Tab

Standard Joomla! ACL settings — configure which user groups can access SP Upgrade.

5. Dashboard — Test Connection

The Dashboard is the first screen you see when opening SP Upgrade. It provides:

• Ping Source Database — Tests connectivity using the credentials entered in Options → Database. A green "DB connection healthy!" message confirms success.
• Test FTP — Tests the FTP connection. A green "FTP connection healthy!" message confirms success.
• A reminder to back up the database before each transfer.

If the connection fails, check your credentials in Options and verify that:

• The source database server is accessible from your destination host.
• The database user has proper permissions.
• The table prefix is correct (including the trailing underscore).

6. Core Transfer View

The Core Transfer view handles all built-in Joomla! entities that SP Upgrade can migrate. Each entity has a checkbox, a description, and optional ID fields.

Supported Entities

Transfer & Finalize

SP Upgrade uses a two-phase process:

1. Transfer — Copies the raw data (rows) from source to destination. ID conflicts are handled per your Same IDs Handling option. Duplicates (aliases, titles, usernames, emails) are automatically renamed.
2. Finalize — Rebuilds relationships, asset tables, nested sets (categories), version history, tag mappings, and 2FA settings. Always run Finalize after completing all transfers.

Selective ID Transfer

You can transfer specific items instead of everything by entering ID ranges in the format:

1-9,12,20-45,53

This transfers items with IDs 1 through 9, item 12, items 20 through 45, and item 53. Leave the field empty to transfer all items.

You can also click Choose to visually select items using a searchable dialog, or Clear to reset the field.

Transfer All

The Transfer All button transfers all checked entities in sequence. If the process is interrupted (timeout, memory), simply click it again — it continues from where it left off.

7. Database Transfer View

The Database Transfer view is for transferring arbitrary database tables that are not among the core entities — for example, third-party extension tables.

1. Select a source table from the list.
2. Enter row IDs in the same range format as Core Transfer (1-9,12,20-45,53) or leave empty for all rows.
3. Click Transfer.

The view automatically:

• Validates that the destination table exists, or creates it if missing.
• Checks for structural conflicts — if the same table exists with a different structure, you will be warned.

ℹ️ NOTE: After transferring extension tables, you must install the corresponding extension on the destination site and ensure the table structure matches.

8. History Log View

The History Log tracks every item that has been transferred. It is invaluable for monitoring progress, diagnosing errors, and resuming interrupted transfers.

Transfer States

An item is only fully migrated when its state is 4 (Transferred and finalized).

Filtering & Searching

• Search by Source ID — Enter a source item's primary key.
• Filter by Extension — Show logs for a specific entity.
• Filter by State — Show only failed, pending, or completed items.
• Date Range — Filter by begin/end date.
• Sorting — Click column headers (Extension, Source ID, State, Date) to sort ascending/descending.

Deleting History

• Mass Delete History — Deletes all entries matching the current filters.
• Delete Selected Items — Deletes individually checked entries.

Auto-Refresh

During active transfer, the log view automatically refreshes every 15 seconds so you can monitor progress in real time.

9. Migration Walkthroughs

SP Upgrade supports many deployment scenarios. Below are three common ones, from simplest to most complex.

Scenario A: Same Host, Different Database

Both source and destination sites are on the same server. They share filesystem access but use separate databases.

Assumptions:

Steps:

1. Backup — Back up the source site (files and database).

2. Create database — Create db_destination and a database user with UTF-8 encoding.

3. Create folder — Create /home/public_html/new/.

4. Install Joomla! — Upload a fresh Joomla! package to /home/public_html/new/ and run the web installer. Connect it to db_destination. Do not install sample data.

   ℹ️ NOTE: It is recommended to install the English Joomla! version even if you use a different language. Add your language pack afterwards.

5. Install SP Upgrade — Install the component on the destination site.

6. Configure source DB — In Options → Database, enter the source site's credentials from its configuration.php.

7. Test connection — On the Dashboard, click Ping Source Database. Confirm a green success message.

8. Transfer core data — Go to Core Transfer, check all needed entities, click Transfer All. When complete, click Finalize.

9. Copy images — Use FTP (configured in Options → FTP) or copy the images/ folder manually via your hosting file manager.

10. Install template — Install a modern responsive template on the destination site.

11. Transfer extensions — For each extension:

    • Set Same IDs Handling to transfer with new IDs.
    • Transfer its database tables via the Database Transfer view.
    • Install the extension on the destination.

12. Go live — See Section 10.

Scenario B: Remote/Different Host

Source and destination are on different servers. The destination server must have network access to the source database server.

Additional considerations:

• The Host field in Options → Database must be the source server's IP address or hostname (not localhost).
• Some hosting providers restrict remote database connections. You may need to add the destination server's IP to the source server's firewall allowlist.
• If remote DB access is not possible, first export the source database to a dump file, import it on the destination server, and connect to the local copy.
• FTP must be configured with the source server's FTP credentials and the correct root path.

Steps are identical to Scenario A, except:

• Database Host = remote server IP or hostname.
• FTP Host = remote server hostname or IP.
• FTP Root = the path from the FTP server's root to the Joomla! installation (e.g., /public_html/).

Scenario C: Local Development (XAMPP/WAMP)

Develop and test the migration on your local machine, then deploy the destination site to production.

Setup:

1. Install XAMPP, WAMP, or MAMP on your local machine.
2. Export the source Joomla! 1.5 database to a .sql file from your live server (phpMyAdmin or mysqldump).
3. Import it into your local MySQL server as a new database.
4. Download the source site's files to your local machine via FTP and place them in the web root.
5. Edit the local copy's configuration.php to point to your local database.
6. Create a second local database for the destination site.
7. Install a fresh Joomla! locally for the destination.
8. Install SP Upgrade on the local destination site.
9. In Options → Database, set Host to localhost and enter the credentials for the local copy of the source database.

When ready to go live:

1. Export the destination database.
2. Upload the destination files to your production server.
3. Import the database on production.
4. Update configuration.php with production credentials.

10. Going Live

When you have finished testing the new site and are ready to put it into production:

1. Backup everything — Both the source and destination sites.

2. Freeze changes — If possible, freeze menu, module, and category changes on the source site before the final transfer. New users and articles can continue to be added.

3. Final transfer — Re-run core transfer to bring over any new or updated items. SP Upgrade's history log ensures only new/changed items are processed.

4. Move files (via file manager or FTP):

   • Ensure both configuration.php files have permissions 644 (not 444).
   • Move (do not copy) all files from the old source folder to a backup directory.
   • Move all files from the destination folder to the old source folder.
   • Moving takes milliseconds; copying then deleting takes much longer.

5. That's it! Your new site is now live at the original URL.

11. Troubleshooting & FAQ

Connection Issues

"DB connection failed" - Verify the host, database name, username, and password in Options → Database. - Check that the database server allows connections from your destination host. - Ensure the table prefix includes the trailing underscore.

"FTP connection failed" - Verify the FTP host, port, username, and password. - Check that the PHP ftp extension is enabled on your server. - If using SSL, ensure your server supports FTPS. - Verify the FTP root path is correct.

Timeouts & Memory

The transfer process stops mid-way - This is usually caused by PHP execution time limits or memory limits. - Simply click Transfer or Transfer All again — the process resumes from where it left off. - For large sites, reduce the Batch size in Options (try 50 or 25). - Consider increasing memory_limit and max_execution_time in your PHP configuration.

Duplicate Items

"Item already exists" or "Duplicate alias/title" messages - These are normal. SP Upgrade handles duplicates automatically by renaming the alias, title, username, or email. - Check the History Log for details on how each duplicate was resolved.

Menu Issues

"Parent menu type is not available" - Menu types (menus) must be transferred before their menu items. Transfer menu types first, then menu items.

General

Can I transfer to the same database as the source? Yes, but a separate database is recommended. If using the same database, the table prefix must differ between source and destination to avoid conflicts. The source Joomla! 1.5 typically uses jos_.

What happens if I transfer the same items twice? The history log prevents double-transfer. Items already in state 4 (transferred and finalized) are skipped.

Does SP Upgrade modify the source database? No. SP Upgrade only reads from the source database. Your original site is never modified.

What Joomla! versions can I migrate FROM? SP Upgrade is specifically designed to migrate from Joomla! 1.5. For migration from newer Joomla! versions (2.5, 3.x), please use SP Transfer.

12. Appendices

Appendix A: Full Configuration Reference

Appendix B: Transfer Log States

Appendix C: Supported Core Entities

For additional support, visit kainotomo.com or check the online documentation.