Enhanced Sorting by Nested Meta Values in Pages (#681)

* Added functionality for sorting pages by nested meta values.

* Additional variables removed.

* Added comment to the config template file about the possibility to access nested metadata with a dot as separator for sorting.

* Added entry in the changelog about the possibility to access nested metadata with a dot as separator for sorting.

* Changelog and config template adapted according to the suggestions.

* Added old entry back in the Config template.

.build/build.sh

@@ -464,10 +464,10 @@ find . -mindepth 1 -maxdepth 1 -printf '%f\0' \
 echo "Creating release archive '$ARCHIVE_FILENAME.zip'..."
 zip -q -r "$APP_DIR/$ARCHIVE_FILENAME.zip" .
 
-echo
-
 # publish release
 if [ -n "$PUBLISH" ]; then
+    echo
+
     # switch to app dir
     cd "$APP_DIR"
 

.github/workflows/test-pr.yml

@@ -0,0 +1,27 @@
+name: Test Pico CMS pull request
+
+on:
+    pull_request: {}
+
+jobs:
+    test:
+        name: Test Pico CMS
+        uses: ./.github/workflows/test.yml
+
+    bouncer:
+        name: Bouncer
+
+        needs: test
+        if: ${{ always() }}
+
+        runs-on: ubuntu-latest
+        permissions: {}
+
+        steps:
+            - name: Check build matrix status
+              if: ${{ needs.test.result != 'success' }}
+              run: |
+                  :
+                  echo "Some tests of Pico CMS failed." >&2
+                  echo "Please check the GitHub workflow logs for details." >&2
+                  exit 1

.github/workflows/test.yml

@@ -6,7 +6,7 @@ on:
             - 'master'
             - 'pico-3.0'
         tags: [ 'v*.*.*' ]
-    pull_request: {}
+    workflow_call: {}
 
 jobs:
     test:

CHANGELOG.md

@@ -32,6 +32,8 @@ Released: -
         now receive the (optional) `$pageId` argument for the new `%page_*%`
         Markdown placeholders
 * [New] Add `page()` Twig function to access a page's data
+* [New] Enhance `pages_order_by_meta` functionality to allow sorting by 
+            nested meta values using '.' notation (e.g., 'author.info')
 * [Changed] ! Pico now requires PHP 7.2.5 or later (this includes full PHP 8
             support, also see #528, #534, #608)
 * [Changed] ! Pico now depends on Twig 3.3, skipping Twig 2.x altogether; this

CONTRIBUTING.md

@@ -188,7 +188,7 @@ Issues and pull requests labeled with `info: Feedback Needed` indicate that feed
   - `status: Resolved` is used when the issue has been resolved (used with issues only).
   - `status: Conflict` indicates a conflict with another issue or behavior of Pico, making it impossible to resolve the problem at the moment.
   - `status: Won't Fix` means, that there is indeed a problem, but for some reason we made the decision that resolving it isn't reasonable, making it intended behavior.
-  - `status: Rejected` is used when the issue was rejected for another reason.
+  - `status: Rejected` is used when the issue was rejected for another reason (used with issues only).
 
 - The `type: Enhancement` and `type: Feature` labels are used to tag pull requests, which introduce either a comparatively small enhancement, or a "big" new feature. As with the `type: Bug` label, they might get combined with the `pri: High` or `pri: Low` labels to indicate the pull request's priority. They might also be labeled with `status: Work In Progress`. After merging or closing the pull request, it is labeled with one of the `status` labels as described above for the `type: Bug` label.
 

config/config.yml.template

@@ -31,6 +31,7 @@ twig_config:                        # Twig template engine config
 date_format: "%D %T"                # Pico's default date format;
                                     #     See https://php.net/manual/en/function.strftime.php for more info
 pages_order_by_meta: author         # Sort pages by meta value "author" (set "pages_order_by" to "meta")
+                                    #     Use '.' notation for nested meta keys (e.g. 'author.info')
 pages_order_by: alpha               # Change how Pico sorts pages ("alpha" for alphabetical order, "date", or "meta")
 pages_order: asc                    # Sort pages in ascending ("asc") or descending ("desc") order
 content_dir: ~                      # The path to Pico's content directory

lib/Pico.php

@@ -370,7 +370,7 @@ class Pico
         $this->configDir = $this->getAbsolutePath($configDir);
         $this->pluginsDir = $this->getAbsolutePath($pluginsDir);
         $this->themesDir = $this->getAbsolutePath($themesDir);
-        $this->enableLocalPlugins = (bool) $enableLocalPlugins;
+        $this->enableLocalPlugins = $enableLocalPlugins;
     }
 
     /**
@@ -1771,6 +1771,8 @@ class Pico
     {
         $contentDir = $this->getConfig('content_dir');
         $contentExt = $this->getConfig('content_ext');
+        $contentDirLen = strlen($contentDir);
+        $contentExtLen = strlen($contentExt);
 
         $this->pages = [];
         $files = $this->getFiles($contentDir, $contentExt, self::SORT_NONE);
@@ -1781,7 +1783,7 @@ class Pico
                 continue;
             }
 
-            $id = substr($file, strlen($contentDir), -strlen($contentExt));
+            $id = substr($file, $contentDirLen, -$contentExtLen);
 
             // trigger onSinglePageLoading event
             // skip inaccessible pages (e.g. drop "sub.md" if "sub/index.md" exists) by default
@@ -1875,11 +1877,18 @@ class Pico
         if ($orderBy === 'meta') {
             // sort by arbitrary meta value
             $orderByMeta = $this->getConfig('pages_order_by_meta');
-            uasort($this->pages, function ($a, $b) use ($alphaSortClosure, $order, $orderByMeta) {
-                $aSortValue = isset($a['meta'][$orderByMeta]) ? $a['meta'][$orderByMeta] : null;
-                $aSortValueNull = ($aSortValue === null);
+            $orderByMetaKeys = explode('.', $orderByMeta);
+
+            uasort($this->pages, function ($a, $b) use ($alphaSortClosure, $order, $orderByMetaKeys) {
+                $aSortValue = $a['meta'];
+                $bSortValue = $b['meta'];
                 
-                $bSortValue = isset($b['meta'][$orderByMeta]) ? $b['meta'][$orderByMeta] : null;
+                foreach ($orderByMetaKeys as $key) {
+                    $aSortValue = isset($aSortValue[$key]) ? $aSortValue[$key] : null;
+                    $bSortValue = isset($bSortValue[$key]) ? $bSortValue[$key] : null;
+                }
+
+                $aSortValueNull = ($aSortValue === null);
                 $bSortValueNull = ($bSortValue === null);
 
                 $cmp = 0;
@@ -2450,7 +2459,7 @@ class Pico
     /**
      * Returns the URL of a given absolute path within this Pico instance
      *
-     * We assume that the given path is a arbitrary deep sub folder of the
+     * We assume that the given path is an arbitrary deep sub folder of the
      * script's base path (i.e. the directory {@path "index.php"} is in resp.
      * the `httpdocs` directory). If this isn't the case, we check whether it's
      * a sub folder of {@see Pico::$rootDir} (what is often identical to the
@@ -2741,7 +2750,7 @@ class Pico
      *
      * @return string normalized path
      *
-     * @throws UnexpectedValueException thrown when a absolute path is passed
+     * @throws UnexpectedValueException thrown when an absolute path is passed
      *     although absolute paths aren't allowed
      */
     public function getNormalizedPath(string $path, bool $allowAbsolutePath = false, bool $endSlash = true): string