.. include:: /Includes.rst.txt .. _admin-migration: Migrating to core redirects ============================ Starting with TYPO3 14.2, the TYPO3 core ships a native `Short URL feature `__ built on top of :code:`EXT:redirects`. This extension is therefore deprecated and will not be developed further. The :code:`tinyurls:migrate-to-redirects` CLI command converts your existing tiny URL records into :code:`sys_redirect` records so that you can uninstall this extension afterward. .. _admin-migration-what-gets-migrated: What gets migrated ------------------- For every :code:`tx_tinyurls_urls` record found on the given storage PID, the command creates one :code:`sys_redirect` record: .. list-table:: :header-rows: 1 :widths: 30 70 * - tx_tinyurls_urls field - sys_redirect field * - :code:`urlkey` - used to build :code:`source_path` (see :code:`--url-template`) * - :code:`target_url` - :code:`target` * - :code:`counter` - :code:`hitcount` * - :code:`comment` - :code:`description` * - :code:`valid_until` - :code:`endtime` The redirect is always created with :code:`target_statuscode` :code:`301` (permanent redirect). Records where :code:`valid_until` is in the past are migrated as well, with the same (past) timestamp carried over to :code:`endtime`. The resulting redirect is therefore created already expired. Nothing in :code:`tx_tinyurls_urls` is deleted by this command, so it is entirely up to you whether to keep, disable or remove those expired redirects afterward. The following records are **skipped** and left untouched in :code:`tx_tinyurls_urls`: - Records with :code:`delete_on_use` enabled. Redirects have no "delete after first hit" concept, so a one-time-use tiny URL would silently become a permanent redirect if it was migrated. If you still need these, note them down before migrating, since the command has no way to recreate their one-time behaviour on the redirects side. - Records for which a matching redirect (same :code:`--host` and resulting :code:`source_path`) already exists. This makes the command safe to run multiple times, for example to pick up tiny URLs that were created after an earlier migration run. .. _admin-migration-caveat-speaking-urls: If you are not using speaking URLs ----------------------------------- By default, a tiny URL is accessed as :code:`index.php?eID=tx_tinyurls&tx_tinyurls[key]=` (see :ref:`what-it-does`), unless you enabled :ref:`admin-speaking-url-configuration`. Because of this, the command cannot derive a sensible default for :code:`--url-template` when speaking URLs are disabled and requires you to pass it explicitly. The :code:`--url-template` option builds a plain path (for example :code:`/`), which matches speaking URLs but **not** the default eID query string. If you are not using speaking URLs, links generated by the migration will not automatically catch requests to the old eID URLs. In that case, either keep this extension installed until you have confirmed that external links, bookmarks and search engine listings have moved over to the new redirect URLs, enable speaking URLs before migrating so that old and new URLs match, or add a webserver-level rewrite that forwards the old eID URLs to the new path, as described below. .. _admin-migration-webserver-config: Redirecting old eID URLs at the webserver ------------------------------------------ If you were not using speaking URLs, you can add a rewrite rule that translates requests for the old :code:`index.php?eID=tx_tinyurls&tx_tinyurls[key]=` URLs into the path used by :code:`--url-template`, so that old links keep working without keeping this extension installed. The webserver issues a redirect to the new path, which TYPO3 then matches against the migrated :code:`sys_redirect` record and redirects to the final target — one extra hop, but only for old links still in circulation. The examples below assume the default :code:`--url-template` of :code:`/tinyurl/###TINY_URL_KEY###`; adjust the target path to whatever template you actually used. They also assume the default :code:`base62Dictionary` (alphanumeric characters); widen the character class if you configured a custom dictionary. .. _admin-migration-webserver-config-apache: Apache example configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add this to your :code:`.htaccess` file or virtual host configuration (requires :code:`mod_rewrite`): :: RewriteEngine On RewriteCond %{QUERY_STRING} ^eID=tx_tinyurls&tx_tinyurls\[key\]=([A-Za-z0-9-]+)$ RewriteRule ^index\.php$ /tinyurl/%1? [R=301,L] .. _admin-migration-webserver-config-nginx: Nginx example configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add this inside the :code:`server` block, before the location that passes requests to PHP-FPM: :: if ($args ~ "^eID=tx_tinyurls&tx_tinyurls\[key\]=([A-Za-z0-9-]+)$") { return 301 /tinyurl/$1; } .. _admin-migration-usage: Usage ----- Run the command with `TYPO3 Console `__ (or via :code:`vendor/bin/typo3` on TYPO3 v10+): .. code-block:: bash vendor/bin/typo3 tinyurls:migrate-to-redirects --pid Always do a dry run first to see how many records would be migrated (this includes already-expired tiny URLs, see :ref:`admin-migration-what-gets-migrated`), skipped or have already been migrated, without writing anything to the database: .. code-block:: bash vendor/bin/typo3 tinyurls:migrate-to-redirects --pid --dry-run The command processes records in batches, so it works the same way regardless of how many tiny URLs you have. .. _admin-migration-options: Options ------- .. list-table:: :header-rows: 1 :widths: 20 10 20 50 * - Option - Shortcut - Default - Description * - :code:`--pid` - :code:`-p` - *(required)* - Storage PID of the tiny URLs to migrate. This is the same PID you configured as :code:`urlRecordStoragePID` (or the site's :code:`tinyurls.urlRecordStoragePID`). * - :code:`--target-pid` - — - :code:`0` - Storage PID for the created :code:`sys_redirect` records. * - :code:`--host` - — - :code:`*` - Value for :code:`source_host`. Use :code:`*` to match any host, or a specific domain if your tiny URLs are bound to one site. * - :code:`--url-template` - — - derived from :code:`speakingUrlTemplate`, otherwise required - Template used to build :code:`source_path`. :code:`###TINY_URL_KEY###` is replaced with the record's :code:`urlkey`. If speaking URLs are enabled and a :code:`speakingUrlTemplate` containing :code:`###TINY_URL_KEY###` is configured, this defaults to a path derived from it (with any leading host placeholder such as :code:`###TYPO3_SITE_URL###` stripped, since :code:`source_path` must not contain the host). For example, the extension default :code:`###TYPO3_SITE_URL###tinyurl/###TINY_URL_KEY###` becomes :code:`/tinyurl/###TINY_URL_KEY###`. If speaking URLs are disabled, or no such template is configured, there is no sensible default to guess, so the command requires you to pass this option explicitly and fails otherwise. * - :code:`--dry-run` - — - off - Do not write anything to the database, only report what would happen. If your tiny URLs are spread across multiple storage pages (for example one per site), run the command once per :code:`--pid`, adjusting :code:`--host` and :code:`--url-template` for each site as needed. .. _admin-migration-recommended-workflow: Recommended workflow --------------------- #. Update to the latest release of this extension and make sure :code:`EXT:redirects` is active. #. Run the command with :code:`--dry-run` and check the summary output. #. Run it for real, with :code:`--host` and :code:`--url-template` matching your setup. #. Check the created records in the backend :guilabel:`Redirects` module. #. If you were not using speaking URLs, add the webserver rewrite described in :ref:`admin-migration-webserver-config` so that old links keep working. #. Test a handful of migrated tiny URLs in the browser to confirm they now go through :code:`sys_redirect`. #. Review the migrated redirects that are already expired (see :ref:`admin-migration-what-gets-migrated`) and decide whether to keep, disable or delete them. #. Repeat for every storage PID that contains tiny URL records. #. Once you are confident all relevant links have been migrated, remove this extension and drop the :code:`tx_tinyurls_urls` table.