PIO API 規格

規格版本

Version 0.6 : 2008/04/07 by scribe
Version 0.5 : 2007/10/13 by scribe & RT
Version 0.4 : 2007/06/05 by scribe
Version 0.3 : 2006/12/03 by scribe
Version 0.2 : 2006/10/27 by scribe
Version 0.1 : 2006/07/04 by RT

方法一覽

PIO 版本相關

  • pioVersion : 取得 PIO 模組版本資訊

資料來源操作相關

  • dbConnect : 分析連線字串並配置連接相關參數
  • dbInit : 初始化資料來源
  • dbPrepare : 連接資料來源
  • dbCommit : 提交操作結果
  • dbOptimize : 最佳化資料來源

匯入匯出相關

  • dbImport : 匯入資料來源
  • dbExport : 匯出資料來源

文章全域相關

  • postCount : 取得文章總數目
  • threadCount : 取得討論串總數目
  • getLastPostNo : 取得文章最後序列編號

文章取得相關

  • fetchPostList : 取得文章編號列表
  • fetchThreadList : 取得討論串編號列表
  • fetchPosts : 取得指定編號文章內容陣列結構

文章刪除相關

  • delOldAttachments : 取得舊附加圖檔及預覽圖列表 (或旗標)
  • removePosts : 刪除指定編號文章
  • removeAttachments : 取得指定編號附加圖檔及預覽圖列表

文章新增相關

  • addPost : 新增文章 (Changed on 0.5)

文章檢查相關

  • isSuccessivePost : 檢查文章是否重複張貼
  • isDuplicateAttachment : 檢查圖檔是否重複張貼
  • isThread : 檢查指定編號文章是否為討論串首篇

文章搜尋相關

  • searchPost : 以關鍵字搜尋文章
  • searchCategory : 以類別標籤搜尋文章

文章屬性相關

  • getPostStatus : 取得文章屬性 (Changed on 0.5)
  • setPostStatus : 設定指定編號文章屬性 (Changed on 0.5)

方法細節

pioVersion

string pioVersion()

單純傳回 PIO 模組版本資訊,即其版本號碼。

回傳值: 版本資訊字串

dbConnect

void dbConnect(string $connStr)

將傳入的連線字串切割分析後存入變數、設定連接環境。

參數:
$connStr - PIO 連線字串

dbInit

void dbInit()

將資料來源作配置、初始化動作。 (如新增儲存資料檔、配置資料表等)

dbPrepare

void dbPrepare(bool $reload=false, bool $transaction=false)

連接資料來源並準備使用。

參數:
$reload - 是否強制重新連接
$transaction - 是否使用交易模式

dbCommit

void dbCommit()

提交在交易模式中所做的操作結果。

dbOptimize

bool dbOptimize(bool $doit=false)

對資料來源作最佳化的動作。如果 $doit 沒有設定為 true 則是詢問 PIO 此資料來源是否支援最佳化。

參數:
$doit - 是否進行最佳化動作
回傳值: 是否成功最佳化

dbImport

bool dbImport(string $data)

匯入資料來源。分析從其他資料來源匯出的中介檔案並匯入目前的資料來源內。

參數:
$data - 中介檔案格式資料
回傳值: 是否匯入成功

dbExport

string dbExport()

匯出資料來源。把目前的資料來源輸出成中介檔案格式。

回傳值: 匯出的中介檔案格式資料

postCount

int postCount(int $resno=0)

取得目前文章的總數目。如果 $resno 有指定則是取得指定編號討論串的文章 (首篇+回應) 的總數目。

參數:
$resno - 指定編號討論串
回傳值: 文章總數目

threadCount

int threadCount()

取得目前討論串總數目。

回傳值: 討論串總數目

getLastPostNo

int getLastPostNo(string $state)

取得目前文章序列編號的最後號碼。假如目前 No.4096 是最後一個號碼,就傳回 4096。而 $state 是送出文章後最後編號會更動的時機 (送交前、送交後)。
註: 時機分開的原因是儲存新文章時 SQL-like 系並不需要 beforeCommit 這一運算取得最後號碼而會自動累加,但 Log 需要,為了節省 SQL-like 運算特此分開。
故 SQL-like 傳入 beforeCommit 後回傳的值並無意義

參數:
$state - 時機,有 "beforeCommit" 和 "afterCommit" 兩種可用
回傳值: 文章序列編號的最後號碼

fetchPostList

array fetchPostList(int $resno=0, int $start=0, int $amount=0)

取得文章編號列表。如果 $resno 有指定的話則是取得討論串的所有文章之編號 (首篇+回應),此時後兩個參數自動忽略。 $start 和 $amount 參數是用來取得片段列表 (即分頁動作),如果沒有指定則是取得所有文章編號 (依編號排序,由大排到小)。

參數:
$resno - 指定編號討論串 (如設定後兩個參數將自動忽略)
$start - 起始位置 (將列表視為陣列,第 1 個為 0)
$amount - 取得數目 (假如 $amount 大於可取數目,則只回傳可取數目)
回傳值: 文章編號陣列 (ex: array(1, 2, 3, 4, 5, 6))

fetchThreadList

array fetchThreadList(int $start=0, int $amount=0, bool $isDESC=false)

取得討論串編號列表。與 fetchPostList 不同處在於此方法只會挑選討論串首篇文章編號 (預設依最後更新時間排序)。也有 $start 和 $amount 參數可做分頁動作 (先排序才分頁切割)。

參數:
$start - 起始位置 (將列表視為陣列,第 1 個為 0)
$amount - 取得數目 (假如 $amount 大於可取數目,則只回傳可取數目)
$isDESC - 是否將討論串列表以遞減方式排序。預設是利用最後更新時間排序再做處理,這邊可以更改其預設行為
回傳值: 討論串首篇編號陣列 (ex: array(2, 7, 3, 4, 1))

fetchPosts

array fetchPosts(array $postlist)
array fetchPosts(int $postlist)

取得指定編號之文章內容陣列結構。 $postlist 接受數字陣列和單一數字形式。

參數:
$postlist - 指定之文章編號,可以是單一數字 (如 15) 或是數字陣列 (如 array(12, 15))
回傳值: 指定編號之文章內容陣列結構,先以 [0], [1] 區分各文章,而其下才是各文章內容結構

文章內容結構:
Array(
['no'] => 文章編號
['resto'] => 文章回應對象編號 (如本身為首篇則為 0)
['md5chksum'] => 附加圖檔之 MD5
['category'] => 文章類別標籤
['tim'] => 附加圖檔檔名
['ext'] => 附加圖檔副檔名
['imgw'] => 附加圖檔寬度
['imgh'] => 附加圖檔高度
['imgsize'] => 附加圖檔檔案大小
['tw'] => 附加圖檔預覽圖寬度
['th'] => 附加圖檔預覽圖高度
['pwd'] => 文章刪除密碼 (已經過編碼並截斷,比對用)
['now'] => 文章發文時間資訊
['name'] => 發文者名稱
['email'] => 發文者 E-mail
['sub'] => 文章標題
['com'] => 文章內文
['host'] => 發文者使用電腦之 Hostname (IP 反解)
['status'] => 文章狀態旗標
)

delOldAttachments

array delOldAttachments(int $total_size, int $storage_max, bool $warnOnly=true)

取得舊附加圖檔及預覽圖列表 (或旗標)。如果 $warnOnly 設定為 true,回傳則是某某編號附加圖檔過舊的旗標。

參數:
$total_size - 目前附加圖檔總容量大小
$storage_max - 限制之附加圖檔最大容量大小
$warnOnly - 是否僅取得警告旗標
回傳值: 將被刪除之附加圖檔及預覽圖之列表陣列
($warnOnly = true) 過舊附加圖檔旗標 (ex: array([24] => 1, [58] => 1))

removePosts

array removePosts(array $posts)

刪除指定編號文章。注意到如果刪除討論串首篇,則其回應也會一併被刪除。

參數:
$posts - 指定之文章編號
回傳值: 將被刪除之附加圖檔及預覽圖之列表陣列

removeAttachments

array removeAttachments(array $posts)

取得指定編號附加圖檔及預覽圖列表。

參數:
$posts - 指定之文章編號
回傳值: 將被刪除之附加圖檔及預覽圖之列表陣列

addPost

public void addPost(…)

新增一筆文章。

參數:
$no - 新文章編號
$resto - 新文章回應對象編號。假如不是回應而是首篇,此值為 0
$md5chksum - 新文章附加圖檔之 MD5 Hash
$category - 新文章之類別標籤
$tim - 新文章發文 Unix 時間撮記 + 毫秒 (共 13 位元)
$ext - 新文章附加圖檔之副檔名
$imgw - 新文章附加圖檔之寬度
$imgh - 新文章附加圖檔之高度
$imgsize - 新文章附加圖檔之檔案大小
$tw - 新文章附加圖檔預覽圖之寬度
$th - 新文章附加圖檔預覽圖之高度
$pwd - 新文章刪除密碼
$now - 新文章時間字串 (含 ID 識別)
$name - 新文章發文者名稱
$email - 新文章發文者 E-mail
$sub - 新文章標題
$com - 新文章內文
$host - 新文章發文者連線主機名稱
$age - 新文章是否使討論串推文 ($resto 有設定時有效)
$status - 新文章狀態旗標

isSuccessivePost

bool isSuccessivePost(int $lcount, string $com, int $timestamp, string $pass, string $passcookie, string $host, bool $isupload)

檢查文章是否重複張貼。判斷的標準為內文、時間、密碼及主機名稱。

參數:
$lcount - 檢查數目,設定越大檢查越多筆文章
$com - 發文之內文
$timestamp - 發文 Unix 時間撮記
$pass - 發文者填入的密碼
$passcookie - 發文者 Cookie 儲存的密碼
$host - 發文者主機名稱
$isupload - 是否有上傳圖檔行為
回傳值: 是否有重複張貼文章

isDuplicateAttachment

bool isDuplicateAttachment(int $lcount, string $md5hash)

檢查圖檔是否重複張貼。判斷的標準是看圖片的 MD5 是否已存在。

參數:
$lcount - 檢查數目,設定越大檢查越多筆文章
$md5hash - 欲檢查圖片的 MD5 Hash 碼
回傳值: 是否已存在相同的圖片

isThread

bool isThread(int $no)

檢查指定編號文章是否為討論串首篇。

參數:
$no - 欲檢查的文章編號
回傳值: 是否為討論串首篇 (即討論串是否存在)

searchPost

array searchPost(array $keyword, string $field, string $method)

以關鍵字搜尋特定欄位以取得相符的文章。

參數:
$keyword - 搜尋的關鍵字陣列
$field - 搜尋的文章欄位,可以是 com, name, sub, no 等欄位
$method - 關鍵字搜尋的方法,有 "AND" (交集) 和 "OR" (聯集) 兩種方式
回傳值: 搜尋相符的文章內容陣列結構

searchCategory

array searchCategory(string $category)

以類別標籤搜尋相符的文章。

參數:
$catalog - 搜尋的類別標籤文字
回傳值: 含此類別標籤的文章內容陣列結構

getPostStatus

FlagHelper getPostStatus(string $status)

將狀態以 FlagHelper 包裹方便處理。此物件提供各種方法方便修改狀態旗標。

參數:
$status - 舊狀態旗標值
回傳值: 此狀態的 FlagHelper 物件 (請參照 FlagHelper API)

updatePost

void updatePost(int $no, array $newValues)

更新指定編號文章的各欄位儲存值。簡言之可以做到修改文章內容的功能。

參數:
$no - 欲更新的文章編號
$newValues - 新欄位值陣列 (ex: array('name' => 'Anonymous', 'email'=> 'sage'))

setPostStatus

void setPostStatus(int $no, string $newStatus)

設定指定編號文章的狀態旗標,實際上使用了 updatePost 進行操作。此方法的存在是作為方便修改狀態旗標的。

參數:
$no - 欲設定的文章編號
$newStatus - 新狀態旗標值,直接取代原有旗標更新成傳入參數

參見

除非特別註明,本頁內容採用以下授權方式: Creative Commons Attribution-Noncommercial-Share Alike 2.5 License.