SP Transfer User Guide

SP Transfer is a Joomla component designed to migrate content, users, menus, modules, and files from an existing (source) Joomla site to a fresh (destination) Joomla installation. It supports migration from Joomla 1.5, 2.5, and 3.x to a modern Joomla destination site.

Table of Contents

1. Introduction
2. Quick Start
3. Installation & Uninstallation
4. Configuration
5. Dashboard — Test Connection
6. Core Transfer View
7. Database Transfer View
8. Files Transfer View
9. History Log View
10. Migration Walkthroughs
11. Going Live
12. Troubleshooting & FAQ
13. Appendices

1. Introduction

SP Transfer copies data from a source Joomla site to a destination Joomla 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 Versions

SP Transfer supports reading from any Joomla version starting from Joomla 1.5 and later.

The destination must be a fresh Joomla installation (3.x or later).

2. Quick Start

For experienced users who want to jump straight in:

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

The detailed walkthroughs in Section 10 cover three common scenarios.

3. Installation & Uninstallation

Installation

1. Download the SP Transfer 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 Transfer menu item appears in the backend.

Uninstallation

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

⚠️ Backup your database before any transfer. The component keeps a history log, but a full database backup is the safest insurance.

4. Configuration

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

4.1 General Tab (Core Joomla! Data)

4.2 Database Tab (Source Connection)

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

4.3 FTP Tab

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

4.4 Live Update Tab

4.5 Permissions Tab

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

5. Dashboard — Test Connection

The Test Connection view is the first screen you see when opening SP Transfer. It provides:

• Ping Source Database — Tests connectivity using the credentials entered in Options. 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 backup 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 22 built-in Joomla entities. Each entity has a checkbox, a description, and optional ID fields.

Supported Entities

Transfer & Finalize

SP Transfer 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 the Choose button 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 22 core entities — for example, third-party extension tables.

• Select a source table from the list.
• Enter row IDs in the same range format as Core Transfer (1-9,12,20-45,53) or leave empty for all rows.
• 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. Files Transfer View

The Files Transfer view lets you copy files from the source site to the destination site via FTP.

Interface

The view is split into two panels:

• Remote Site — Browse the source site's file system via FTP. Navigate folders and select files.
• Local Site — Browse the destination site's file system. You can create folders here.

Transferring Files

1. Navigate to the desired folder on the Remote Site.
2. Select files or folders.
3. Click Transfer to copy them to the corresponding location on the Local Site.

Replace Strategy

The Existing Files Replace option in Configuration determines whether existing files on the destination are overwritten.

FTP Requirements

• The PHP ftp extension must be enabled on your server.
• The FTP user must have read access to the source files and write access to the destination.
• SSL (FTPS) is supported — enable it in Options → FTP tab.

9. 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.

10. Migration Walkthroughs

SP Transfer 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.
5. Install SP Transfer — 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 transfer in the Files view, or copy the images/ folder manually via file manager.
10. Install template — Install a modern responsive template on the destination site.
11. Transfer extensions — For each extension: (a) set "Same IDs Handling" to transfer with new IDs, (b) transfer its database tables via the Database Transfer view, (c) install the extension on the destination.
12. Go live — See Section 11.

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 transfer the source database to a local dump, 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 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 Transfer 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.

11. 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 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 Transfer'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.

12. 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 exist" or "Duplicate alias/title" messages - These are normal. SP Transfer 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.

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 Transfer modify the source database? No. SP Transfer only reads from the source database. Your original site is never modified.

13. 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.