File Sharing API for PHP SDK

You can upload and share files up to 5 MB on PubNub. Common uses include sharing images in chat apps and documents in healthcare.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Send file

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, sendFile internally calls the publishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

For details on the method that publishes the file message, see Publish file message.

Method(s)

$pubnub->sendFile()
->channel(string)
->fileName(string)
->message(string|array)
->shouldStore(Boolean)
->shouldCompress(Boolean)
->ttl(Int)
->fileHandle(Resource)
->fileContent(bytes|File)
->meta(string|array)
->customMessageType(string)
->sync();
* required
ParameterDescription
channel *
Type: string
Default:
n/a
Channel for the file.
fileName *
Type: string
Default:
n/a
Name of the file to send.
message
Type: string or array
Default:
n/a
Message to send along with the file to the specified channel.
shouldStore
Type: Boolean
Default:
True
Whether to store the published file message in the channel history.
shouldCompress
Type: Boolean
Default:
True
Whether to compress the request payload.
ttl
Type: Integer
Default:
n/a
How long the message should be stored in the channel's storage.
fileHandle *
Type: Resource
Default:
n/a
Pointer to a resource to be read and placed in the buffer.
fileContent *
Type: bytes or PHP file object
Default:
n/a
Input stream with file content.
meta
Type: string or array
Default:
n/a
Metadata object which can be used with the filtering ability.
customMessageType
Type: string
Default:
n/a
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.

Sample code

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

Returns

Returns PNSendFileResult.

PNSendFileResult

Property NameTypeDescription
name
string
Name of the uploaded file.
fileId
string
ID of the uploaded file.

List channel files

Retrieve a list of files uploaded to a channel.

Method(s)

$pubnub->listFiles()
->channel(string)
->sync();
* required
ParameterDescription
channel *
Type: string
Default:
n/a
Channel to get the list of files.

Sample code


Returns

Returns PNGetFilesResult.

PNGetFilesResult

Property NameTypeDescription
next
string
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
prev
string
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
count
Int
Number of files returned.
data
Array
Array of PNGetFilesItem.

PNGetFilesItem contains the following properties:

Property NameTypeDescription
id
string
Id of the uploaded file.
name
string
Name of the upload file.
size
string
Size of the uploaded file.
creationTime
string
Time of creation.

Get file URL

Generate a URL to download a file from the target channel.

Method(s)

$pubnub.getFileDownloadUrl()
->channel(string)
->fileId(string)
->fileName(string)
->sync()
* required
ParameterDescription
channel *
Type: string
Name of channel to which the file has been uploaded.
fileName *
Type: string
Name under which the uploaded file is stored.
fileId *
Type: string
Unique identifier for the file, assigned during upload.

Sample code


Returns

Returns PNGetFileDownloadURLResult.

PNGetFileDownloadURLResult

Property NameTypeDescription
fileUrl
string
URL to be used to download the requested file.

Download file

Download a file from the specified channel.

Method(s)

$pubnub.downloadFile()
->channel(string)
->fileId(string)
->fileName(string)
->sync()
* required
ParameterDescription
channel *
Type: string
Name of channel to which the file has been uploaded.
fileName *
Type: string
Name under which the uploaded file is stored.
fileId *
Type: string
Unique identifier for the file, assigned during upload.

Sample code


Returns

Returns PNDownloadFileResult.

PNDownloadFileResult

Property NameTypeDescription
fileContent
bytes
The file that was uploaded.

Delete file

Delete a file from the specified channel.

Method(s)

$pubnub.deleteFile()
->channel(string)
->fileId(string)
->fileName(string)
->sync()
* required
ParameterDescription
channel *
Type: string
The channel from which to delete the file.
fileId *
Type: string
Unique identifier of the file to be deleted.
fileName *
Type: string
Name of the file to be deleted.

Sample code


Returns

Returns PNDeleteFileResult.

Property NameTypeDescription
status
Int
Returns a status code.

Publish file message

Publish the uploaded file message to a specified channel.

This method is called internally by sendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when sendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use publishFileMessage to manually resend a file message to a channel without repeating the upload step.

Method(s)

$pubnub.publishFileMessage()
->channel(string)
->fileId(string)
->fileName(string)
->message(string|array)
->meta(string|array)
->shouldStore(Boolean)
->ttl(Int)
->customMessageType(string)
->sync();
* required
ParameterDescription
channel *
Type: String
Default:
n/a
Name of channel to publish file message.
file_id *
Type: String
Default:
n/a
Unique identifier of the file.
file_name *
Type: String
Default:
n/a
Name of the file.
message
Type: Dictionary
Default:
n/a
The payload.
meta
Type: Dictionary
Default:
n/a
Metadata object which can be used with the filtering ability.
should_store
Type: Boolean
Default:
True
Whether to store this message in history. Set to False to not store it. By default, messages are stored according to the retention policy set on your key.
ttl
Type: Int
Default:
0
How long the message should be stored in the channel's history. If not specified, defaults to the key set's retention value.
customMessageType
Type: string
Default:
n/a
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.

Sample code


Returns

Returns PNPublishFileMessageResult.

PNPublishFileMessageResult

PNPublishFileMessageResult field:

Property NameTypeDescription
timestamp
string
The timetoken when the message was published.
Last updated on