File Sharing API for PubNub PHP SDK

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

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.

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();

Parameter	Type	Required	Default	Description
channel	string	Yes		Channel for the file.
fileName	string	Yes		Name of the file to send.
message	string or array	Optional		Message which should be sent along with file to specified channel.
shouldStore	Boolean	Optional	True	Whether PubNub published file message should be stored in channel history.
shouldCompress	Boolean	Optional	True	Whether the request payload should be compressed.
ttl	Integer	Optional		How long message should be stored in channel's storage.
fileHandle	Resource	Yes		Pointer to a resource to be read and placed in the buffer.
fileContent	bytes or PHP file object	Yes		Input stream with file content.
meta	string or array	Optional		Meta data object which can be used with the filtering ability.
customMessageType	string	Optional		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.

Basic Usage

Returns

The sendFile() operation returns an PNSendFileResult which contains the following fields:

PNSendFileResult

Property Name	Type	Description
name	string	Name of the uploaded file.
fileId	string	ID of the uploaded file.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

$pubnub->listFiles()
    ->channel(string)
    ->sync();

Parameter	Type	Required	Default	Description
channel	string	Yes	n/a	Channel to get the list of files.

Basic Usage

Returns

The listFiles() operation returns an PNGetFilesResult which contains the following fields:

PNGetFilesResult

Property Name	Type	Description
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 Name	Type	Description
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 URL which can be used to download file from target Channel.

Method(s)

$pubnub.getFileDownloadUrl()
    ->channel(string)
    ->fileId(string)
    ->fileName(string)
    ->sync()

Parameter	Type	Required	Description
channel	string	Yes	Name of channel to which the file has been uploaded.
fileName	string	Yes	Name under which the uploaded file is stored.
fileId	string	Yes	Unique identifier for the file, assigned during upload.

Basic Usage

Returns

The getFileDownloadUrl() operation returns an PNGetFileDownloadURLResult which contains the following fields:

PNGetFileDownloadURLResult

Property Name	Type	Description
fileUrl	string	URL to be used to download the requested file.

Download file

Download file from specified Channel.

Method(s)

$pubnub.downloadFile()
    ->channel(string)
    ->fileId(string)
    ->fileName(string)
    ->sync()

Parameter	Type	Required	Description
channel	string	Yes	Name of channel to which the file has been uploaded.
fileName	string	Yes	Name under which the uploaded file is stored.
fileId	string	Yes	Unique identifier for the file, assigned during upload.

Basic Usage

Returns

The downloadFile() operation returns an PNDownloadFileResult which contains the following fields:

PNDownloadFileResult

Property Name	Type	Description
fileContent	bytes	The file that was uploaded.

Delete file

Delete file from specified Channel.

Method(s)

$pubnub.deleteFile()
    ->channel(string)
    ->fileId(string)
    ->fileName(string)
    ->sync()

Parameter	Type	Required	Description
channel	string	Yes	The channel from which to delete the file.
fileId	string	Yes	Unique identifier of the file to be deleted.
fileName	string	Yes	Name of the file to be deleted.

Basic Usage

Returns

The deleteFile() operation returns an PNDeleteFileResult which contains the following fields:

Property Name	Type	Description
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();

Parameter	Type	Required	Default	Description
channel	String	Yes	n/a	Name of channel to publish file message.
file_id	String	Yes	n/a	Unique identifier of the file.
file_name	String	Yes	n/a	Name of the file.
message	Dictionary	Optional	n/a	The payload.
meta	Dictionary	Optional	n/a	Meta data object which can be used with the filtering ability.
should_store	Boolean	Optional	True	Set to False to not store this message in history. By default, messages are stored according to the retention policy you set on your key.
ttl	Int	Optional	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	string	Optional		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.

Basic Usage

pubnub.publishFileMessage()
    ->message("Hey, this is the requested file.")
    ->channel("channel_1")
    ->fileId("p1n4ppl3p1zz4")
    ->fileName("pinapplePizza.jpg")
    ->customMessageType("file-message")
    ->sync();

Returns

The publish_file_message() operation returns an PNPublishFileMessageResult which contains the following fields:

PNPublishFileMessageResult

The publishFileMessage() operation returns a PNPublishFileMessageResult which contains the following property:

Property Name	Type	Description
timestamp	string	The timetoken when the message was published.