PhalApi2.x笔记

PhalApi 2.x 版本的安装很简单，有两种方式

安装Composer

有两种方法安装

如果还没有安装 Composer，在 Linux 和 Mac OS X 中可以运行如下命令：

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

在 Windows 中，你需要下载并运行 Composer-Setup.exe。
如果遇到任何问题或者想更深入地学习 Composer，请参考 Composer 文档（英文），Composer 中文。

由于众所周知的原因，国外的网站连接速度很慢。因此安装的时间可能会比较长，我们建议通过下面的方式使用国内镜像。

打开命令行窗口（windows用户）或控制台（Linux、Mac 用户）并执行如下命令：

composer config -g repo.packagist composer https://packagist.phpcomposer.com

注意：最近phpcomposer镜像存在问题，可以改成

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/  

如果你是第一次安装的话，在命令行下面，切换到你的WEB根目录下面并执行下面的命令：

composer create-project topthink/think=5.1.* tp5

这里的tp5目录名你可以任意更改，执行完毕后，会在当前目录下的tp5子目录安装最新版本的ThinkPHP，这个目录就是我们后面会经常提到的应用根目录。

如果你之前已经安装过，那么切换到你的应用根目录下面，然后执行下面的命令进行更新：

composer update topthink/framework

更新操作会删除thinkphp目录重新下载安装新版本，但不会影响application目录，因此不要在核心框架目录添加任何应用代码和类库。

安装和更新命令所在的目录是不同的，更新必须在你的应用根目录下面执行

如果出现错误提示，请根据提示操作或者参考Composer中文文档。

一般情况下，composer 安装的是最新的稳定版本，不一定是最新版本，如果你需要安装实时更新的版本（适合学习过程），可以安装5.1.x-dev版本。

composer create-project topthink/think=5.1.x-dev tp5

温馨提示：关于composer的使用，请参考Composer 中文网 / Packagist 中国全量镜像。

如何升级PhalApi 2.x框架？

在composer的管理下，升级PhalApi 2.x 版本系列非常简单。只需要修改composer.json文件，指定相应的版本即可。PhalApi的框架内核项目在phalapi/kernal，你可以指定版本，也可以跟随最新版本。

例如，当需要指定PhalApi 2.0.1版本时，可以这样配置：

{
    "require": {
        "phalapi/kernal": "2.0.1"
    }
}

当需要保持最新版本时，则可以改成：

{
    "require": {
        "phalapi/kernal": "2.*.*"
    }
}

这样，当PhalApi 2.x 有版本更新时，只需执行composer更新操作即可。对应命令操作为：

$ composer update

至此，升级完毕！

温馨提示：关于composer版本的说明，可参考Composer中文文档 - 包版本。

配置

Nginx配置

如果使用的是Nginx，可参考以下配置。

server {
    listen 80;
    server_name dev.phalapi.net;
    root /path/to/phalapi/public;
    charset utf-8;

    location / {
        index index.php;
    }

    # 开启URI路由匹配
    # location / {
    #       try_files $uri $uri/ /?$args;
    # }
    # if (!-e $request_filename) {
    #        rewrite ^/(.*)$ /index.php last;
    # }

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass 127.0.0.1:9000;
        #fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock; # 根据需要选择配置
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    access_log logs/dev.phalapi.net.access.log;
    error_log logs/dev.phalapi.net.error.log;
}

重启Nginx并配置本地HOSTS后，可通过以下链接，访问默认接口服务。

http://dev.phalapi.net

温馨提示：推荐将访问根路径指向/path/to/phalapi/public。后续开发文档中，如无特殊说明，均约定采用此配置方式。

Apache配置

如果使用的是Apache，可参考以下配置。目录结构：

htdocs
├── phalapi
└── .htaccess

.htaccess内容：

<IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteBase /

    RewriteCond %{HTTP_HOST} ^dev.phalapi.net$

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    RewriteCond %{REQUEST_URI} !^/phalapi/public/
    RewriteRule ^(.*)$ /phalapi/public/$1
    RewriteRule ^(/)?$ index.php [L]
</IfModule>

XAMPP配置

如果使用的是XAMPP集成环境，只需要将项目源代码phalapi整个目录复制到xampp的htdocs目录下即可。打开XAMPP控制面板并启动Apache后，便可通过以下链接，访问默认接口服务。

http://localhost/phalapi/public/

以上不管何种配置，正常情况下，访问默认接口服务可以看到类似这样的输出：

{
    "ret": 200,
    "data": {
        "title": "Hello PhalApi",
        "version": "2.0.1",
        "time": 1501079142
    },
    "msg": ""
}

运行效果，截图如下：

至此，安装完毕！

编写一个接口

在PhalApi 2.x 版本中，项目源代码放置在/path/to/PhalApi2/src目录中。里面各个命名空间对应一个子目录，默认命名空间是app，里面主要有Api、Domain、Model这三个目录以及存放函数的functions.php文件。例如像是这样的目录结构：

./src/
└── app
    ├── Api # 放置接口源代码，相当于控制器层
    ├── Common # 公共代码目录，放置工具等
    ├── Domain # 领域业务层，负责业务逻辑和处理
    ├── functions.php
    └── Model # 数据源层，负责数据持久化存储及操作

当需要新增一个接口时，先要在Api层添加一个新的接口文件。例如对于Hello World示例，可以使用你喜欢的编辑器创建一个./src/app/Api/Hello.php文件，并在里面放置以下代码。

// 文件 ./src/app/Api/Hello.php
 <?php
 namespace App\Api;
 
 use PhalApi\Api;
 
 /**
  * 第一个接口
  */
 class Hello extends Api {
 
     public function getRules() {
         return array(
             'world' => array(
                 'username' => array('name' => 'username', 'desc' => 'B站账号名称'),
             ),
         );
     }
 
     /**
      * 接口名称-欢迎B站
      * @desc 欢迎B站的同学，bilibili!!
      */
     public function world() {
         return array('content' => 'Hello ' . $this->username);
     }
 }

编写接口时，需要特别注意：

• 1、默认所在命名空间必须为App\Api (第2行)

• 2、具体实现的接口类必须是PhalApi\Api的子类 （第4行、第9行）

• 3、定义接口方法，必须为public访问权限 （第23行）

• 4、接口参数，放置在getRules()函数方法中 （第11行）

• 5、返回业务的数据，对应data返回字段，推荐返回对象结构，方便扩展 （第24行）

• 访问一个接口

  通常情况下，建议可访问的根路径设为/path/to/PhalApi2/public。若未设置根目录为public目录，此时接口访问的URL格式为：接口域名/public/?s=Namespace.Class.Action。其中，s参数用于指定待请求的接口服务，由三部分组成。分别是：

组成部分	是否必须	默认值	说明
Namespace	可选	App	Api命名空间前缀，多级命名空间时用下划线分割，缺省命名空间为App
Class	必须	无	待请求的接口类名，通常首字母大写，多个目录时用下划线分割
Action	必须	无	待请求的接口类方法名，通常首字母大写。若Class和Action均未指定时，默认为Site.Index

温馨提示：s参数为service参数的缩写，即使用?s=Class.Action等效于?service=Class.Action，两者都存在时优先使用service参数。

例如，上面新增的Hello World接口的访问链接为：

http://dev.phalapi.net/?s=Hello.World

或者可以使用完整的写法，带上命名空间App：

http://dev.phalapi.net/?s=App.Hello.World

例如：

http://localhost/phalapi/public/index.php
return:
{
    "ret": 200,
    "data": {
        "title": "Hello PhalApi",
        "version": "2.17.1",
        "time": 1621092716
    },
    "msg": ""
}
http://127.0.0.1/phalapi/public/index.php?s=App.Hello.World
return:
{
    "ret": 200,
    "data": {
        "content": "Hello "
    },
    "msg": ""
}

接口返回

默认情况下，接口的结果以JSON格式返回，并且返回的顶级字段有状态码ret、业务数据data，和错误提示信息msg。其中data字段对应接口类方法返回的结果。如Hello Wolrd示例中，返回的结果是：

{"ret":200,"data":{"title":"Hello World!"},"msg":""}

JSON可视化后是：

{
    "ret": 200,
    "data": {
        "title": "Hello World!"
    },
    "msg": ""
}

恭喜！你已顺便完成PhalApi 2.x 简单的接口开发了！

为了方便，可以选择配置域名