diff --git a/Authentication.md b/Authentication.md index 27aef3e..bcb53fa 100644 --- a/Authentication.md +++ b/Authentication.md @@ -16,7 +16,7 @@ This provider uses the default basic authentication built into Laravel and Lumen ```php app('Dingo\Api\Auth\Auth')->extend('basic', function ($app) { - return new Dingo\Api\Auth\Provider\Basic($app['auth'], 'email'); + return new Dingo\Api\Auth\Provider\Basic($app['auth'], 'email'); }); ``` @@ -24,15 +24,19 @@ app('Dingo\Api\Auth\Auth')->extend('basic', function ($app) { This package makes use of a 3rd party package to integrate JWT authentication. Please refer to the [`tymon/jwt-auth`](https://github.com/tymondesigns/jwt-auth) GitHub page for details on installing and configuring the package. -Once you have the package you can configure the provider in your `config/api.php` file or in a service provider or bootstrap file. +Once you have the package you can configure the provider in your `config/api.php` file. ```php -'jwt' => 'Dingo\Api\Auth\Provider\JWT' +'auth' => [ + 'jwt' => Dingo\Api\Auth\Provider\JWT::class, +], ``` +Or in a service provider or bootstrap file. + ```php app('Dingo\Api\Auth\Auth')->extend('jwt', function ($app) { - return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']); + return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']); }); ``` @@ -46,7 +50,7 @@ Once you have the package you will need to configure it in a service provider or ```php app('Dingo\Api\Auth\Auth')->extend('oauth', function ($app) { - $provider = new Dingo\Api\Auth\Provider\OAuth2($app['oauth2-server.authorizer']->getChecker()); + $provider = new Dingo\Api\Auth\Provider\OAuth2($app['oauth2-server.authorizer']->getChecker()); $provider->setUserResolver(function ($id) { // Logic to return a user by their ID. @@ -105,7 +109,7 @@ The resolvers both receive the ID of the user or client and should use this ID t If you're developing for a legacy system or require some other form of authentication you may implement your own provider. -Your authentication provider should implement `Dingo\Api\Contract\Auth\Provider`. If authentication succeeds your provider should return an instance of the authenticated user. If authentication fails your provider should thrown a `Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException`. +Your authentication provider should implement `Dingo\Api\Contract\Auth\Provider`. If authentication succeeds your provider should return an instance of the authenticated user. If authentication fails your provider should throw a `Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException`. ```php use Illuminate\Http\Request; @@ -141,7 +145,7 @@ class CustomProvider extends Authorization $this->validateAuthorizationHeader($request); // If the authorization header passed validation we can continue to authenticate. - // If authentication then fails we must throw the UnauthorizedHttpException. + // If authentication fails we must throw the UnauthorizedHttpException. } public function getAuthorizationMethod() @@ -154,7 +158,9 @@ class CustomProvider extends Authorization Once you've implemented your authentication provider you can configure it in your `config/api.php` file. ```php -'custom' => 'CustomProvider' +'auth' => [ + 'custom' => 'CustomProvider', +], ``` Or from your bootstrap file or service provider. diff --git a/Commands.md b/Commands.md index 66b944c..907c422 100644 --- a/Commands.md +++ b/Commands.md @@ -2,9 +2,9 @@ The commands that are available will vary depending on which framework you're us | | Laravel | Lumen | |------------|:-------:|:-----:| -| api:routes | ✔ | | -| api:cache | ✔ | | -| api:docs | ✔ | ✔ | +| api:routes | ✔ | | +| api:cache | ✔ | | +| api:docs | ✔ |✔ | #### `api:routes` @@ -32,7 +32,7 @@ $ php artisan api:routes --scopes read_user_data --scopes write_user_data This command will cache your API routes alongside the main application routes. When run this command will also run the `route:cache` command automatically, so do not run that command after running this command. -Your routes should either appear in the main `app/Http/routes.php` file or be included within that file for caching to take affect. +Your routes should either appear in the main `app/Http/routes.php` file or be included within that file for caching to take effect. ##### Examples diff --git a/Configuration.md b/Configuration.md index 7dee38a..0ade466 100644 --- a/Configuration.md +++ b/Configuration.md @@ -92,7 +92,7 @@ API_CONDITIONAL_REQUEST=false Strict mode will require clients to send the `Accept` header instead of defaulting to the version specified in the configuration file. This means you will not be able to browse the API through your web browser. -If strict mode is enabled and an invalid `Accept` header is used the API will throw an unhandled `Symfony\Component\HttpKernel\Exception\BadRequestHttpException` that should be you should handle appropriately. +If strict mode is enabled and an invalid `Accept` header is used the API will throw an unhandled `Symfony\Component\HttpKernel\Exception\BadRequestHttpException` that you should handle appropriately. You can configure this in your `.env` file. @@ -108,7 +108,7 @@ For more complex configuration you will need a service provider or bootstrap fil ```php $app['Dingo\Api\Auth\Auth']->extend('oauth', function ($app) { - return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']); + return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']); }); ``` @@ -128,7 +128,13 @@ $app['Dingo\Api\Http\RateLimit\Handler']->extend(function ($app) { Fractal is the default response transformer. -You can configure this in your `.env`. file, however, for more complex configuration you will need a service provider or bootstrap file. +You can configure this in your `.env`. file. + +``` +API_TRANSFORMER=Dingo\Api\Transformer\Adapter\Fractal +``` + +However, for more complex configuration you will need a service provider or bootstrap file. ```php $app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) { diff --git a/Creating-API-Endpoints.md b/Creating-API-Endpoints.md index ff56ff3..ad2d0cc 100644 --- a/Creating-API-Endpoints.md +++ b/Creating-API-Endpoints.md @@ -73,13 +73,13 @@ You can also register resources and controllers using the respective methods. Naming your routes lets you easily generate URLs to them. You can name your routes in the exact same way as you do in Laravel. ```php -$api->get('users/{id}', ['as' => 'users.index', 'uses' => 'Api\V1\UserController@show']); +$api->get('users/{id}', ['as' => 'users.show', 'uses' => 'Api\V1\UserController@show']); ``` Now you can generate a URL to the named route. ```php -app('Dingo\Api\Routing\UrlGenerator')->version('v1')->route('users.index'); +app('Dingo\Api\Routing\UrlGenerator')->version('v1')->route('users.show'); ``` You must supply a version so that the URL can be properly generated based on the route within that version. This let's you use the diff --git a/Errors-And-Error-Responses.md b/Errors-And-Error-Responses.md index ca44406..84b0345 100644 --- a/Errors-And-Error-Responses.md +++ b/Errors-And-Error-Responses.md @@ -18,7 +18,7 @@ Here is a list of built-in Symfony exceptions. | `Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException` | 503 | | `Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException` | 429 | | `Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException` | 401 | -| `Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException` | 415 | +| `Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException` | 415 | As an example you might throw a `ConflictHttpException` when you attempt to update a record that has been updated by another user prior to this update request. diff --git a/Responses.md b/Responses.md index 8a52f36..d59e563 100644 --- a/Responses.md +++ b/Responses.md @@ -46,7 +46,7 @@ Now your controllers can simply extend this base controller. The response builde > Some of the documentation below makes use of [Transformers](https://github.com/dingo/api/wiki/Transformers), be sure to read that chapter for more details. -#### Responding With An Array +#### Responding With An Array (deprecated) ```php class UserController extends BaseController @@ -174,7 +174,7 @@ return $this->response->item($user, new UserTransformer)->setStatusCode(200); ### Custom Response Formats -In the **configuration** chapter we briefly touched on response formats. By default the package will automatically use the JSON format and set an appropriate `Content-Type` header. Aside from a JSON formatter there is also a JSONP formatter. This formatter will wrap the responses in a callback. To register this format you can simply swap out the default JSON formatter in the configuration file or in your bootstrap file. +In the **configuration** chapter we briefly touched on response formats. By default the package will automatically use the JSON format and set an appropriate `Content-Type` header. Aside from a JSON formatter there is also a JSONP formatter. This formatter will wrap the responses in a callback. To register this format you can simply swap out the default JSON formatter in the configuration file. ```php 'formats' => [ @@ -182,13 +182,15 @@ In the **configuration** chapter we briefly touched on response formats. By defa ] ``` + Or in your bootstrap file. + ```php Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp); ``` By default the callback parameter expected in the query string is `callback`, this can be changed by passing in the first parameter to the class constructor. If the query string does not contain a parameter with the name of your callback parameter it will default to a JSON response. -You can also register and use your own formatters should you need to. Your formatter should extend `Dingo\Api\Http\Response\Format\Format`. There following methods should be defined: `formatEloquentModel`, `formatEloquentCollection`, `formatArray`, and `getContentType`. Refer to the abstract class for more details on what each method should do or take a look at the pre-defined format classes. +You can also register and use your own formatters should you need to. Your formatter should extend `Dingo\Api\Http\Response\Format\Format`. The following methods should be defined: `formatEloquentModel`, `formatEloquentCollection`, `formatArray`, and `getContentType`. Refer to the abstract class for more details on what each method should do or take a look at the pre-defined format classes. ### Morphing And Morphed Events diff --git a/Transformers.md b/Transformers.md index 5471afe..0747451 100644 --- a/Transformers.md +++ b/Transformers.md @@ -2,7 +2,7 @@ Transformers allow you to easily and consistently transform objects into an arra ### Terminology -The word "transformer" is used quite a bit in this chapter. It's worth noting what the following terms mean when used throughout this chapter. +The word "transformer" is used quite a bit in this chapter. It's worth nothing what the following terms mean when used throughout this chapter. - The **transformation layer** is a library that prepares and handles transformers. - A **transformer** is a class that will takes raw data and returns it as a presentable array ready for formatting. The way a transformer is handled is dependant upon the transformation layer. @@ -97,7 +97,7 @@ class MyCustomTransformer implements Adapter { public function transform($response, $transformer, Binding $binding, Request $request) { - // Make a call to your transformation layer to transformer the given response. + // Make a call to your transformation layer to transform the given response. } } ``` diff --git a/_Sidebar.md b/_Sidebar.md index 519c50c..25430cb 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -12,3 +12,4 @@ 12. [API Blueprint Documentation](https://github.com/dingo/api/wiki/API-Blueprint-Documentation) 13. [Commands](https://github.com/dingo/api/wiki/Commands) 14. [Package Incompatibilities](https://github.com/dingo/api/wiki/Package-Incompatibilities) +15. [Extending The Core](https://github.com/dingo/api/wiki/Extending-The-Core)