System - Link Canonical is a Joomla system plugin designed to enhance search engine optimization (SEO) by generating canonical URLs for front-end HTML pages. When a component-specific fix script is installed, the plugin generates a canonical URL and replaces any existing <link rel="canonical"> tag in the HTML <head> with a superior version, if applicable, and adds a corresponding Link: <canonical_url>; rel=canonical HTTP header. It supports Joomla core components (com_content, com_contact, com_users, etc.) and third-party extensions (com_k2, com_ars, etc.), with configurable options for scheme, host, redirects, and component exclusion. Developers can extend support to custom components using the provided guidelines. This documentation details installation, configuration, usage, and extension procedures for the plugin.
Installation
To install System - Link Canonical:
- In the Joomla administrator panel, navigate to Extensions > Manage > Install
- Upload the plugin package or specify the URL: https://www.richeyweb.com/index.php?option=com_ars&view=update&task=download&format=raw&id=80
- Go to Extensions > Plugins, locate “System - Link Canonical,” and enable the plugin.
- Proceed to the plugin’s configuration settings to customize its behavior.
Configuration
Configure the plugin in Joomla’s plugin manager to align with your site’s requirements:
- Override Existing Canonical: When enabled, the plugin replaces an existing <link rel="canonical"> tag only when a component-specific fix script generates a superior canonical URL. Default: Enabled.
- Canonical Scheme: Select HTTP, HTTPS, or Current (uses the page’s scheme) for the canonical URL’s protocol. Default: Current.
- Canonical Host: Specify a domain (e.g., example.com) or leave blank to use the current host. Default: Blank.
- Redirect Canonical URL: Enable to redirect users to the canonical URL if the current URL differs (e.g., from http to https). Default: Disabled.
- Ignore Components: List components to exclude from canonical URL processing (e.g., com_admin, com_users) using their option identifier. Default: None.
Usage
Upon activation, System - Link Canonical operates on front-end HTML pages as follows:
- Canonical URL Generation: Generates SEO-friendly URLs (e.g., https://yourdomain.com/article-title) using Joomla’s Search Engine Friendly (SEF) routing or component-specific fix scripts for supported components, including com_content, com_k2, com_ars, com_contact, com_finder, com_newsfeeds, com_tags, com_users, and com_weblinks.
- Link Replacement: Replaces an existing <link rel="canonical"> tag in the HTML <head> only when a component-specific fix script produces a superior canonical URL, optimizing SEO performance. If no fix script is available or no better URL is generated, the existing tag is preserved unless “Override Existing Canonical” is enabled.
- HTTP Headers: Adds a Link: <canonical_url>; rel=canonical HTTP header when a canonical URL is generated.
Exclusions: Skips processing for administrator pages, non-HTML outputs (e.g., JSON, XML), URLs with tasks (e.g., task=edit), and components listed in the “Ignore Components” setting. - Redirects: If “Redirect Canonical URL” is enabled, redirects users to the canonical URL (except for the homepage) when the current URL differs and a valid canonical URL is generated.
To verify functionality, inspect the HTML <head> for updated canonical tags or review server logs to confirm URL consolidation (e.g., redirecting index.php?option=com_content&id=123 to /article-title).
Extending with Custom Fix Scripts
To support components not covered by built-in fix scripts (e.g., com_virtuemart, com_eventbooking), create a custom fix script:
- Location: Place the script in JPATH_PLUGINS/system/linkcanonical/src/Fixes/.
- File Name: Use the format LinkCanonical_com_[component].php (e.g., LinkCanonical_com_eventbooking.php).
- Structure: Extend the Joomla\Plugin\System\LinkCanonical\Fixes\LinkCanonicalFix class and implement a fix method to generate a canonical URL. Use component-specific routing helpers or Joomla’s Route class.
- Guidelines:
- The fix method receives $vars (URL variables, e.g., view, id) and $uri (current URI instance).
- Use component-specific routing helpers (e.g., RouteHelper::getEventRoute) when available, or construct URLs with Joomla\CMS\Router\Route::_.
- Filter valid query parameters using self::extraVars($vars, $valid) to maintain clean URLs.
- Return false to fall back to the plugin’s default routing if no custom route is applicable.
- Testing: Activate the plugin, access a page for the custom component (e.g., index.php?option=com_eventbooking&view=event&id=123), and verify the canonical tag in the HTML <head> or redirect behavior in server logs.
Example Fix Script
<?php
namespace Joomla\Plugin\System\LinkCanonical\Fixes;
\defined('_JEXEC') or die;
use Joomla\Component\Eventbooking\Site\Helper\RouteHelper;
\defined('_JEXEC') or die;
class LinkCanonical_com_eventbooking extends LinkCanonicalFix {
public static function fix(&$vars, $uri) {
$valid = ['id', 'layout'];
$url = false;
switch ($vars['view']) {
case 'event':
$url = RouteHelper::getEventRoute($vars['id'], $vars['catid'] ?? null);
break;
case 'category':
$url = RouteHelper::getCategoryRoute($vars['id']);
break;
}
return $url ? $url . self::extraVars($vars, $valid) : false;
}
}What's happening in this fix script? That's actually the easy part! First of all, I MUST insist that you NOT use this for the eventbooking component. This is totally made up, and I'm quite certain that it won't work correctly for that component.
In the fix() function, we define the valid URL variables 'id' and 'layout'. This list is added to a predefined list of Joomla valid URL variables (tmpl, lang, Itemid). So we're defining a list of acceptable URL variables. Anything else is getting stripped.
From here, we switch the view variable and use the same RouteHelper as the component uses, along with the variables it uses natively to generate URLs.
Finally, we return the URL with any valid URL variables appended to it. If there's a problem, we return false and the plugin does nothing to the existing canonical link.
I'll probably have to rewrite this in the future, but it's good enough for now - sorry if it's a problem, this is a brand new plugin and I'm going to be learning YOUR needs from here going forward.
