CKFinder 3 – PHP 连接器文档
命令

目录

CKFinder 命令的行为就像控制器。它们封装了处理请求并生成适当响应（在 CKFinder 中通常是 JSON）所需的逻辑。命令根据 command URL 参数解析。

每个命令类的心脏是它的 execute 方法，所有处理都在这里进行。execute 方法允许在执行期间进行基于类型的参数注入。

例如，要轻松访问当前请求对象和 CKFinder 配置，您可以将它们定义为 execute 方法参数，如下所示

public function execute(Request $request, Config $config)
{
// ...
}

可以作为 execute 方法参数注入的对象是

定义权限

执行每个 CKFinder 命令都需要在 ACL 配置设置 中设置适当的权限。命令所需的权限在命令类中名为 $requires 的数组属性中定义

class CreateFolder extends CommandAbstract
{
protected $requires = array(Permission::FOLDER_CREATE);
// ...
}

在命令对象实例化期间，使用 Acl 检查命令所需的全部权限。

有关所有可用权限常量的详细信息，请参阅 Permission。

处理错误

每个命令响应都可以选择性地包含一个错误对象，以防服务器端出现任何问题

{
"error": {
"number": 100,
"message": "可选"
},
// ...
}

或者对于可以返回多个错误的命令（例如 CopyFiles、MoveFiles）

{
"error": {
"number": 301,
"errors": [
{
"number": 115,
// ...
}
]
},
// ...
}

更改现有命令

所有现有的 CKFinder 命令都可以使用事件系统进行更改（例如，添加附加信息或更改默认 JSON 响应）。有关更详细的信息，请参阅 事件 文章。

在某些情况下，更改从 CKFinder 传递到服务器端连接器的命令参数可能很有用。有关如何执行此操作的示例，请查看 AlterCommand 插件，该插件位于 CKFinder 3 示例 JavaScript 插件 存储库中。

创建自定义命令

自定义 CKFinder 命令可以作为插件实现。您可以在 HOWTO 的 自定义命令 部分找到示例插件的描述。

查看 ImageInfo 插件（位于 CKFinder 3 示例 JavaScript 插件 存储库中）也很有用，以了解如何从 JavaScript 插件请求命令。您可以在 将命令发送到服务器 部分找到更多信息，该部分位于 CKFinder 3 JavaScript 文档 中。

CSRF 防护

由于
CKFinder 3.2.0

CKFinder 3 PHP 连接器提供了一种机制来保护应用程序免受 跨站点请求伪造 (CSRF) 攻击（请参阅 csrfProtection 配置选项）。默认保护方法基于 双重提交 cookie。

如果启用了保护，将检查对修改任何类型资源的命令的所有请求，以确保它们具有有效的 CSRF 令牌。令牌是一个随机字符串值，长度至少为 32 个字符，应使用加密安全的伪随机数生成器生成。在验证请求时，连接器会检查请求 POST 参数和请求 cookie 中是否存在相同的令牌（两个字段的预期名称均为 ckCsrfToken）。

CKFinder 命令列表

通用 URL 参数

名称描述
command 要执行的命令的名称。
type 资源类型名称。
currentFolder 当前工作文件夹路径。

CopyFiles

描述从选定文件夹复制文件。
方法POST
示例请求

将 Files 资源类型的 sub1 目录中的两个文件复制到 Images 资源类型的根 (/) 目录。

files 参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
"options": ""
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
"options": ""
}
]
/ckfinder/core/connector/php/connector.php?command=CopyFiles&type=Images&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/images/",
"acl": 255
},
"copied": 2
}
说明请求应包含一个名为 files 的数组参数，其元素定义要复制的源文件。每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。
  • options – 定义如果目标文件夹中已存在同名文件，应如何复制文件的一个参数。option 参数可以包含以下值
    • 默认情况下，它是一个空字符串，在这种情况下，如果文件已存在，则会将适当的错误添加到响应中。
    • overwrite – 覆盖目标文件。
    • autorename – 在这种情况下，复制文件的名称会通过在文件名中添加数字而改变，例如，自动重命名后的 file.txt 是 file(1).txt。

CreateFolder

描述创建子文件夹。
方法POST
示例请求

在 Files 资源类型的根 (/) 文件夹中创建 My Folder 文件夹

/ckfinder/core/connector/php/connector.php?command=CreateFolder&type=Files&currentFolder=/&newFolderName=My Folder
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"newFolder": "My Folder",
"created": 1
}

DeleteFiles

描述删除给定的文件。
方法POST
示例请求

删除 Files 资源类型的 sub1 目录中的两个文件。

files 参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
}
]
/ckfinder/core/connector/php/connector.php?command=DeleteFiles&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"deleted": 2
}
说明请求应包含一个名为 files 的数组参数，其元素定义要删除的源文件。每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。

DeleteFolder

描述删除给定的文件夹。
方法POST
示例请求

删除 Files 资源类型的 sub1 目录

/ckfinder/core/connector/php/connector.php?command=DeleteFolder&type=Files&currentFolder=/sub1/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"deleted": 1
}

DownloadFile

描述从服务器下载文件。
方法GET
示例请求

从 Files 资源类型的根 (/) 目录下载名为 Test.jpg 的文件

/ckfinder/core/connector/php/connector.php?command=DownloadFile&type=Files&currentFolder=/&fileName=Test.jpg
说明此命令不期望连接器返回文本响应。相反，它必须将文件数据流式传输到客户端。

FileUpload

描述将文件上传到给定文件夹。
方法POST
示例请求

将文件上传到 Files 资源类型的根 (/) 目录

/ckfinder/core/connector/php/connector.php?command=FileUpload&type=Files&currentFolder=/
示例响应

{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"fileName": "fileName.jpg",
"uploaded": 1
}
说明
  • 文件数据应编码为 multipart/form-data。
  • 包含上传文件的 POST 参数应命名为 upload。
  • 上传的文件名可能包含非 ASCII 字符。

GetFiles

描述返回给定文件夹的文件列表。
方法GET
示例请求获取 Images 资源类型的 /Docs/ 文件夹中的文件列表
/ckfinder/core/connector/php/connector.php?command=GetFiles&type=Images&currentFolder=/Docs/
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/Docs/",
"url": "/ckfinder/userfiles/images/Docs/",
"acl": 255
},
"files": [
{
"name": "image1.png",
"date": "201406080924",
"size": 1
},
{
"name": "測試.png",
"date": "201406080924",
"size": 12
}
]
}
说明

文件名可能包含非 ASCII 字符，如上面使用中文字符的示例所示。

date 属性对应于上次文件修改时间，格式为 YYYYMMDDHHmm，其中

  • YYYY – 年份（4 位数字）。
  • MM – 月份（两位数，带前导零）。
  • DD – 日份（两位数，带前导零）。
  • HH – 小时（24 小时制，两位数，带前导零）。
  • mm – 分钟（两位数，用零填充）。

size 属性包含文件大小（以千字节为单位）。

GetFileUrl

描述返回指向文件的直接 URL。
方法GET
示例请求获取存储在 Images 资源类型 /kittens/ 文件夹中的名为 longcat.jpg 文件的直接 URL
/ckfinder/core/connector/php/connector.php?command=GetFileUrl&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"url": "/ckfinder/userfiles/images/kittens/longcat.jpg"
}
说明此命令返回的 URL 取决于为资源类型定义的后端。 在大多数情况下，需要为后端定义 baseUrl 才能获取指向文件的有效直接 URL。

GetFolders

描述返回给定文件夹的子文件夹列表。
方法GET
示例请求获取 Images 资源类型 /Docs/ 文件夹内的子文件夹。
/ckfinder/core/connector/php/connector.php?command=GetFolders&type=Images&currentFolder=/Docs/
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/Docs/",
"url": "/ckfinder/userfiles/images/Docs/",
"acl": 255
},
"folders": [
{
"name": "folder1",
"hasChildren": false,
"acl": 255
},
{
"name": "繁體中文字",
"hasChildren": false,
"acl": 255
}
]
}
说明文件夹名称可能包含非 ASCII 字符，如上面的示例中的中文字符。

GetResizedImages

描述返回图像文件的大小调整版本列表。
方法GET
示例请求获取存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的大小调整版本
/ckfinder/core/connector/php/connector.php?command=GetResizedImages&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"originalSize":"1920x1200",
"resized": {
"small": "longcat__480x300.jpg",
"medium": "longcat__600x375.jpg",
"large": "longcat__800x500.jpg",
"__custom": ["longcat__200x125.jpg", "longcat__300x188.jpg"]
}
}
说明图像的大小调整版本始终保持原始图像的长宽比。 当图像的大小调整版本与 images.sizes 配置选项中定义的任何大小匹配时，它将附加到响应中相应键下（如上面的示例中的 small、medium、large）。 所有其他现有的调整大小版本都存储在名为 __custom 的键下。

ImageEdit

描述执行基本图像修改：裁剪、旋转、调整大小。
方法POST
示例请求

要执行的操作以及所需参数在 actions 数组参数中发送。

actions 参数结构的示例（JSON 表示法）

request["actions"] = [
{
"action": "rotate",
"angle": 90 // 顺时针旋转的度数。
},
{
"action": "resize",
"width": 300, // 最大图像宽度。
"height": 300 // 最大图像高度。
},
{
"action": "crop",
"x": 0, // 裁剪区域左上角的 X 坐标。
"y": 0, // 裁剪区域左上角的 Y 坐标。
"width": 225, // 裁剪区域宽度。
"height": 150 // 裁剪区域高度。
}
]

取决于是否提供了 newFileName 参数

  • 如果提供，将创建具有给定名称的新文件。
  • 如果省略，将替换当前文件。
/ckfinder/core/connector/php/connector.php?command=ImageEdit&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"saved": 1
}

ImageInfo

描述返回有关图像文件维度的信息。
方法GET
示例请求

获取存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的尺寸。

/ckfinder/core/connector/php/connector.php?command=ImageInfo&type=Images&currentFolder=/kittens/&fileName=longcat.jpg
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"width": 1440,
"height": 900
}

ImagePreview

描述创建图像文件的大小调整版本。
方法GET
示例请求

创建存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的大小调整版本。 将其调整为 450x450

/ckfinder/core/connector/php/connector.php?command=ImagePreview&type=Images&currentFolder=/kittens/&fileName=longcat.jpg&size=450x450
示例响应此命令不希望连接器返回文本响应。 相反，它必须将图像数据流式传输到客户端。
说明

返回的图像始终保持原始图像的长宽比（使用为边框计算的较高缩放系数）。 当请求的大小与其长宽比不匹配时，将更正请求的大小。

使用此命令生成的图像不会存储在服务器端。

ImageResize

描述创建图像文件的大小调整版本。
方法POST
示例请求

创建存储在 Images 资源类型 /kittens/ 文件夹中的 longcat.jpg 图像的大小调整版本。 将其调整为 450x450

/ckfinder/core/connector/php/connector.php?command=ImageResize&type=Images&currentFolder=/kittens/&fileName=longcat.jpg&size=450x450
示例响应
{
"resourceType": "Images",
"currentFolder": {
"path": "/kittens/",
"url": "/ckfinder/userfiles/images/kittens/",
"acl": 255
},
"url":"/ckfinder/userfiles/images/kittens/__thumbs/longcat.jpg/longcat__450x281.jpg" // 指向文件的直接 URL
}
说明

返回的图像始终保持原始图像的长宽比（使用为边框计算的较低缩放系数）。 当请求的大小与其长宽比不匹配时，将更正请求的大小。

使用此命令生成的图像存储在当前文件文件夹中创建的名为 __thumbs 的特殊文件夹中。

Init

描述这是 CKFinder 发出的第一个命令。 它返回连接器的常规设置和所有配置的资源类型。
方法GET
示例请求
/ckfinder/core/connector/php/connector.php?command=Init
示例响应
{
"enabled": true,
"s": "",
"c": "",
"thumbs": ["150x150", "300x300", "500x500"],
"images":{"max":"500x400","sizes":{"small":"480x320","medium":"600x480","large":"800x600"}},
"uploadMaxSize": "425167",
"uploadCheckImages": true,
"resourceTypes": [
{
"name": "Files",
"url": "/ckfinder/userfiles/files",
"allowedExtensions": "7z,aiff,asf,avi,bmp,csv,doc,docx,fla,flv,gif,gz,gzip,jpeg,zip",
"deniedExtensions": "",
"hash": "8b787e3ea25b5079",
"hasChildren": false,
"acl": 1023,
"maxSize": 32768
},
{
"name": "Images",
"url": "/ckfinder/userfiles/images",
"allowedExtensions": "bmp,gif,jpeg,jpg,png",
"deniedExtensions": "",
"hash": "b8de0a3f3cb3cd1f",
"hasChildren": false,
"acl": 1023,
"maxSize": 65536
}
]
}

MoveFiles

描述将文件从选定的文件夹中移动。
方法POST
示例请求

将两个文件从 Files 资源类型的 sub1 目录移动到 Images 资源类型的根 (/) 目录。

files 参数结构示例（JSON 表示法）

request["files"] = [
{
"name": "file1.jpg",
"type": "Files",
"folder": "/sub1/"
"options": ""
},
{
"name": "file2.png",
"type": "Files",
"folder": "/sub1/"
"options": ""
}
]
/ckfinder/core/connector/php/connector.php?command=MoveFiles&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"moved": 2
}
说明请求应包含一个名为 files 的数组参数，其元素定义要移动的源文件。 每个数组元素应包含以下参数
  • name – 文件名。
  • type – 文件资源类型。
  • folder – 文件夹。
  • options – 定义当目标文件夹中已存在同名文件时文件应如何移动的参数。 option 参数可以包含以下值
    • 默认情况下，它是一个空字符串，在这种情况下，当文件已存在时，将向响应添加适当的错误。
    • overwrite – 覆盖目标文件。
    • autorename – 在这种情况下，移动文件的名称会通过在文件名中添加一个数字来更改，例如，file.txt 自动重命名后变为 file(1).txt。

Operation

由于
CKFinder 3.1.0
描述跟踪耗时连接器命令中操作的进度。
方法GET
示例请求

可以通过传递一个名为 operationId 的附加参数来启动耗时命令的进度跟踪

/ckfinder/core/connector/php/connector.php?command=RenameFolder&type=Files&currentFolder=/foo/&newFolderName=bar&operationId=i52q7a7db83rz3n6

operationId 是一个唯一的操作标识符，应与以下正则表达式匹配：^[a-z0-9]{16}。

然后可以使用对 Operation 命令的请求定期检查操作的状态

/ckfinder/core/connector/php/connector.php?command=Operation&operationId=i52q7a7db83rz3n6
示例响应
{
"total": 291,
"current": 128
}
说明

并非所有命令都支持操作跟踪，此功能可能取决于为后端定义的存储类型。

此命令可以使用以下可选参数

  • abort – 如果此布尔参数存在，则耗时操作将立即中止。

Proxy

由于
CKFinder 3.1.0
描述

将文件提供给浏览器而不强制下载。 此命令在您希望在网页上使用无法直接访问的文件时很有用。 这些可能是存储在没有定义 baseUrl 的后端上的文件（例如私有 FTP 服务器），或者不在 Web 服务器根文件夹中的文件。 如果 useProxyCommand 标志在后端配置中设置，则 CKFinder 生成的所有链接都将指向 Proxy 命令。

注意：如果您决定使用此选项，则 CKFinder 生成的所有链接都将指向 Proxy 命令，并且将依赖 CKFinder 连接器才能正常工作。

方法GET
示例请求
/ckfinder/core/connector/php/connector.php?command=Proxy&type=Files&currentFolder=/&fileName=foo.jpg
示例响应此命令不期望连接器返回文本响应。相反，它必须将文件数据流式传输到客户端。
说明此命令可以使用以下可选参数
  • cache – 一个整数值，定义以秒为单位的缓存生存期（这对应于 Expires 和 Cache-Control 响应头）。 请参阅 cache 配置选项。
  • thumbnail – 公共缩略图文件的名称，如果应提供图像的大小调整版本。

QuickUpload

描述将文件上传到给定的文件夹。 此命令与 FileUpload 非常相似，它用于处理来自 CKEditor 图像或链接对话框的上传。
方法POST
示例请求

此命令接受一个名为 responseType 的附加 URL 参数，该参数定义返回响应的格式。

将文件上传到 Files 资源类型的根 (/) 目录

/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files&currentFolder=/
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"fileName": "fileName.jpg",
"uploaded": 1
}
说明
  • 文件数据应编码为 multipart/form-data。
  • 包含上传文件的 POST 参数应命名为 upload。
  • 上传的文件名可能包含非 ASCII 字符。

RenameFile

描述重命名文件。
方法POST
示例请求

将 Files 资源类型 sub1 目录中的文件 foo.jpg 重命名为 bar.jpg

/ckfinder/core/connector/php/connector.php?command=RenameFile&type=Files&currentFolder=/sub1/&fileName=foo.jpg&newFileName=bar.jpg
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"name": "foo.jpg",
"newName":"bar.jpg",
"renamed": 1
}

RenameFolder

描述重命名文件夹。
方法POST
示例请求

将 Files 资源类型中的 sub1 文件夹重命名为 sub1_renamed

/ckfinder/core/connector/php/connector.php?command=RenameFolder&type=Files&currentFolder=/sub1/&newFolderName=sub1_renamed
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/sub1/",
"url": "/ckfinder/userfiles/files/sub1/",
"acl": 255
},
"newName": "sub1_renamed",
"newPath": "/sub1_renamed/",
"renamed": 1
}

SaveImage

描述将 Base64 编码的 PNG 图像保存到文件。
方法POST
示例请求

将 content 参数中发送的 Base64 编码图像保存为 Files 资源类型根 (/) 目录中的 Test.jpg 文件

/ckfinder/core/connector/php/connector.php?command=SaveImage&type=Files&currentFolder=/&fileName=Test.jpg
示例响应
{
"resourceType": "Files",
"currentFolder": {
"path": "/",
"url": "/ckfinder/userfiles/files/",
"acl": 255
},
"saved": 1,
"date": "201406080924",
"size": 1
}

Thumbnail

描述下载图像文件的缩略图。
方法GET
示例请求

下载 Files 资源类型根 (/) 目录中名为 Test.jpg 的文件的缩略图

/ckfinder/core/connector/php/connector.php?command=Thumbnail&type=Files&currentFolder=/&fileName=Test.jpg&size=150x150
响应此命令不希望连接器返回文本响应。 相反，它必须将缩略图文件数据流式传输到浏览器。
说明

size 参数可用于控制返回的缩略图图像的大小。 默认情况下，CKFinder 3 for PHP 连接器支持以下缩略图大小

  • 150x150
  • 300x300
  • 500x500

默认大小可以在主配置文件中覆盖。