Adding pagination, tests, + docs to Client Grants; minor test suite refactor #271
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,75 +2,193 @@ | |
|
|
||
| namespace Auth0\SDK\API\Management; | ||
|
|
||
| use Auth0\SDK\Exception\CoreException; | ||
|
|
||
| /** | ||
| * Class ClientGrants. | ||
| * Handles requests to the Client Grants endpoint of the v2 Management API. | ||
| * | ||
| * @package Auth0\SDK\API\Management | ||
| */ | ||
| class ClientGrants extends GenericResource | ||
| { | ||
|
|
||
| /** | ||
| * Get all Client Grants, by page if desired. | ||
| * Required scope: "read:client_grants" | ||
| * | ||
| * @param array $params Additional URL parameters to send: | ||
| * - "audience" to filter be a specific API audience identifier. | ||
| * - "client_id" to return an object. | ||
| * - "include_totals" to return an object. | ||
| * @param null|integer $page The page number, zero based. | ||
| * @param null|integer $per_page The amount of entries per page. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants | ||
| */ | ||
| public function getAll(array $params = [], $page = null, $per_page = null) | ||
| { | ||
| if (null !== $page) { | ||
| $params['page'] = abs(intval($page)); | ||
| } | ||
|
|
||
| if (null !== $per_page) { | ||
| $params['per_page'] = abs(intval($per_page)); | ||
| } | ||
|
|
||
| return $this->apiClient->method('get') | ||
| ->addPath('client-grants') | ||
| ->withDictParams($params) | ||
| ->call(); | ||
| } | ||
|
|
||
| /** | ||
| * Get Client Grants by audience. | ||
| * Required scope: "read:client_grants" | ||
| * | ||
| * @param string $audience API Audience to filter by. | ||
| * @param null|integer $page The page number, zero based. | ||
| * @param null|integer $per_page The amount of entries per page. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws CoreException Thrown when $audience is empty or not a string. | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants | ||
| */ | ||
| public function getByAudience($audience, $page = null, $per_page = null) | ||
|
There was a problem hiding this comment. Is this convenience method also in other SDKs? |
||
| { | ||
| if (empty($audience) || ! is_string($audience)) { | ||
|
There was a problem hiding this comment. So the rest of the code follows this, although I think it's ugly. If it's consistent with the rest of the code base, then I'm fine with it. There was a problem hiding this comment. "Ugly" as in you don't like the error checking here? @lbalmaceda and I talked about failing early in methods to avoid API errors. For this one, an empty There was a problem hiding this comment. Don't like the space between a There was a problem hiding this comment. I was on the fence about the space. This is all whitespace-corrected now so I can enforce no space. |
||
| throw new CoreException('Empty or invalid "audience" parameter.'); | ||
| } | ||
|
|
||
| return $this->getAll(['audience' => $audience], $page, $per_page); | ||
| } | ||
|
|
||
| /** | ||
| * Get Client Grants by Client ID. | ||
| * Required scope: "read:client_grants" | ||
| * | ||
| * @param string $client_id Client ID to filter by. | ||
| * @param null|integer $page The page number, zero based. | ||
| * @param null|integer $per_page The amount of entries per page. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws CoreException Thrown when $client_id is empty or not a string. | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants | ||
| */ | ||
| public function getByClientId($client_id, $page = null, $per_page = null) | ||
|
There was a problem hiding this comment. Is this convenience method also in other SDKs? There was a problem hiding this comment. Not that I know of but I don't think that's a good reason not to add it here. Make the developer's life easier! There was a problem hiding this comment. Just curious, it's always good to create more convenience for the end user, balanced with maintainability. |
||
| { | ||
| if (empty($client_id) || ! is_string($client_id)) { | ||
| throw new CoreException('Empty or invalid "client_id" parameter.'); | ||
| } | ||
|
|
||
| return $this->getAll(['client_id' => $client_id], $page, $per_page); | ||
| } | ||
|
|
||
| /** | ||
| * Create a new Client Grant. | ||
| * Required scope: "create:client_grants" | ||
| * | ||
| * @param string $client_id Client ID to receive the grant. | ||
| * @param string $audience Audience identifier for the API being granted. | ||
| * @param array $scope Array of scopes for the grant. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws CoreException Thrown when $client_id or $audience are empty or not a string. | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/post_client_grants | ||
| */ | ||
| public function create($client_id, $audience, array $scope = []) | ||
| { | ||
| if (empty($client_id) || ! is_string($client_id)) { | ||
| throw new CoreException('Empty or invalid "client_id" parameter.'); | ||
| } | ||
|
|
||
| if (empty($audience) || ! is_string($audience)) { | ||
| throw new CoreException('Empty or invalid "audience" parameter.'); | ||
| } | ||
|
|
||
| return $this->apiClient->method('post') | ||
| ->addPath('client-grants') | ||
| ->withBody(json_encode([ | ||
| 'client_id' => $client_id, | ||
| 'audience' => $audience, | ||
| 'scope' => $scope, | ||
| ])) | ||
| ->call(); | ||
| } | ||
|
|
||
| /** | ||
| * Delete a Client Grant by ID. | ||
| * Required scope: "delete:client_grants" | ||
| * | ||
| * @param string $id Client Grant ID to delete. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
|
There was a problem hiding this comment. Although we use Guzzle I would not mention it by name, goes for all mentions in this PR. There was a problem hiding this comment. We use it in the variable name for the API. It will also appear in the error name. I think it's helpful here in case someone is getting a fatal error and want to know where to start troubleshooting. |
||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/delete_client_grants_by_id | ||
| */ | ||
| public function delete($id) | ||
|
There was a problem hiding this comment. So presume audience is no longer required? What happens in PHP if a developer makes a call to a method that has a change in signature? There was a problem hiding this comment. Bad diff for this one ... you can see this is a different method. To answer your question though ... it wouldn't fail, it just wouldn't use that param. There was a problem hiding this comment. Indeed, the one I saw was |
||
| { | ||
| return $this->apiClient->method('delete') | ||
| ->addPath('client-grants', $id) | ||
| ->call(); | ||
| } | ||
|
|
||
| /** | ||
| * Update an existing Client Grant. | ||
| * Required scope: "update:client_grants" | ||
| * | ||
| * @param string $id Client Grant ID to update. | ||
| * @param array $scope Array of scopes to update; will replace existing scopes, not merge. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| * | ||
| * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/patch_client_grants_by_id | ||
| */ | ||
| public function update($id, array $scope) | ||
| { | ||
| return $this->apiClient->method('patch') | ||
| ->addPath('client-grants', $id) | ||
| ->withBody(json_encode(['scope' => $scope,])) | ||
| ->call(); | ||
| } | ||
|
|
||
| /** | ||
| * Get a Client Grant. | ||
| * TODO: Deprecate, cannot get a Client Grant by ID. | ||
| * | ||
| * @param string $id Client Grant ID. | ||
| * @param null|string $audience Client Grant audience to filter by. | ||
| * | ||
| * @return mixed | ||
| * | ||
| * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call. | ||
| */ | ||
| public function get($id, $audience = null) | ||
| { | ||
| $request = $this->apiClient->get() | ||
| ->addPath('client-grants'); | ||
|
|
||
| if ($audience !== null) { | ||
| $request = $request->withParam('audience', $audience); | ||
| } | ||
|
|
||
| return $request->call(); | ||
| } | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like I'm changing the method name here but I'm not. The
getmethod still exists (in a semi-broken state), moved to the bottom of the class with aTODOto deprecate.