README

phpAPI - [已弃用] - 请使用 coreAPI 代替

功能

• REST API

你可能为什么需要它

如果你正在寻找一个简单的PHP REST API的开始，那么这个PHP类就是为你准备的。

我能使用这个吗？

当然可以！

许可证

本软件根据GNU通用公共许可证v3.0许可证进行分发。请阅读LICENSE，了解软件可用性和分发信息。

需求

• PHP >= 8.0
• MySQL或MariaDB

安全

请负责任地披露发现的任何漏洞 - 私下向维护者报告安全问题。

安装

使用Composer

composer require laswitchtech/php-api

如何使用它？

在本文档中，我们将使用名为users的表作为示例。

骨架

让我们从API项目目录的骨架开始。

├── api.php
├── config
│   └── api.cfg
├── Controller
│   └── UserController.php
└── Model
    └── UserModel.php

• api.php：api文件是应用程序的入口点。它将初始化应用程序中调用的控制器。
• config/api.cfg：配置文件包含API的配置信息。主要，它将包含数据库凭据。但您也可以用它来存储其他配置。
• Controller/：此目录将包含所有控制器。
• Controller/UserController.php：用户控制器文件包含处理REST API调用所需的必要应用程序代码。主要是可以调用的方法。
• Model/：此目录将包含所有模型。
• Model/UserModel.php：用户模型文件实现与MySQL数据库中用户表交互所需的必要方法。

模型

模型文件实现与MySQL数据库中表交互所需的必要方法。这些模型文件需要扩展Database类才能访问数据库。

命名约定

您的模型文件名称应以下划线开头，后跟Model.php。如果不这样，则引导程序将不会加载它。Model文件中的类名应与模型文件名称匹配。

示例

//Import BaseModel class into the global namespace
use LaswitchTech\phpAPI\BaseModel;

class UserModel extends BaseModel {
  public function getUsers($limit) {
    return $this->select("SELECT * FROM users ORDER BY id ASC LIMIT ?", ["i", $limit]);
  }
}

控制器

控制器文件包含处理REST API调用所需的必要应用程序代码。主要是可以调用的方法。这些控制器文件需要扩展BaseController类才能访问基本方法。

命名约定

您的控制器文件名称应以下划线开头，后跟Controller.php。如果不这样，则引导程序将不会加载它。Controller文件中的类名应与控制器文件名称匹配。

最后，可调用方法需要以Action结尾。

示例

//Import BaseController class into the global namespace
use LaswitchTech\phpAPI\BaseController;

class UserController extends BaseController {

  public function __construct($Auth){

    // Set the controller Authentication Policy
    $this->Public = true; // Set to false to require authentication

    // Set the controller Authorization Policy
    $this->Permission = false; // Set to true to require a permission for the namespace used. Ex: namespace>/user/list
    $this->Level = 1; // Set the permission level required

    // Call the parent constructor
    parent::__construct($Auth);
  }

  public function listAction() {
    try {

      // Namespace: /user/list

      // Check the request method
      if($this->Method !== 'GET'){
        throw new Error('Invalid request method.');
      }

      // Initialize the user model
      $UserModel = new UserModel();

      // Configure default limit
      $Limit = 25;

      // Check if the limit is set
      if($this->getQueryStringParams('limit')){
        $Limit = intval($this->getQueryStringParams('limit'));
      }

      // Get the users
      $Users = $UserModel->getUsers($Limit);

      // Check if the users were found
      if(count($Users) <= 0){
        throw new Error('Users not found.');
      }

      // Send the output
      $this->output(
        $Users,
        array('Content-Type: application/json', 'HTTP/1.1 200 OK')
      );
    } catch (Error $e) {

      // Set the error
      $this->Error = $e->getMessage();

      // Log the error
      $this->Logger->error($e->getMessage());

      // Send the output
      $this->output(
        array('error' => $this->Error . ' - Something went wrong! Please contact support.'),
        array('Content-Type: application/json', 'HTTP/1.1 500 Internal Server Error'),
      );
    }
  }
}

配置

配置文件包含API的配置信息。主要，它将包含数据库凭据。但您也可以用它来存储其他配置。配置文件必须存储在config/config.php中。因为这个文件已经在引导程序中加载。

示例

{
    "sql": {
        "host": "localhost",
        "database": "demo3",
        "username": "demo",
        "password": "demo"
    }
}

API

api文件是应用程序的入口点。它将初始化应用程序中调用的控制器。该文件本身可以命名为任何您想要的名称。只要您将API调用指向它即可。在我们的示例中，我们使用api.php。这个名称很有用，因为它允许您使用index.php文件构建前端，并且也使API的URL显而易见。

示例

// Initiate Session
session_start();

// These must be at the top of your script, not inside a function
use LaswitchTech\phpAPI\phpAPI;

// Load Composer's autoloader
require 'vendor/autoload.php';

// Initiate phpAPI
new phpAPI();

调用API

一旦您设置了第一个控制器和模型，就可以开始调用您的API。

JavaScript实现

phpAPI自带JavaScript实现。该类位于/vendor/laswitchtech/php-api/dist/js/phpAPI.js。

示例

更多示例请查看示例文件夹。

安装器示例

// Initiate Session
session_start();

// These must be at the top of your script, not inside a function
use LaswitchTech\phpLogger\phpLogger;
use LaswitchTech\phpSMS\phpSMS;
use LaswitchTech\SMTP\phpSMTP;
use LaswitchTech\phpDB\Database;
use LaswitchTech\phpAUTH\phpAUTH;

// Load Composer's autoloader
require 'vendor/autoload.php';

// Initiate phpLogger
$phpLogger = new phpLogger();

// Configure phpLogger
$phpLogger->config("level",0); // Set Logging Level

// Initiate phpSMS
$phpSMS = new phpSMS();

// Configure phpSMS
$phpSMS->config('provider','twilio')
       ->config('sid', 'your_account_sid')
       ->config('token', 'your_auth_token')
       ->config('phone', 'your_twilio_phone_number');

// Initiate phpDB
$phpDB = new Database();

// Configure phpDB
$phpDB->config("host","localhost")
      ->config("username","demo")
      ->config("password","demo")
      ->config("database","demo3");

// Initiate phpSMTP
$phpSMTP = new phpSMTP();

// Configure phpSMTP
$phpSMTP->config("username","username@domain.com")
        ->config("password","*******************")
        ->config("host","smtp.domain.com")
        ->config("port",465)
        ->config("encryption","ssl");

// Construct Hostnames
$Hostnames = ["localhost","::1","127.0.0.1"];
if(isset($_SERVER['SERVER_NAME']) && !in_array($_SERVER['SERVER_NAME'],$Hostnames)){
  $Hostnames[] = $_SERVER['SERVER_NAME'];
}
if(isset($_SERVER['HTTP_HOST']) && !in_array($_SERVER['HTTP_HOST'],$Hostnames)){
  $Hostnames[] = $_SERVER['HTTP_HOST'];
}

// Initiate phpAUTH
$phpAUTH = new phpAUTH();

// Configure phpAUTH
$phpAUTH->config("hostnames",$Hostnames)
        ->config("basic",false) // Enable/Disable Basic Authentication
        ->config("bearer",true) // Enable/Disable Bearer Token Authentication
        ->config("request",false) // Enable/Disable Request Authentication
        ->config("cookie",false) // Enable/Disable Cookie Authentication
        ->config("session",false) // Enable/Disable Session Authentication
        ->config("2fa",false) // Enable/Disable 2-Factor Authentication
        ->config("maxAttempts",5) // Max amount of authentication attempts per windowAttempts
        ->config("maxRequests",1000) // Max amount of API request per windowRequests
        ->config("lockoutDuration",1800) // 30 mins
        ->config("windowAttempts",100) // 100 seconds
        ->config("windowRequests",60) // 60 seconds
        ->config("window2FA",60) // 60 seconds
        ->config("windowVerification",2592000) // 30 Days
        ->init();

// Install phpAUTH
$Installer = $phpAUTH->install();

// Create a User
$User = $Installer->create("api",["username" => "username@domain.com"]);

// Activate User
$User->activate();

// Verify User
$User->verify();

// Initiate phpConfigurator
$Configurator = new phpConfigurator('account');

// Save Account for Testing
$Configurator->set('account','url',"https://{$Hostname}/api.php")
             ->set('account','token',$User->get('username').":".$User->getToken());