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();
Parameter | Description |
---|---|
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
Returns
Returns PNSendFileResult
.
PNSendFileResult
Property Name | Type | Description |
---|---|---|
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();
Parameter | Description |
---|---|
channel *Type: string Default: n/a | Channel to get the list of files. |
Sample code
Returns
Returns PNGetFilesResult
.
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 a URL to download a file from the target channel
.
Method(s)
$pubnub.getFileDownloadUrl()
->channel(string)
->fileId(string)
->fileName(string)
->sync()
Parameter | Description |
---|---|
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 Name | Type | Description |
---|---|---|
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()
Parameter | Description |
---|---|
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 Name | Type | Description |
---|---|---|
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()
Parameter | Description |
---|---|
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 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 | Description |
---|---|
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 Name | Type | Description |
---|---|---|
timestamp | string | The timetoken when the message was published. |