[SDK-1514] Implement Management V2 users export job support (#461)

* Implement Management V2 users export job support
* Update function docblocks in jobs class
* Add test units for user export job

Author: Evan Sims

src/API/Helpers/RequestBuilder.php

@@ -39,9 +39,9 @@ class RequestBuilder
     /**
      * HTTP method to use for the request.
      *
-     * @var array
+     * @var string
      */
-    protected $method = [];
+    protected $method;
 
     /**
      * Headers to include for the request.

src/API/Management/Jobs.php

@@ -7,9 +7,16 @@
 class Jobs extends GenericResource
 {
     /**
+     * Retrieves a job. Useful to check its status.
+     * Required scopes: "create:users" "read:users"
+     *
+     * @param  string  $id
+     *
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
      *
-     * @param  string $id
      * @return mixed
+     *
+     * @see https://auth0.com/docs/api/management/v2#!/Jobs/get_jobs_by_id
      */
     public function get($id)
     {
@@ -19,9 +26,16 @@ public function get($id)
     }
 
     /**
+     * Retrieve error details of a failed job.
+     * Required scopes: "create:users" "read:users"
+     *
+     * @param  string  $id
+     *
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
      *
-     * @param  string $id
      * @return mixed
+     *
+     * @see https://auth0.com/docs/api/management/v2#!/Jobs/get_errors
      */
     public function getErrors($id)
     {
@@ -31,11 +45,18 @@ public function getErrors($id)
     }
 
     /**
+     * Import users from a formatted file into a connection via a long-running job.
+     * Required scopes: "create:users" "read:users"
+     *
+     * @param  string  $file_path
+     * @param  string  $connection_id
+     * @param  array   $params
+     *
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
      *
-     * @param  string $file_path
-     * @param  string $connection_id
-     * @param  array  $params
      * @return mixed
+     *
+     * @see https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports
      */
     public function importUsers($file_path, $connection_id, $params = [])
     {
@@ -59,6 +80,45 @@ public function importUsers($file_path, $connection_id, $params = [])
         return $request->call();
     }
 
+
+    /**
+     * Export all users to a file via a long-running job.
+     * Required scopes: "read:users"
+     *
+     * @param  array  $params
+     *
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @return mixed
+     *
+     * @see https://auth0.com/docs/api/management/v2#!/Jobs/post_users_exports
+     */
+    public function exportUsers($params = [])
+    {
+        $request = $this->apiClient->method('post')
+        ->addPath('jobs', 'users-exports');
+
+        $body = [];
+
+        if (!empty($params['connection_id'])) {
+            $body['connection_id'] = $params['connection_id'];
+        }
+
+        if (!empty($params['format']) && in_array($params['format'], ['json', 'csv'])) {
+            $body['format'] = $params['format'];
+        }
+
+        if (!empty($params['limit']) && is_numeric($params['limit'])) {
+            $body['limit'] = $params['limit'];
+        }
+
+        if (!empty($params['fields']) && is_array($params['fields'])) {
+            $body['fields'] = $params['fields'];
+        }
+
+        return $request->withBody(json_encode($body), JSON_FORCE_OBJECT)->call();
+    }
+
     /**
      * Create a verification email job.
      * Required scope: "update:users"

tests/unit/API/Management/JobsTest.php

@@ -127,6 +127,61 @@ public function testThatImportUsersRequestIsFormedProperly()
         $this->assertEquals( '__test_ext_id__', $form_body_arr[$ext_id_key + self::FORM_DATA_VALUE_KEY_OFFSET] );
     }
 
+    /**
+     * @throws \Exception Should not be thrown in this test.
+     */
+    public function testThatExportUsersRequestIsFormedProperly()
+    {
+        $api = new MockManagementApi( [ new Response( 200, self::$headers ) ] );
+
+        $api->call()->jobs()->exportUsers(
+            [
+                'connection_id' => '__test_conn_id__',
+                'limit' => 5,
+                'format' => 'json',
+                'fields' => [['name' => 'user_id']],
+            ]
+        );
+
+        $this->assertEquals( 'POST', $api->getHistoryMethod() );
+        $this->assertEquals( 'https://api.test.local/api/v2/jobs/users-exports', $api->getHistoryUrl() );
+        $this->assertEmpty( $api->getHistoryQuery() );
+
+        $request_body = $api->getHistoryBody();
+
+        $this->assertNotEmpty( $request_body['connection_id'] );
+        $this->assertEquals( '__test_conn_id__', $request_body['connection_id'] );
+
+        $this->assertNotEmpty( $request_body['limit'] );
+        $this->assertEquals( '5', $request_body['limit'] );
+
+        $this->assertNotEmpty( $request_body['format'] );
+        $this->assertEquals( 'json', $request_body['format'] );
+
+        $this->assertNotEmpty( $request_body['fields'] );
+        $this->assertEquals( [['name' => 'user_id']], $request_body['fields'] );
+    }
+
+    /**
+     * @throws \Exception Should not be thrown in this test.
+     */
+    public function testThatExportUsersRequestIsFilteringProperly()
+    {
+        $api = new MockManagementApi( [ new Response( 200, self::$headers ) ] );
+
+        $api->call()->jobs()->exportUsers(
+            [
+                'connection_id' => '__test_conn_id__',
+                'limit' => 'invalid limit',
+                'format' => 'invalid format',
+            ]
+        );
+
+        $request_body = $api->getHistoryBody();
+
+        $this->assertArrayNotHasKey('limit', $request_body);
+        $this->assertArrayNotHasKey('format', $request_body);
+    }
 
     /**
      * @throws \Exception Should not be thrown in this test.