Payload CMS Release: 2.25.0

TL;DR

PayloadCMS 2.25.0 Release

This release introduces two notable features: the ability to append metadata to uploaded media files and MongoDB collation support. It also addresses several bugs, including fixes for handling null values in query strings, preserving ObjectIDs in deep copies, properly displaying zero values in list views, and improving relationship filtering. These changes enhance both the developer experience and system reliability.

Highlight of the Release

• Added support for appending metadata to uploaded media files
• Introduced MongoDB collation support for improved text handling
• Fixed handling of zero values in number fields in list views
• Improved relationship filtering with relaxed equality checks
• Added support for null values in query strings

Migration Guide

Using Media Metadata

To use the new media metadata feature, update your upload field configuration to include the withMetadata option:

{
  name: 'media',
  type: 'upload',
  relationTo: 'media',
  withMetadata: true // Enable metadata to be appended to the file
}

Enabling MongoDB Collation

To enable MongoDB collation features, update your MongoDB adapter configuration:

import { mongooseAdapter } from '@payloadcms/db-mongodb'

const mongoDBAdapter = mongooseAdapter({
  // Your existing MongoDB config
  collation: true // Enable MongoDB collation
})

Note that enabling collation may change the behavior of text comparisons and sorting in your application, so test thoroughly after enabling this feature.

Upgrade Recommendations

This release contains valuable features and important bug fixes without introducing breaking changes. It's recommended for all PayloadCMS users to upgrade to version 2.25.0, especially if you:

• Work with media uploads and need to embed metadata
• Use MongoDB and need better international text handling
• Have experienced issues with relationship filtering, particularly with PostgreSQL
• Need to handle null values in query strings
• Display number fields with zero values in list views

The upgrade should be straightforward as this is a non-breaking release. Simply update your PayloadCMS dependency to version 2.25.0 in your package.json and run your package manager's install command.

Bug Fixes

Fixed Zero Value Display in List Views

Previously, number fields with a value of 0 were not being properly displayed in list views (issue #5510). This has been fixed, ensuring that zero values are correctly rendered.

Improved Relationship Filtering

The equality check for relationship options in filters has been relaxed to address an issue where string values from query parameters weren't matching numeric IDs. This was particularly problematic with PostgreSQL, where IDs are numbers by default, causing infinite loops in some cases (issue #7103).

Support for Null Values in Query Strings

The system now properly handles null values in query strings, fixing an issue where null values weren't being correctly processed between client and server.

Preserved ObjectIDs in Deep Copy Operations

The deepCopyObject function was previously converting MongoDB ObjectIDs to a different format, which caused issues when these IDs needed to be preserved. This has been fixed to ensure ObjectIDs pass through the deep copy process unchanged.

New Features

Media Metadata Support

PayloadCMS now allows metadata to be appended to uploaded media files through the new withMetadata configuration option in the uploads config. This feature enables developers to store additional information directly within the media files themselves, which can be useful for embedding copyright information, descriptions, or other metadata that should travel with the file.

MongoDB Collation Support

A new optional collation feature flag has been added to the MongoDB adapter configuration. This enables MongoDB's collation capabilities, which provide language-specific rules for string comparison. This is particularly valuable for applications that need to handle international text with proper sorting and searching capabilities.

Security Updates

No specific security fixes were included in this release.

Performance Improvements

More Efficient Relationship Handling

The relaxed equality check for relationship options in filters not only fixes a bug but also prevents potential infinite loops that could occur with PostgreSQL databases, improving overall system performance and stability.

Improved Object Handling

The fix for preserving ObjectIDs in the deepCopyObject function improves the efficiency of operations that need to maintain MongoDB's native ObjectID format, reducing unnecessary conversions.

Impact Summary

PayloadCMS 2.25.0 enhances the platform's capabilities with two notable features: media metadata support and MongoDB collation. The media metadata feature allows developers to embed additional information directly into media files, which is valuable for maintaining file-level metadata that persists outside the database. The MongoDB collation support improves text handling for international applications.

Several important bug fixes are included that address pain points reported by users. The fix for zero values in list views resolves a long-standing display issue. The relationship filtering improvement is particularly important for PostgreSQL users who may have experienced infinite loops. Support for null values in query strings and proper preservation of ObjectIDs make the system more robust overall.

These changes collectively improve both developer experience and end-user reliability without introducing breaking changes, making this a recommended upgrade for all PayloadCMS users.

Full Release Notes