README

Api Responder是一个使用Laravel资源进行API响应的简单包，具有一些有用、易读和可链式的方法。

这个包是为我个人的使用而制作的。

• 先决条件
• 入门
• 安装
• 用法
  • 基本用法
  • 响应用法
    • 响应别名
  • 获取分页限制用法
  • 设置分页限制用法
  • 错误用法
  • 安全错误用法
  • 验证用法
  • With用法
  • 获取包装用法
  • 设置包装用法
• 示例
• 待办事项

先决条件

此包需要Laravel 5.5（或更高版本）。

入门

请记住，此包并不完美，它只是我在开发期间的一些辅助工具。您可以访问Laravel官方文档了解有关API资源的更多内容。其余的文档将解释如何安装以及提供的每个方法。

安装

通过Composer

$ composer require moaalaa/laravel-api-responder

如果您没有运行Laravel 5.5（或更高版本），请在config/app.php中添加服务提供者。

MoaAlaa\ApiResponder\ApiResponderServiceProvider::class,

如果您在Laravel 5.5+上运行此包，包自动发现将处理添加服务提供者的魔法。

用法

使用ApiResponder非常简单直接，只需在任何地方使用ApiResponder特质（我通常在控制器中使用它，所以用法和示例也将是如此）。

<?php

namespace App\Http\Controllers;

use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {

    }
}

基本用法

通过使用ApiResponder特质，您将能够访问名为api()的方法，它将为您执行所有魔法。它为您提供了许多有用方法，其中最重要的是response()，它会为您发送响应。

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        return $this->api()->response(User::first());
    }
}

响应用法

$this->api()->response(...)负责为您响应所有数据，并且它接受多个参数。

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        // $this->api()->response($data, $error = null, int $code = 200, $additional = [], $wrap = 'payload');

        $this->api()->response(User::first(), null, 200, function () {
            return ['foo' => 'bar'];
        }, 'baz');

        return $this->api()->response(User::first());
    }
}

响应别名

响应有一个名为$this->api()->responseWith()的别名，以提高可读性。

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        $users = User::where(...)->take(...)->get();
        return $this->api()->responseWith($users);
    }
}

获取分页限制用法

$this->api()->getPaginateLimit()方法用于在分页时返回分页限制。默认值为10，除非您使用$this->api()->setPaginateLimit($limit)来更改它。

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        return $this->api()->response(User::paginate($this->api()->getPaginateLimit()));
    }
}

设置分页限制用法

$this->api()->setPaginateLimit(50)->response(...)方法用于在分页时调整分页限制。您可以在任何服务提供者（如AppServiceProvider）中定义它，以在所有使用$this->api()->getPaginationLimit()的地方应用限制。您也可以在运行时编辑它。

AppServiceProvider

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use MoaAlaa\ApiResponder\ApiResponder;

class AppServiceProvider extends ServiceProvider
{
    use ApiResponder;

    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->api()->setPaginationLimit(20);
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }
}

HomeController

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {   
        // Default Pagination Limit 
        return $this->api()->response(User::paginate($this->api()->getPaginateLimit()));
        
        // Run-Time Set Pagination Limit 
        return $this->api()->setPaginateLimit(50)->response(User::paginate($this->api()->getPaginateLimit()));
    }
}

错误用法

$this->api()->error(...)负责响应错误消息。

<?php

// Simple User Api Login Example
namespace App\Http\Controllers\Auth;

use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class LoginController extends Controller
{
    use ApiResponder;

    public function login(Request $request)
    {
        if (! $token = auth()->attempt($request->only(['email', 'password']))) {
            return $this->api()->error($token, Response::HTTP_NOT_FOUND)
        }

        return $this->api()->response(['token' => $token]);
    }
}

安全错误用法

$this->api()->safeError(...)当在Laravel应用程序中进行验证且不想手动使用Validator Class时，如果您使用$this->validate() Or request()->validate() Or $this->api()->validate()，则此方法适用于您。但您必须将代码放在Try Catch Block中，该方法将处理异常并获取消息，即使它是正常消息、自定义消息或甚至是Laravel验证错误（我最喜欢的方法之一）。

注意$this->api()->validate()将在下面进行说明。

<?php

// Simple User Api Login Example
namespace App\Http\Controllers\Auth;

use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class LoginController extends Controller
{
    use ApiResponder;

    public function login(Request $request)
    {
        try {
            $request->validate(...);

            if (! $token = auth()->attempt($request->only(['email', 'password']))) {
                return $this->api()->error($token, Response::HTTP_NOT_FOUND)
            }

            return $this->api()->response(['token' => $token]);
        
        } catch(\Exception $ex) {
            return $this->api()->safeError($ex);
        }

    }
}

验证用法

$this->api()->validate(...Roles...) 此方法用于验证请求输入并返回已验证的输入

注意，它只是对 request()->validate() 函数的一个包装

<?php

// Simple User Api Login Example
namespace App\Http\Controllers\Auth;

use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class LoginController extends Controller
{
    use ApiResponder;

    public function login(Request $request)
    {
        try {
            $validated = $this->api()->validate([
                'email' => 'required|email',
                'password' => 'required',
            ]);

            if (! $token = auth()->attempt($validated)) {
                return $this->api()->error($token, Response::HTTP_NOT_FOUND)
            }

            return $this->api()->response(['token' => $token]);
        
        } catch(\Exception $ex) {
            return $this->api()->safeError($ex);
        }

    }
}

With用法

$this->api()->with(...)->response(...) 当需要在响应中发送附加数据或使代码更易读时，此方法非常有用

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        return $this->api()->with(['foo' => 'bar'])->response(User::first());
    }
}

您还可以进行动态命名

但是，使用它时仍有一些问题需要注意

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        return $this->api()->withFoo('bar')->response(User::first()); // ->withFoo('bar') Will Convert To ['foo' => 'bar']
        return $this->api()->withFoo(['bar', 'baz'])->response(User::first()); // ->withFoo(['bar', 'baz']) Will Convert To ['foo' => ['bar', 'baz']]
    }
}

获取包装用法

$this->api()->getWrapping 此方法获取围绕您数据的外包装键字符串

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        return $this->api()->getWrapping(); // "payload" is The Default
    }
}

设置包装用法

方法 $this->api()->setWrapping('foo') 用于调整围绕数据响应的外包装键字符串。您可以在任何服务提供者（如 AppServiceProvider）中定义它，以便在所有使用 $this->api()->response() 方法的地方应用新的外包装键字符串。您也可以在运行时进行编辑

请注意，它还有一个别名 $this->api()->wrapping('foo')

AppServiceProvider

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use MoaAlaa\ApiResponder\ApiResponder;

class AppServiceProvider extends ServiceProvider
{
    use ApiResponder;

    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->api()->setWrapping('foo');
        $this->api()->wrapping('foo');
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }
}

HomeController

<?php

namespace App\Http\Controllers;

use App\User;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        // return $this->api()->getWrapping(); // "foo"

        return $this->api()->response(...); // Now All Response Data Will Be In "foo" Key String
        
        // Run-Time Set Wrapping
        return $this->api()->setWrapping('bar')->response(...); // Now All Response Data Will Be In "bar" Key String
        
        // Run-Time Set Wrapping
        return $this->api()->wrapping('baz')->response(...); // Now All Response Data Will Be In "baz" Key String
    }
}

示例

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use App\User;
use App\Post;
use App\Setting;
use MoaAlaa\ApiResponder\ApiResponder;

class HomeController extends Controller
{
    use ApiResponder;

    public function index()
    {
        $this->api()
        ->with(['posts'=> Post::all()])
        ->withSettings(Setting::all())
        ->wrapping('myData')
        ->response(User::paginate($this->api()->getPaginateLimit()), null, 200, function () {
            return ['token' => auth()->user()->token];
        });
    }
}

待办事项

• 测试用例