====== Module hỗ trợ API ======

Trong tài liệu này chúng tôi ví dụ module hiện tại là module **Page** đang chuẩn bị lập trình chức năng API.

> Lưu ý: Tên module, tên file Api và tên Class phân biệt chữ hoa và chữ thường.

**Bước 1: Tạo thư mục Api để chứa các file Api**

Trong thư mục của module tạo thêm thư mục **Api**. Khi đó tồn tại đường dẫn ''modules/Page/Api''

**Bước 2: Tạo file trong thư mục Api**

Mỗi Api sẽ nằm trong một file php nằm trong thư mục Api. Tên file là tên class (phân biệt chữ viết hoa và viết thường). Ví dụ:

<file php CreatArticle.php>
<?php

/**
 * @Project NUKEVIET 4.x
 * @Author VINADES.,JSC <contact@vinades.vn>
 * @Copyright (C) 2014 VINADES ., JSC. All rights reserved
 * @License GNU/GPL version 2 or any later version
 * @Createdate Jun 20, 2010 8:59:32 PM
 */

namespace NukeViet\Module\Page\Api;

use NukeViet\Api\Api;
use NukeViet\Api\ApiResult;
use NukeViet\Api\IApi;

if (!defined('NV_ADMIN') or !defined('NV_MAINFILE')) {
    die('Stop!!!');
}

class CreatArticle implements IApi
{
    private $result;

    /**
     * @return number
     */
    public static function getAdminLev()
    {
        return Api::ADMIN_LEV_MOD;
    }

    /**
     * @return string
     */
    public static function getCat()
    {
        return 'System';
    }

    /**
     * {@inheritDoc}
     * @see \NukeViet\Api\IApi::setResultHander()
     */
    public function setResultHander(ApiResult $result)
    {
        $this->result = $result;
    }

    /**
     * {@inheritDoc}
     * @see \NukeViet\Api\IApi::execute()
     */
    public function execute()
    {
        // @TODO

        return $this->result->getResult();
    }
}

</file>

Giải thích code như sau:

===== Namespaces =====

<code php>
namespace NukeViet\Module\Page\Api;
</code>

Quy luật:

<code>
NukeViet\Module\<ModuleName>\Api
</code>

''<ModuleName>'' chính là tên module, trong ví dụ này là ''Page''.

Sau khi đặt namespace, ta khai báo sử dụng các class NukeViet Core hỗ trợ:

<code php>
use NukeViet\Api\Api;
use NukeViet\Api\ApiResult;
use NukeViet\Api\IApi;
</code>
===== Class Name =====

<code php>
class CreatArticle implements IApi
</code>

Class cần phải implements lớp IApi, theo đó phải có đủ 3 phương thức

<code php>
/**
 * Lấy được quyền hạn sử dụng của admin
 * Admin tối cao, điều hành chung hay quản lý module được sử dụng
 */
public static function getAdminLev();

/**
 * Danh mục, cũng là khóa ngôn ngữ của API
 * Nếu không có danh mục thì trả về chuỗi rỗng
 */
public static function getCat();

/**
 * Thiết lập trình xử lý kết quả
 *
 * @param ApiResult $result
 */
public function setResultHander(ApiResult $result);

/**
 * Thực thi API
 */
public function execute();
</code>

> Lưu ý: Class name chính là tên file. Ví dụ class name là CreatArticle thì file sẽ là ''module/Page/Api/CreatArticle.php''

===== Phương thức getAdminLev =====

Cho biết đối tượng được quyền sử dụng API:

<code php>
public static function getAdminLev()
{
    return Api::ADMIN_LEV_MOD;
}
</code>

Cần trả về một trong 3 giá trị:

<code php>
Api::ADMIN_LEV_GOD; // 3: Quản lý module
Api::ADMIN_LEV_SP; // 2: Điều hành chung
Api::ADMIN_LEV_MOD; // 1: Admin tối cao
</code>

===== Phương thức getCat =====

Cho biết danh mục của API nếu có, nếu API không được xếp danh mục hãy trả về chuỗi rỗng.

<code php>
public static function getCat()
{
    return 'System';
}
</code>

===== Phương thức setResultHander =====

<code php>
public function setResultHander(ApiResult $result)
{
    $this->result = $result;
}
</code>

Giữ nguyên code như mẫu, không thay đổi thêm.

===== Code thực thi Api =====

<code php>
public function execute()
{
    // Viết code thực thi tại đây

    return $this->result->getResult();
}
</code>

Code thực thi được viết tự do, và bắt buộc phải trả về thông qua phương thức ''getResult'' của class ''NukeViet\Api\ApiResult''

==== Sử dụng các dữ liệu hệ thống ====

  * Lấy biến ''$module_name'' sử dụng lệnh ''$module_name = Api::getModuleName();''
  * Lấy biến ''$module_info'' sử dụng lệnh ''$module_name = Api::getModuleInfo();''. Các biến ''$module_data, $module_file, $module_upload'' xác định từ ''$module_info''.
  * Lấy ID của Admin thực hiện API sử dụng lệnh ''$admin_id = Api::getAdminName();''
  * Lấy Username của Admin thực hiện API sử dụng lệnh ''$admin_username = Api::getAdminId();''
  * Lấy Cấp bậc của Admin thực hiện API sử dụng lệnh ''$admin_level = Api::getAdminLev();''
  * Các biến hệ thống như ''$nv_Lang, $nv_Request, $db, $nv_Cache, ...'' có thể gọi global như thông thường.

==== Cách trả dữ liệu về ====

Message thông báo:

<code php>
$this->result->setMessage($nv_Lang->getModule('empty_bodytext'));
</code>

Mã lỗi (nếu có):

<code php>
$this->result->setCode($code);
</code>

Đánh dấu thành công:

<code php>
$this->result->setSuccess();
</code>

Đánh dấu lỗi:

<code php>
$this->result->setError();
</code>

Các dữ liệu khác:

<code php>
$this->result->set($key, $value);
</code>