My interpretation of gridfile_get_metadata() is to obtain user-defined metadata, where the user-defined metadata is embedded in the "file-system" specific metadata (such as md5, upload date, content type, ...). At least, gridfile_get_metadata() tries to access the object named "metadata" and returns its content, which is - without other operations - empty.

Currently, i use the plain mongo db interface to add the additional metadata with separate operations. It would be nice, to pass this additional (user-defined) meta-data as bson field to the following file-creating operations.

gridfs_store_buffer()
gridfs_insert_file()

if backward compatibility is already an issue, providing new names for this functions would help.