Merge branch 'release/1.0.9'

Author: rhukster

CHANGELOG.md

@@ -1,3 +1,15 @@
+# v1.0.9
+## 07/06/2026
+
+1. [](#new)
+    * The new admin can now retrieve the Grav core changelog for versions newer than the one installed, so it can show what changed before you upgrade ([getgrav/grav-plugin-admin2#109](https://github.com/getgrav/grav-plugin-admin2/issues/109)).
+    * Plugins can now add their own columns to the new admin's Users list, contributing safe per-user values that stay scoped to the page you are viewing ([getgrav/grav-plugin-admin2#111](https://github.com/getgrav/grav-plugin-admin2/issues/111)).
+1. [](#improved)
+    * Media listings now include each file's saved alt text and title from its metadata, so the admin can insert an image with proper alt text instead of the filename ([getgrav/grav-plugin-admin2#114](https://github.com/getgrav/grav-plugin-admin2/issues/114)).
+1. [](#bugfix)
+    * The page summary preview now returns clean stripped text instead of a slice of raw Markdown, so leading links and images no longer leave broken fragments in the new admin's page list ([getgrav/grav-plugin-admin2#110](https://github.com/getgrav/grav-plugin-admin2/issues/110)).
+    * Media files whose extension has any uppercase letters, such as `.JPG`, can now be deleted instead of failing with a not-found error ([getgrav/grav#4196](https://github.com/getgrav/grav/issues/4196)).
+
 # v1.0.8
 ## 07/04/2026
 

blueprints.yaml

@@ -1,7 +1,7 @@
 name: API
 slug: api
 type: plugin
-version: 1.0.8
+version: 1.0.9
 description: RESTful API for Grav CMS. Provides headless access to pages, media, configuration, users, and system management.
 icon: plug
 author:

classes/Api/ApiRouter.php

@@ -410,9 +410,15 @@ protected function dispatch(ServerRequestInterface $request): ResponseInterface
         // page type (e.g. .md, .txt, .html) before the route is built. Without
         // this re-attach, `DELETE /api/v1/media/notes.txt` would arrive as
         // `/media/notes` and 404.
+        //
+        // RequestProcessor lowercases the extension, but the route path keeps
+        // the file's original case. Compare case-insensitively so an uppercase
+        // extension (e.g. `photo.JPG`) is not treated as missing and a duplicate
+        // `.jpg` appended — which turned the filename into `photo.JPG.jpg` and
+        // 404'd every media file with a non-lowercase extension (getgrav/grav#4196).
         if ($route) {
             $extension = (string)$route->getExtension();
-            if ($extension !== '' && !str_ends_with($gravPath, '.' . $extension)) {
+            if ($extension !== '' && !str_ends_with(strtolower($gravPath), '.' . strtolower($extension))) {
                 $gravPath .= '.' . $extension;
             }
         }
@@ -590,6 +596,7 @@ protected function registerCoreRoutes(RouteCollector $r): void
         // Static route registered before the /users/{username} catch-all so the
         // tab-discovery endpoint is never swallowed as a username lookup.
         $r->addRoute('GET', '/users/filters', [UsersController::class, 'filters']);
+        $r->addRoute('GET', '/users/columns', [UsersController::class, 'columns']);
         $r->addRoute('POST', '/users', [UsersController::class, 'create']);
         $r->addRoute('GET', '/users/{username}', [UsersController::class, 'show']);
         $r->addRoute('PATCH', '/users/{username}', [UsersController::class, 'update']);
@@ -637,6 +644,7 @@ protected function registerCoreRoutes(RouteCollector $r): void
         $r->addRoute('GET', '/gpm/themes/{slug}/fields', [GpmController::class, 'customFieldBundle']);
         $r->addRoute('GET', '/gpm/themes/{slug}/field/{type}', [GpmController::class, 'customFieldScript']);
         $r->addRoute('GET', '/gpm/updates', [GpmController::class, 'updates']);
+        $r->addRoute('GET', '/gpm/grav/changelog', [GpmController::class, 'gravChangelog']);
         $r->addRoute('POST', '/gpm/install', [GpmController::class, 'install']);
         $r->addRoute('POST', '/gpm/remove', [GpmController::class, 'remove']);
         $r->addRoute('POST', '/gpm/update', [GpmController::class, 'update']);

classes/Api/Controllers/GpmController.php

@@ -1176,6 +1176,41 @@ public function changelog(ServerRequestInterface $request): ResponseInterface
         ]);
     }
 
+    /**
+     * GET /gpm/grav/changelog - Get the Grav core changelog for versions newer
+     * than the one currently installed, assembled into a single markdown doc.
+     */
+    public function gravChangelog(ServerRequestInterface $request): ResponseInterface
+    {
+        $this->requirePermission($request, self::PERMISSION_READ);
+
+        $query = $request->getQueryParams();
+        $flush = filter_var($query['flush'] ?? false, FILTER_VALIDATE_BOOLEAN);
+
+        $gravInfo = $this->getGpm($flush)->getGrav();
+
+        // Only show entries newer than the installed version.
+        $changelog = $gravInfo ? (array) $gravInfo->getChangelog(GRAV_VERSION) : [];
+
+        // Each entry is either a markdown string or ['date' => ..., 'content' => markdown].
+        $parts = [];
+        foreach ($changelog as $version => $entry) {
+            $date = is_array($entry) ? ($entry['date'] ?? '') : '';
+            $body = is_array($entry) ? ($entry['content'] ?? '') : $entry;
+            $body = is_string($body) ? trim($body) : '';
+
+            $heading = "# v{$version}";
+            if ($date !== '') {
+                $heading .= " ({$date})";
+            }
+            $parts[] = "{$heading}\n\n{$body}";
+        }
+
+        return ApiResponse::create([
+            'content' => implode("\n\n", $parts),
+        ]);
+    }
+
     /**
      * Resolve the filesystem path for an installed package.
      */

classes/Api/Controllers/MediaController.php

@@ -1606,6 +1606,16 @@ private function serializeSiteFile(string $basePath, string $filename, string $r
             'size' => (int) filesize($filePath),
         ];
 
+        // Alt/title from the `.meta.yaml` sidecar so the media panel can insert
+        // `![alt](file)` rather than overwriting alt with the filename.
+        $meta = $this->readMetaSidecar($filePath);
+        if (isset($meta['alt']) && is_scalar($meta['alt']) && (string) $meta['alt'] !== '') {
+            $data['alt'] = (string) $meta['alt'];
+        }
+        if (isset($meta['title']) && is_scalar($meta['title']) && (string) $meta['title'] !== '') {
+            $data['title'] = (string) $meta['title'];
+        }
+
         if (str_starts_with($mime, 'image/') && $mime !== 'image/svg+xml') {
             if ($imageSize = @getimagesize($filePath)) {
                 $data['dimensions'] = [

classes/Api/Controllers/UsersController.php

@@ -30,6 +30,19 @@ class UsersController extends AbstractApiController
     /** 8 MB cap — a profile avatar shouldn't be anywhere near this. */
     private const AVATAR_MAX_SIZE = 8_388_608;
 
+    /**
+     * Client-side renderers a plugin column may name. The server only ever
+     * declares *which* formatter renders a value; the rendering itself is the
+     * client's job. No renderer function or HTML crosses the wire, so a plugin
+     * can't smuggle markup or behaviour through a column. Unknown values fall
+     * back to 'text'.
+     */
+    private const COLUMN_FORMATTERS = ['text', 'link', 'date', 'datetime', 'boolean', 'number', 'badge'];
+
+    /** Hard caps so a misbehaving plugin can't bloat a list response. */
+    private const COLUMN_MAX_FIELDS = 32;
+    private const COLUMN_VALUE_MAX_LEN = 2048;
+
     private ?UserSerializer $serializer = null;
 
     public function index(ServerRequestInterface $request): ResponseInterface
@@ -102,6 +115,194 @@ public function filters(ServerRequestInterface $request): ResponseInterface
         return ApiResponse::create($this->assembleFilterTabs($event, $user));
     }
 
+    /**
+     * GET /users/columns — plugin-declared extra columns for the Users list.
+     *
+     * The presentation half of the Users extension contract (getgrav/
+     * grav-plugin-admin2#111). A plugin declares columns via the
+     * `onApiUserListColumns` event; Admin2 owns the table, and the per-user
+     * values ride along inside each user's `extra` map on GET /users (populated
+     * by `onApiUserListColumnData`, scoped to the current page — never a
+     * parallel all-users fetch).
+     *
+     * Column format:
+     *   [
+     *     'id'        => 'my-plugin-valid-till', // required, unique; client key
+     *     'plugin'    => 'my-plugin',            // owning plugin slug
+     *     'label'     => 'Valid until',          // display name (raw text)
+     *     'field'     => 'subscription.valid_till', // key into each user's `extra`
+     *     'formatter' => 'datetime',             // one of COLUMN_FORMATTERS; else 'text'
+     *     'sortable'  => false,                  // client-side, current page only
+     *     'priority'  => 50,                     // optional sort order (higher = earlier)
+     *     'authorize' => 'api.users.read',       // optional — string or array for any-of
+     *   ]
+     *
+     * Deliberately narrow: scalar data only, a fixed formatter whitelist, no
+     * raw HTML or renderer functions. That keeps plugin columns from becoming
+     * the kind of open-ended surface that let classic-admin plugins break on
+     * upgrade.
+     *
+     * Response shape: { "columns": [ ... ] }
+     */
+    public function columns(ServerRequestInterface $request): ResponseInterface
+    {
+        // Columns only mean something to a caller who can list users.
+        $this->requirePermission($request, 'api.users.read');
+
+        $user = $this->getUser($request);
+        $event = $this->fireEvent('onApiUserListColumns', [
+            'columns' => [],
+            'user' => $user,
+        ]);
+
+        return ApiResponse::create(['columns' => $this->assembleColumns($event, $user)]);
+    }
+
+    /**
+     * Validate and normalize plugin-declared columns: drop malformed entries and
+     * columns the caller isn't authorized for, whitelist the formatter, sanitize
+     * the field key, then order by descending priority. Mirrors
+     * assembleFilterTabs() — the `authorize` field is a server-side annotation
+     * and is stripped before the column reaches the client.
+     *
+     * @param Event $event The onApiUserListColumns event after plugins ran
+     * @return array<int, array<string, mixed>>
+     */
+    private function assembleColumns(Event $event, UserInterface $user): array
+    {
+        $isSuperAdmin = $this->isSuperAdmin($user);
+
+        $columns = [];
+        $seen = [];
+        foreach ((array) ($event['columns'] ?? []) as $column) {
+            if (!is_array($column) || !isset($column['id']) || !is_string($column['id']) || $column['id'] === '') {
+                continue;
+            }
+            if (isset($seen[$column['id']])) {
+                continue; // first declaration of an id wins
+            }
+            if (!$this->userPassesAuthorize($user, $column['authorize'] ?? null, $isSuperAdmin)) {
+                continue;
+            }
+
+            // The field is the key looked up in each user's `extra` map. Keep it
+            // to a safe identifier charset — no traversal or odd keys.
+            $field = isset($column['field']) && is_string($column['field'])
+                ? preg_replace('/[^A-Za-z0-9_.\-]/', '', $column['field'])
+                : '';
+            if ($field === '') {
+                continue;
+            }
+
+            $formatter = isset($column['formatter']) && is_string($column['formatter'])
+                && in_array($column['formatter'], self::COLUMN_FORMATTERS, true)
+                    ? $column['formatter']
+                    : 'text';
+
+            $seen[$column['id']] = true;
+            $column['field'] = $field;
+            $column['formatter'] = $formatter;
+            $column['sortable'] = (bool) ($column['sortable'] ?? false);
+            // Strip the authorize field — server-side annotation, not client data.
+            unset($column['authorize']);
+            $columns[] = $column;
+        }
+
+        usort($columns, fn($a, $b) => ($b['priority'] ?? 0) <=> ($a['priority'] ?? 0));
+
+        return $columns;
+    }
+
+    /**
+     * Merge plugin-owned scalar column data into an already-serialized,
+     * already-paginated page of users. Fired ONCE for the whole page (the
+     * `onApiUserListColumnData` event receives only the usernames already
+     * selected after search / filter / permission / pagination), so there is no
+     * N+1 and no incentive to load metadata for every account.
+     *
+     * Hard isolation: a throwing or misbehaving subscriber can never 500 or
+     * stall the listing — failures degrade to missing column values, logged as
+     * a warning. Plugin values are scalar-only and capped.
+     *
+     * @param array<int, array<string, mixed>> $data Serialized users for this page
+     * @return array<int, array<string, mixed>>
+     */
+    private function applyColumnData(array $data, UserInterface $currentUser): array
+    {
+        if ($data === []) {
+            return $data;
+        }
+
+        $usernames = array_values(array_filter(array_column($data, 'username'), 'is_string'));
+        if ($usernames === []) {
+            return $data;
+        }
+
+        try {
+            $event = $this->fireEvent('onApiUserListColumnData', [
+                'usernames' => $usernames,
+                'data' => [], // plugin fills: username => [ field => scalar ]
+                'user' => $currentUser,
+            ]);
+
+            $map = $event['data'] ?? null;
+            if (!is_array($map) || $map === []) {
+                return $data;
+            }
+
+            foreach ($data as &$row) {
+                $extra = $map[$row['username']] ?? null;
+                if (is_array($extra)) {
+                    $clean = $this->sanitizeColumnValues($extra);
+                    if ($clean !== []) {
+                        $row['extra'] = $clean;
+                    }
+                }
+            }
+            unset($row);
+        } catch (\Throwable $e) {
+            // Isolation: a plugin fault must not break the users list.
+            $this->grav['log']->warning('[api] onApiUserListColumnData failed: ' . $e->getMessage());
+        }
+
+        return $data;
+    }
+
+    /**
+     * Enforce the column-data contract on one user's plugin values: scalars (or
+     * null) only — arrays, objects and resources are rejected so a plugin can't
+     * leak blobs or nested structures — with a safe key charset and per-value
+     * and per-user size caps.
+     *
+     * @param array<mixed, mixed> $extra
+     * @return array<string, string|int|float|bool|null>
+     */
+    private function sanitizeColumnValues(array $extra): array
+    {
+        $clean = [];
+        foreach ($extra as $key => $value) {
+            if (count($clean) >= self::COLUMN_MAX_FIELDS) {
+                break;
+            }
+            if (!is_string($key)) {
+                continue;
+            }
+            $key = preg_replace('/[^A-Za-z0-9_.\-]/', '', $key);
+            if ($key === '') {
+                continue;
+            }
+            if ($value !== null && !is_scalar($value)) {
+                continue; // scalar-only: drop arrays/objects/resources
+            }
+            if (is_string($value) && strlen($value) > self::COLUMN_VALUE_MAX_LEN) {
+                $value = substr($value, 0, self::COLUMN_VALUE_MAX_LEN);
+            }
+            $clean[$key] = $value;
+        }
+
+        return $clean;
+    }
+
     /**
      * Merge plugin-contributed Users tabs with the built-in "All Users" tab,
      * dropping malformed entries and tabs the caller isn't authorized for, then
@@ -273,6 +474,11 @@ private function indexViaFlex(ServerRequestInterface $request, FlexDirectory $di
             }
         }
 
+        // Let plugins attach their declared column values to this page of
+        // users (getgrav/grav-plugin-admin2#111). Scoped to the served page,
+        // applied after pagination — the indexed fast path above is untouched.
+        $data = $this->applyColumnData($data, $this->getUser($request));
+
         return ApiResponse::paginated(
             data: $data,
             total: $total,
@@ -310,6 +516,10 @@ private function indexViaAccounts(ServerRequestInterface $request): ResponseInte
         $total = count($allUsers);
         $paged = array_slice($allUsers, $pagination['offset'], $pagination['limit']);
 
+        // Column data is resolved for the served page only — never $allUsers —
+        // so a plugin isn't pushed into loading metadata for every account.
+        $paged = $this->applyColumnData($paged, $this->getUser($request));
+
         return ApiResponse::paginated(
             data: $paged,
             total: $total,

classes/Api/Serializers/MediaSerializer.php

@@ -27,6 +27,18 @@ public function serialize(object $medium, array $options = []): array
             'size' => (int) ($medium->get('size') ?? 0),
         ];
 
+        // Alt/title come from the `.meta.yaml` sidecar, which Grav merges into
+        // the medium's attributes. Exposing them here lets the media panel
+        // insert `![alt](file)` instead of overwriting alt with the filename.
+        $alt = $medium->get('alt');
+        if (is_string($alt) && $alt !== '') {
+            $data['alt'] = $alt;
+        }
+        $title = $medium->get('title');
+        if (is_string($title) && $title !== '') {
+            $data['title'] = $title;
+        }
+
         if (str_starts_with($mime, 'image/')) {
             $width = $medium->get('width');
             $height = $medium->get('height');