Support closures for outputAlternate. Bump to 3.0.0-beta.6

CHANGELOG.md

@@ -1,5 +1,9 @@
 # SEOMate Changelog
 
+## 3.0.0-beta.6 - 2024-04-25
+### Added
+- The `outputAlternate` config setting now accepts a closure returning `true` or `false`.
+
 ## 3.0.0-beta.5 - 2024-04-06  
 ### Fixed
 - Fixed a PHP exception that would occur when using the `{% seomateMeta %}` hook in nested entry templates ([#85](https://github.com/vaersaagod/seomate/issues/85))

README.md

@@ -495,16 +495,40 @@ meta content.
 *Default: `'|'`*  
 The separator between the meta tag content and the site name.
 
-### outputAlternate [bool]
+### outputAlternate [bool|Closure]
 *Default: `true`*  
-Enables/disables output of alternate URLs. Alternate URLs are meant to provide
-search engines with alternate URLs _for localized versions of the current page's content_. 
+Enables/disables output of alternate URLs in meta tags and sitemaps.  
+
+Alternate URLs are meant to provide search engines with alternate URLs  
+_for localized versions of the current page's content_.  
 
 If you have a normal multi-locale website, you'll probably want to leave this setting
-enabled. If you're running a multi-site website, where the sites are distinct, you'll
-probably want to disable this.  
+enabled (i.e. set to `true`). However, if you're running a multi-site website where the  
+sites are distinct, you'll might want to set it to `false`, to prevent alternate URLs  
+from being output at all.    
+
+For the Advanced Use Case (tm) – _e.g. multi-sites that have a mix of translated **and**  
+distinct content_, it's also possible to break free from the shackles of the binary boolean,  
+and configure the `outputAlternate` setting with a closure function (that returns either `true`  
+or `false`).  
+
+The `outputAlternate` closure will receive two parameters; `$element` (the current element) and  
+`$alternateElement` (the element from a different site, i.e. the *potential* alternate). This makes  
+it possible to compose custom logic, in order to determine if that alternate element's URL  
+should be output or not.  
+
+An example: the below closure would make SEOMate only output alternate URLs if the _language_ for  
+the alternate element is different from the element's language:  
+
+```php
+'outputAlternate' => static fn($element, $alternateElement) => $element->language !== $alternateElement->language,
+```  
+
+If this closure returns `true`, SEOMate will create an alternate URL for the `$alternateElement`.  
+If it returns `false` (or any other falsey value), SEOMate will quietly pretend the `$alternateElement`  
+does not exist.  
 
-For more information about alternate URLs, (refer to this article)[https://support.google.com/webmasters/answer/189077].   
+_For more information about alternate URLs, [refer to this article](https://support.google.com/webmasters/answer/189077)._   
 
 ### alternateFallbackSiteHandle [string|null]
 *Default: `null`*  

composer.json

@@ -2,7 +2,7 @@
     "name": "vaersaagod/seomate",
     "description": "SEO, mate! It's important.",
     "type": "craft-plugin",
-    "version": "3.0.0-beta.5",
+    "version": "3.0.0-beta.6",
     "keywords": [
         "craft",
         "cms",

src/helpers/SitemapHelper.php

@@ -131,7 +131,7 @@ public static function getElementsSitemapUrls(string $handle, array $definition,
         $siteElements = null;
         $fallbackSite = null;
 
-        if ($settings->outputAlternate && Craft::$app->isMultiSite) {
+        if ($settings->outputAlternate !== false && Craft::$app->getIsMultiSite()) {
             $elementIds = $elements->pluck('id')->all();
             /** @var Collection $siteElements */
             $siteElements = (clone($query))
@@ -164,6 +164,9 @@ public static function getElementsSitemapUrls(string $handle, array $definition,
                 }
                 /** @var ElementInterface $alternate */
                 foreach ($alternates->all() as $alternate) {
+                    if ($settings->outputAlternate instanceof \Closure && !($settings->outputAlternate)($element, $alternate)) {
+                        continue;
+                    }
                     $url['alternate'][] = [
                         'hreflang' => strtolower(str_replace('_', '-', $alternate->getLanguage())),
                         'href' => $alternate->getUrl(),

src/models/Settings.php

@@ -45,7 +45,7 @@ class Settings extends Model
 
     public string|null $defaultProfile = null;
 
-    public bool $outputAlternate = true;
+    public bool|\Closure $outputAlternate = true;
 
     public string|null $alternateFallbackSiteHandle = null;
 

src/services/UrlsService.php

@@ -103,7 +103,7 @@ public function getAlternateUrls($context): array
             SEOMateHelper::updateSettings($settings, $overrideObject['config']);
         }
 
-        if (!$settings->outputAlternate || !Craft::$app->isMultiSite) {
+        if ($settings->outputAlternate === false || !Craft::$app->getIsMultiSite()) {
             return [];
         }
 
@@ -140,6 +140,9 @@ public function getAlternateUrls($context): array
 
         /** @var ElementInterface $siteElement */
         foreach ($siteElements->all() as $siteElement) {
+            if ($settings->outputAlternate instanceof \Closure && !($settings->outputAlternate)($element, $siteElement)) {
+                continue;
+            }
             $alternateUrls[] = [
                 'url' => $siteElement->getUrl(),
                 'language' => strtolower(str_replace('_', '-', $siteElement->getLanguage())),