dingo/api中文文档

https://laravel-china.org/docs/dingo-api/2.0.0

----------------------------------lesson 1----------------------------------
建立项目：laravel new zhihu

新建数据库,名为zhiwu

修改.env数据库连接配置:
DB_HOST=localhost
DB_PORT=33060
DB_DATABASE=zhihu
DB_USERNAME=homestead
DB_PASSWORD=secret

修改Homestead.yaml文件，添加站点配置(冒号后面有空格，否则启动出错）
   - map: www.zhihu.pc
     to: /home/vagrant/hurong/zhihu/public

修改host文件：
192.168.10.10     www.zhihu.pc

重启vagrant:
vagrant provision

浏览器中检查是否能访问：http://www.zhihu.pc/

修改database/migrations下的create_users_table:
   public function up()
   {
       Schema::create('users', function (Blueprint $table) {
           $table->increments('id');
           $table->string('name')->unique();
           $table->string('email')->unique();
           $table->string('password');
           $table->string('avatar')->comment('头像');
           $table->string('confirmation_token')->comment('邮箱验证token');
           $table->integer('is_active',false,true)->default(0)->comment('邮箱是否激活');
           $table->integer('questions_count',false,true)->default(0)->comment('问题数');
           $table->integer('answers_count',false,true)->default(0)->comment('回答数');
           $table->integer('comments_count',false,true)->default(0)->comment('评论数');
           $table->integer('favorites_count',false,true)->default(0)->comment('收藏数');
           $table->integer('likes_count',false,true)->default(0)->comment('点赞数');
           $table->integer('followers_count',false,true)->default(0)->comment('关注数');
           $table->integer('followings_count',false,true)->default(0)->comment('被关注数,粉丝数');
           $table->text('setting')->nullable()->comment('用户设置');
           $table->rememberToken();
           $table->timestamps();
       });
   }

进入homestead对应zhihu目录下执行：
php artisan migrate
在数据库中查看表是否建立成功

原文地址：http://www.hu-rong.com/Article/view/id/285.html

----------------------------lesson2----------------------------
先将项目composer镜像改为中国：
修改当前项目的 composer.json 配置文件：

打开命令行窗口（windows用户）或控制台（Linux、Mac 用户），进入你的项目的根目录（也就是 composer.json 文件所在目录），执行如下命令：

复制
composer config repo.packagist composer https://packagist.phpcomposer.com

安装：laravel-SendCloud
https://packagist.org/packages/naux/sendcloud
composer require naux/sendcloud
配置：https://github.com/NauxLiu/Laravel-SendCloud
需要去注册一个帐号：sendcloud.sohu.com
注册信息：
http://www.sendcloud.net/email/#/welcome

安装：guzzlehttp/guzzle
https://packagist.org/packages/guzzlehttp/guzzle
composer require guzzlehttp/guzzle

生成认证（注册、登录等）：
http://d.laravel-china.org/docs/5.4/authentication


---------------------------安装ide-helper------------------------------------
https://packagist.org/packages/barryvdh/laravel-ide-helper
安装Laravel-Ide-Helper
   laravel-ide-helper能为IDE提供代码自动提示。
   在命令控制台，将目录切换到项目目录，然后执行下列命令：
   E:
   cd code
   cd jit
   composer require barryvdh/laravel-ide-helper
   此命令将安装laravel-ide-helper到项目中

   安装完成后，需要配置。
   打开config/app.php文件，在provider数组下添加如下代码：
   BarryvdhLaravelIdeHelperIdeHelperServiceProvider::class,

   修改项目composer.json文件的如下部分，一遍每次update后自动生成ide-helper
   "scripts":{
       "post-update-cmd": [
           "IlluminateFoundationComposerScripts::postUpdate",
           "php artisan clear-compiled",
           "php artisan ide-helper:generate",
           "php artisan ide-helper:meta",
           "php artisan optimize"
       ]
   },

   执行如下命令，生成ide-helper配置文件
   php artisan vendor:publish --provider="BarryvdhLaravelIdeHelperIdeHelperServiceProvider" --tag=config
   此命令将生成config/ide-helper.php配置文件，

   配置文件生成后，将如下配置项改为true，一遍为链式调用生成代码提示：
   'include_fluent' => true,

   执行如下命令来生成代码提示文档：
   php artisan ide-helper:generate
   php artisan ide-helper:meta

   为了能够生成模型代码提示，需要安装如下包：
   composer require doctrine/dbal

   然后可执行如下命令生成模型代码提示(注意：如果表中字段有json类型会报错，mysql版本问题）：
   php artisan ide-helper:models

   或者可指定为某一个模型生成代码提示：
   php artisan ide-helper:models 模型名

   每次增加了新的包，记得运行一下这几个php artisan命令；
---------------------------------------------------------------------------
三、安装jwt-auth
   https://github.com/tymondesigns/jwt-auth/wiki/Installation
   本项目使用jwt-auth实现Json Web Token认证模式。

   1、安装jwt-auth
   composer require tymon/jwt-auth

   在config/app.php配置文件的providers数组中加入：
   TymonJWTAuthProvidersJWTAuthServiceProvider::class,

   在aliases数组中加入：
   'JWTAuth' => TymonJWTAuthFacadesJWTAuth::class,
   'JWTFactory' => TymonJWTAuthFacadesJWTFactory::class,

   执行：
   php artisan vendor:publish --provider="TymonJWTAuthProvidersJWTAuthServiceProvider"
   php artisan jwt:generate

   jwt-auth默认的登录状态有效期为60分钟，token刷新时间为14天，该设置可以在config/jwt.php中修改。
   在超过token刷新时间之前，可以用旧token刷新换取新token，以重新获取登录状态。

   config/jwt.php修改配置如下，因为我们把模型放在AppModels下：（如果不修改路径，则不用修改此项）
   'user' => 'AppModelsUser',
   其中ttl表示token有效期，默认60分钟，但是测试改成一分钟貌似没起作用；

四、安装dingo/api
   https://github.com/dingo/api/wiki/Installation

   在composer.json中加入：
   "dingo/api": "1.0.*@dev"
   然后composer update
   执行：php artisan vendor:publish --provider="DingoApiProviderLaravelServiceProvider"，生成配置文件api.php
   config/app.php中的providers中加入：
   DingoApiProviderLaravelServiceProvider::class,
   aliases中加入：
   'DingoApi' => DingoApiFacadeAPI::class,
   'DingoRoute' => DingoApiFacadeRoute::class,

   config/api.php的auth中加入：

   'basic' => function($app){
       return new DingoApiAuthProviderBasic($app['Auth']);
   },
   'jwt' => function($app){
       return new DingoApiAuthProviderJWT($app['TymonJWTAuthJWTAuth']);
   }

   在kernel.php中的$routeMiddleware中加入下列中间件
   'jwt.auth' => TymonJWTAuthMiddlewareGetUserFromToken::class,
   'jwt.refresh' => TymonJWTAuthMiddlewareRefreshToken::class,

   .env中增加配置
   #dingo/api配置
   API_STANDARDS_TREE=vnd
   API_DOMAIN=www.zhihu.pc
   #API_PREFIX=api
   API_VERSION=v1
   API_DEBUG=true
   API_STRICT=false

   路由设置：/routes/web.php中路由：这里都是系统默认的路由，会应用 web 中间件组，其提供了诸如 Session 和 CSRF 保护等特性；不要自己定义middleware什么的
   $api = app('DingoApiRoutingRouter');

   Route::get('/', function () {
       return view('welcome');
   });
   Route::get('/home', 'HomeController@index');
   Auth::routes();

   /routes/api.php中路由：这里的路由都是无状态的，并且会应用api 中间件组。这里我们用了dingo/api的jwt.auth中间件
   $api = app('DingoApiRoutingRouter');
   $api->version('v1', function (Router $api) {
       //非认证路由
       $api->group(['prefix' => 'home', 'namespace' => 'AppApiV1HomeController'], function (Router $api) {
           $api->post('/login', 'CommonController@login');
           $api->post('/register','CommonController@register');
           $api->get('refresh_token','CommonController@refreshToken');
       });
       //需要认证的路由:jwt.auth为Kernel.php中的$routeMiddleware配置的'jwt.auth' => TymonJWTAuthMiddlewareGetUserFromToken::class,
       $api->group(['prefix'=>'home','middleware' => 'jwt.auth', 'namespace' => 'AppApiV1HomeController'], function (Router $api) {
           $api->get('/users', 'CommonController@users');
       });
   });


   //注册用户：成功返回token
   http://www.zhihu.pc/home/register

   //post方式模拟登录：先要在users表里注册一个用户
   http://www.zhihu.pc/home/login

   //post方式：
   传送版本标记
   版本标记通过HTTP头传送，请在请求的HTTP头中包含一个Accept头，值为 application/vnd.xxxx.v1+json
   其中xxxx为.env文件中对应的API_SUBTYPE值

   登录状态保持
   本系统使用JWT(Json Web Token)机制保持客户端登录状态，对于需要验证身份后才能访问的接口，客户端必须提供token方能访问。客户端需要通过HTTP头Authorization携带token，请在请求的HTTP头中包含一个Authorization头，其值为 Bearer+一个半角空格+token值

   api的路由查看方式：
   php artisan api:routes
   web路由查看试：
   php artisan route:list

五、安装laravel-lang语言包
   https://packagist.org/packages/caouecs/laravel-lang
   composer require caouecs/laravel-lang:~3.0
   配置config/app.php，修改如下内容：
   'locale' => 'zh-CN',        //设置语言，对应于laravel-lang的语言包目录名，这将让错误提示返回中文信息
   然后把vendorcaouecslaravel-langsrczh-CN文件夹复制到resourceslangzh-CN
   修改config/app.php:
   locale' => 'zh-CN',        //设置语言，对应于laravel-lang的语言包目录名，这将让错误提示返回中文信息

六、配置
   1、创建Models目录(如果不改目录则不用修改让给项)，并将AppUser.php移动到AppModels，并修改User类的命名空间为AppModels。我们的Eloquent模型类将存放于此。
   2、配置config/app.php，修改如下内容：
       'timezone' => 'PRC',        //时区设置
   3、修改config/auth.php
       'providers' => [
           'users' => [
               'driver' => 'eloquent',
               'model' => AppModelsUser::class,        //修改命名空间(如果没有改目录，则不用改）
           ],
       ],
   4、修改appProvidersRouteServiceProvider.php下
       protected $namespace = '';      //原值为：AppHttpControllers

   5、创建appApiV1目录，作为Version 1 Api的目录

   6、安装laravel-cors包，提供跨站ajax调用能力

   7、安装jenssegers/agent包，获取客户端信息

七、前端相关
   Cors跨域资源共享（跨域）
   web前端与api使用不同的域名进行访问，于是产生跨域请求问题。但在本项目中，已经解决该问题。
   web端使用ajax的方式调用后端api接口。默认的，浏览器在进行跨域请求时，已经具备了提供的Origin头（HTTP头）的能力，但如果因为浏览器的原因，
   web端在请求中未提供Origin头时，api服务器将无法为web端提供服务，此时，需要web前端程序员主动提供Origin头。

   调用协议
   接口使用HTTP协议调用，遵循RESTful架构风格。

   请求方式
   GET：查看资源；
   POST：创建资源或提交数据；
   PUT：更新或创建资源；
   PATCH：修改资源部分属性
   DELETE：删除资源
   每个接口使用的请求方式不同，具体请参见接口说明。

   对于PUT、PATCH、DELETE类型的请求，api消费者如果无法正常请求，可尝试使用POST请求方式，
   并提供一个HTTP头X-HTTP-Method-Override来指明请求的方式，以此模拟PUT、PATCH或DELETE请求，例如：

   POST:/user/info
   X-HTTP-Method-Override=PUT

八、jwt模式下注册、登录、刷新token、获取信息的实现：
   <?php
   namespace AppApiV1HomeController;

   use AppHttpControllersController;
   use AppUser;
   use JWTAuth;
   use TymonJWTAuthExceptionsJWTException;
   use IlluminateSupportFacades;
   use IlluminateHttpRequest;
   use TymonJWTAuthExceptionsTokenBlacklistedException;

   class CommonController extends Controller
   {
       /**
        * 登录：成功返回token
        *
        * @param Request $request
        * @return IlluminateHttpJsonResponse
        */
       public function login(Request $request)
       {

           // grab credentials from the request
           $credentials = $request->only('email', 'password');

           try {
               // attempt to verify the credentials and create a token for the user
               if (!$token = JWTAuth::attempt($credentials)) {
                   return response()->json(['error' => 'invalid_credentials'], 401);
               }
           } catch (JWTException $e) {
               // something went wrong whilst attempting to encode the token
               return response()->json(['error' => 'could_not_create_token'], 500);
           }

           // all good so return the token
           return response()->json(compact('token'));
       }

       /**
        * 获取用户信息，token要通过验证
        *
        * @return IlluminateDatabaseEloquentCollection|static[]
        */
       public function users()
       {
           $users = User::all();
           return $users;
       }

       /**
        * 注册：成功返回token
        *
        * @param Request $request
        * @return mixed
        */
       public function register(Request $request)
       {
           //这里可以建个request对字段进行验证，这里就不写了
           $user = $request->only([
               'email',
               'name',
           ]);
           $user['avatar'] = $request->input('avatar', '');
           $user['password'] = bcrypt($request->input('password'));
           $user['confirmation_token'] = str_random(32);
           $user['is_active'] = 1;
           //记得要改user models里的fillable
           /**
            * protected $fillable = [
            * 'name', 'email', 'password', 'avatar', 'confirmation_token','is_active'
            * ];
            */
           $user = User::create($user);
           $token = JWTAuth::fromUser($user);
           return response()->json(compact('token'));
       }

       /**
        * 刷新token
        *
        * 简要描述：
        * 刷新token。当token过期后，使用此接口刷新token
        * 通过Accept头携带旧token
        * 客户端需要通过HTTP头Authorization携带token，请在请求的HTTP头中包含一个Authorization头，其值为：
        * Bearer+一个半角空格+token值
        *
        * @return IlluminateHttpJsonResponse
        * @throws Exception
        */
       public function refreshToken()
       {
           try {
               $token = JWTAuth::parseToken()->refresh();
           } catch (TokenBlacklistedException $e) {
               $data = [
                   'code' => '4005',
                   'msg' => '登录状态过期'
               ];
               return response()->json($data);
           }
   
           return response()->json(compact('token'));
       }
   }