README

PHP jsHarmony CMS SDK

安装

安装和集成说明可在 jsHarmonyCMS.com 获取

API 文档

apHarmony\jsHarmonyCms\CmsPassthruResponse 类

公共属性
公共方法
- serve

apHarmony\jsHarmonyCms\CmsRedirect 类

构造函数
公共属性
- http_code
- url

jsHarmonyCmsEditor 类 (客户端 JS)

构造函数

apHarmony\jsHarmonyCms\CmsRouter 类

CmsRouter 构造函数

new CmsRouter($config)

参数

$config (数组) :: 包含以下一个或多个配置键的关联数组

[
  'content_path' => null,
  //(string) File path to published CMS content files

  'redirect_listing_path' => null,
  //(string) Path to redirect listing JSON file (relative to content_path)

  'default_document' => 'index.html',
  //(string) Default Directory Document

  'strict_url_resolution' => false,
  //(bool) Whether to support URL variations (appending "/" or Default Document)

  'passthru_timeout' => 30,
  //(int) Maximum number of seconds for passthru request

  'cms_clientjs_editor_launcher_path' => '/.jsHarmonyCms/jsHarmonyCmsEditor.js',
  //(string) Path where router will serve the client-side JS script that launches CMS Editor

  'cms_server_urls' => [],
  //Array(string) The CMS Server URLs that will be enabled for Page Editing (set to '*' to enable any remote CMS)
  //  * Used by page.editorScript, and the getEditorScript function
  //  * NOT used by jsHarmonyCmsEditor.js - the launcher instead uses access_keys for validating the remote CMS
]

示例

$cmsRouter = new CmsRouter([ 'cms_server_urls' => ['https://cms.example.com'] ]);

公共属性

CmsRouter->config

(数组)

包含 CmsRouter 的配置的关联数组。配置参数在上面的构造函数中定义。

$cmsRouter->config['passthru_timeout'] = 60;

公共方法

CmsRouter->serve

CmsRouter->serve(?string $url = null, array $options = [])

主要入口点 - 提供CMS内容

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

$options: (数组) (可选) 可能具有以下键的关联数组

[
   'onPage' => (function($router, $filename){ }),
   //Function to execute on page route
   //Return value will be passed as return value of "serve" function
   //Default: function($router, $filename){ $router->serveFile($filename); return true; }

   'on301' => (function($router, $url){ }),
   //Function to execute when a 301 redirect is processed
   //Return value will be passed as return value of "serve" function
   //Default: function($router, $url){ $router->redirect301($url); return true; }

   'on302' => (function($router, $url){ }),
   //Function to execute when a 302 redirect is processed
   //Return value will be passed as return value of "serve" function
   //Default: function($router, $url){ $router->redirect302($url); return true; }
   
   'onPassthru' => (function($router, $url){ }),
   //Function to execute when a PASSTHRU redirect is processed
   //Return value will be passed as return value of "serve" function
   //Default: function($router, $url){ $router->passthru($url)->serve(); return true; }

   'on404' => (function($router){ }|null)
   //Function to execute when on 404 / Page Not Found.  Set to null to continue on Page Not Found.
   //Return value will be passed as return value of "serve" function
   //Default: null

   'onError' => (function($router, $err){ }|null) 
   //Function to execute when an unexpected error occurs.  If null, Exception will be thrown instead.
   //Return value will be passed as return value of "serve" function
   //Default: null

   'serveCmsEditorScript' => (bool)
   //Whether the router should serve the CMS Editor Launcher script at config['cms_clientjs_editor_launcher_path']
   //Default: true
}

返回值

(混合类型) onPage, on301, on302, onPassthru, on404, 或 onError 处理程序的结果，或如果返回值为 null 或未定义，则返回 TRUE。

示例

$cmsRouter->serve();

CmsRouter->getStandalone

CmsRouter->getStandalone(?string $url = null)

主要入口点 - 获取独立集成所需的CMS页面数据

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

返回值

(CmsPage) 页面内容

如果页面是从CMS编辑器或未找到打开的，将返回空的 CmsPage 对象

示例

$cmsRouter->getStandalone();

CmsRouter->getPlaceholder

CmsRouter->getPlaceholder()

获取用于编辑器模板渲染的占位符页面

参数

N/A

返回值

(CmsPage) 占位符页面

示例

$cmsRouter->getPlaceholder();

CmsRouter->isInEditor

CmsRouter->isInEditor(?string $url = null)

检查页面是否在CMS编辑模式

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

返回值

(布尔值) 如果此页面是从CMS编辑器打开的，则为 TRUE

示例

if($cmsRouter->isInEditor()){ /* Perform Operation */ }

CmsRouter->resolve

CmsRouter->resolve(?string $url = null, array $options = [])

将URL转换为CMS内容路径

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

$options: (数组) (可选) 可能具有以下键的关联数组

[
   'strictUrlResolution' => (bool), 
   // Whether to try URL variations (adding "/", "/<default_document>")
   // Default: $this->config['strict_url_resolution']

   'variation' => (int)
   // Starting Variation ID
   // Default: 1
]

返回值

(字符串) CMS内容路径

示例

$contentPath = $cmsRouter->resolve($targetUrl);

CmsRouter->route

CmsRouter->route(?string $url = null)

在目标URL上运行CMS路由器

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

返回值

(CmsResponse|null) 包含页面文件名、重定向或未找到时的 null 的响应

示例

$response = $cmsRouter->route($targetUrl);

CmsRouter->matchRedirect

CmsRouter->matchRedirect(?array $redirects, ?string $url)

检查URL是否与重定向匹配并返回第一个匹配项

参数

redirects: (数组|null) CMS重定向数组（从 getRedirectData 函数获取）
url: (string|null) 与 CMS 重定向匹配的目标 URL

使用完整URL，根相关URL，或留空使用当前URL

返回值

(CmsRedirect|null) 重定向

示例

$redirect = $cmsRouter->matchRedirect($cmsRedirects);
if($redirect && ($redirect->http_code=='301')){
  $cmsRouter->redirect301($redirect->url);
}

CmsRouter->getRedirectData

CmsRouter->getRedirectData()

获取 CMS 重定向数据

需要定义 config['redirect_listing_path']

返回值

array|null CMS 重定向的 JSON 数组

示例

$cmsRedirects = $cmsRouter->getRedirectData();

CmsRouter->getEditorScript

CmsRouter->getEditorScript(?string $url = null)

生成 CMS 编辑器脚本

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

返回值

(string) 启动 CMS 编辑器的 HTML 代码

如果页面不是从 CMS 编辑器启动，则返回空字符串

安全

查询字符串 jshcms_url 参数将与 config['cms_server_urls'] 进行验证

如果在 config['cms_server_urls'] 中未找到 CMS 服务器，则返回空字符串

示例

echo $cmsRouter->getEditorScript();

CmsRouter->serveFile

CmsRouter->serveFile($filePath)

向用户提供服务文件

参数

$filePath (string) 目标文件的路径

示例

$pageFilename = $cmsRouter->getPageFileName();
$cmsRouter->serveFile($pageFilename);

CmsRouter->redirect301

CmsRouter->redirect301(string $url)

执行 301 重定向

参数

$url (string) 重定向的目标 URL

示例

$cmsRouter->redirect301('https://example.com');

CmsRouter->redirect302

CmsRouter->redirect302(string $url)

执行 302 重定向

参数

$url (string) 重定向的目标 URL

示例

$cmsRouter->redirect302('https://example.com');

CmsRouter->passthru

CmsRouter->passthru(string $url)

执行 Passthru 请求

参数

$url (string) Passthru 重定向的目标 URL

返回值

(CmsPassthruResponse) 响应

调用 CmsPassthruResponse->serve() 方法来提供服务页面

示例

$cmsRouter->passthru('https://example.com')->serve();

CmsRouter->generate404

CmsRouter->generate404()

生成 404 未找到页面

参数

N/A

示例

$cmsRouter->generate404();

CmsRouter->generateError

CmsRouter->generateError($err)

生成 500 错误页面

参数

$err (Exception|string) 错误信息

示例

$cmsRouter->generateError('An unexpected error has occurred.');

CmsRouter->getPage

CmsRouter->getPage(?string $url = null, array $options = [])

从 URL 获取 CMS 页面

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

$options: (数组) (可选) 可能具有以下键的关联数组

[
   'variation' => (int)
   // Starting Variation ID
   // Default: 1
]

返回值

(CmsPage|null) 页面数据，如果页面未找到则返回 null

示例

$page = $cmsRouter->getPage($targetUrl);

CmsRouter->getPageFromFile

CmsRouter->getPageFromFile(string $filePath)

从文件路径获取 CMS 页面

参数

$filePath (string) 目标文件的路径

返回值

(CmsPage|null) 页面数据，如果页面未找到或发生错误则返回 null

示例

$page = $cmsRouter->getPageFromFile($filePath);

CmsRouter->getPageFileName

CmsRouter->getPageFileName(?string $url = null, array $options = [])

获取 CMS 页面文件

参数

$url (字符串|null) (可选) CMS 页面 URL

使用完整URL，根相关URL，或留空使用当前URL

$options: (数组) (可选) 可能具有以下键的关联数组

[
   'variation' => (int)
   // Starting Variation ID
   // Default: 1
]

返回值

(string) CMS 内容文件的完整路径

CmsPageNotFoundException 异常会在页面未找到时抛出

示例

$pageFile = $cmsRouter->getPageFile($targetUrl);

CmsRouter->getFile

CmsRouter->getFile($filePath)

从文件系统读取文件

参数

$filePath (string) 目标文件的路径

返回值

(string) 文件内容

示例

$pageFilename = $cmsRouter->getPageFileName();
$pageContent = $cmsRouter->getFile($pageFilename);

CmsRouter->getJsonFile

CmsRouter->getJsonFile($filePath)

读取并解析 JSON 文件

参数

$filePath (string) 目标文件的路径

返回值

(array|null) JSON 内容，如果文件未找到或发生错误则返回 null

示例

$pageFilename = $cmsRouter->getPageFileName();
$pageData = $cmsRouter->getJsonFile($pageFilename);

apHarmony\jsHarmonyCms\CmsPage 类

公共属性

CmsPage->seo

(CmsPageSeo)

包含页面 SEO 相关属性的类实例

CmsPage->seo->title

(string)

用于 <title> 标签的页面内容

CmsPage->seo->keywords

(string)

用于 <meta name="keywords" content="..." /> 标签的页面内容

CmsPage->seo->metadesc

(string)

用于 <meta name="description" content="..." /> 标签的页面内容

CmsPage->seo->canonical_url

(string)

用于 <link rel="canonical" href="..." /> 标签的页面内容

CmsPage->css

(string)

用于 <style type="text/css"> 标签的页面内容

CmsPage->js

(string)

用于 <script type="javascript"> 标签的页面内容

CmsPage->header

(string)

要附加到 <head> 标签的 HTML 内容

CmsPage->footer

(string)

要附加到 <body> 标签末尾的 HTML 内容

CmsPage->title

(string)

要添加到 <h1> 标签中的 HTML 内容

CmsPage->page_template_id

(string)

此页面使用的 CMS 页面模板名称

CmsPage->content

(CmsPageDictionary)

此页面的内容数组，按内容元素 ID 索引

示例

echo $page->content->body;
echo $page->content->sidebar;

如果未定义内容区域，其值将为空字符串。

CmsPage->properties

(CmsPageDictionary)

此页面的属性值数组，按属性名称索引

示例

if($page->properties->showTitle != 'N'){
  echo '<title>'.htmlspecialchars($page->title).'</title>';
}

如果未定义属性，其值将为空字符串。

CmsPage->isInEditor

(bool)

如果页面被检测到是通过CMS打开的，则为True。

CmsPage->editorScript

(string)

如果页面是通过CMS打开的，则用于启动CMS编辑器的脚本标签。否则，为空字符串。

CmsPage->notFound

(bool)

当页面内容应该被渲染但没有找到匹配的内容时（不在CMS编辑器模式下），由CmsRouter->getStandalone设置为true。

公共方法

CmsPage::fromArray

CmsPage::fromArray($data)

从JSON数据生成CmsPage对象

参数

$data (array) CMS JSON页面内容

返回值

(CmsPage) 页面

示例

$page = CmsPage::fromArray([
  'title'=>'Welcome',
  'content'=>['body'=>'Hello World']
]);

apHarmony\jsHarmonyCms\CmsResponse 类

CmsResponse构造函数

new CmsResponse($type)

参数

$type (string) 响应类型 - 'page'或'redirect'

示例

$response = new CmsResponse('page');

公共属性

CmsResponse->type

(string|null)

响应类型 - 'page'或'redirect'

CmsResponse->filename

(string|null)

如果响应类型是"page"，则页面文件名

CmsResponse->redirect

(CmsRedirect|null)

如果响应类型是"redirect"，则重定向

apHarmony\jsHarmonyCms\CmsPassthruResponse 类

公共属性

CmsPassthruResponse->http_code

(int|null)

目标passthru页面的HTTP响应代码

CmsPassthruResponse->content_type

(string|null)

目标passthru页面的HTTP内容类型

CmsPassthruResponse->content

(string|null)

目标passthru页面的HTML内容

公共方法

CmsPassthruResponse->serve

CmsPassthruResponse->serve()

将passthru内容服务给用户

参数

N/A

示例

$cmsRouter->passthru('https://example.com')->serve();

apHarmony\jsHarmonyCms\CmsRedirect 类

CmsRedirect构造函数

new CmsRedirect($http_code, $url)

参数

$http_code (string) HTTP代码('301', '302'或'PASSTHRU')
$url (string) 目标URL

示例

$redirect = new CmsRedirect('301', 'https://example.com');

公共属性

CmsRedirect->http_code

(string|null)

HTTP代码('301', '302'或'PASSTHRU')

CmsRedirect->url

(string|null)

目标URL

jsHarmonyCmsEditor类（客户端JS）

jsHarmonyCmsEditor构造函数

jsHarmonyCmsEditor(config)

参数

config (Object) :: 包含以下一个或多个配置键的对象

{
  access_keys: [],
  //Array(string) CMS Editor Access Keys, used to validate remote CMS URL
}

示例

//Load the CMS Editor in this page
jsHarmonyCmsEditor({ access_keys: ['*****ACCESS_KEY*****'] });

apharmony/ jsharmony-cms-sdk-php

维护者

详细信息

README

安装

API 文档

apHarmony\jsHarmonyCms\CmsRouter 类

apHarmony\jsHarmonyCms\CmsPage 类

apHarmony\jsHarmonyCms\CmsResponse 类

apHarmony\jsHarmonyCms\CmsPassthruResponse 类

apHarmony\jsHarmonyCms\CmsRedirect 类

jsHarmonyCmsEditor 类 (客户端 JS)

apHarmony\jsHarmonyCms\CmsRouter 类

CmsRouter 构造函数

参数

示例

公共属性

CmsRouter->config

公共方法

CmsRouter->serve

参数

返回值

示例

CmsRouter->getStandalone

参数

返回值

示例

CmsRouter->getPlaceholder

参数

返回值

示例

CmsRouter->isInEditor

参数

返回值

示例

CmsRouter->resolve

参数

返回值

示例

CmsRouter->route

参数

返回值

示例

CmsRouter->matchRedirect

参数

返回值

示例

CmsRouter->getRedirectData

返回值

示例

CmsRouter->getEditorScript

参数

返回值

安全

示例

CmsRouter->serveFile

参数

示例

CmsRouter->redirect301

参数

示例

CmsRouter->redirect302

参数

示例

CmsRouter->passthru

参数

返回值

示例

CmsRouter->generate404

参数

示例

CmsRouter->generateError

参数

示例

CmsRouter->getPage

参数

返回值

示例

CmsRouter->getPageFromFile

参数