Adding documentation and tests for Logs endpoint; minor code quality …

…tweaks

composer.json

@@ -36,7 +36,8 @@
     "test": "SHELL_INTERACTIVE=1 vendor/bin/phpunit  --colors=always --verbose ",
     "test-ci": "vendor/bin/phpunit --coverage-text --coverage-clover=build/coverage.xml",
     "phpcs": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcs --standard=phpcs-ruleset.xml -s",
-    "phpcbf": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcbf --standard=phpcs-ruleset.xml .",
+    "phpcbf": "./vendor/bin/phpcbf --standard=phpcs-ruleset.xml .",
+    "phpcbf-path": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcbf --standard=phpcs-ruleset.xml",
     "sniffs": "./vendor/bin/phpcs --standard=phpcs-ruleset.xml -e"
   }
 }

phpcs-ruleset.xml

@@ -26,6 +26,12 @@
         <exclude name="Generic.Files.EndFileNoNewline"/>
         <exclude name="Generic.Files.LowercasedFilename"/>
     </rule>
+    <rule ref="Generic.Files.LineLength">
+        <properties>
+            <property name="lineLimit" value="120"/>
+            <property name="absoluteLineLimit" value="120"/>
+        </properties>
+    </rule>
     <rule ref="Generic.Formatting">
         <exclude name="Generic.Formatting.NoSpaceAfterCast"/>
     </rule>
@@ -51,6 +57,7 @@
     <rule ref="Squiz.Classes"/>
     <rule ref="Squiz.Commenting">
         <exclude name="Squiz.Commenting.ClosingDeclarationComment"/>
+        <exclude name="Squiz.Commenting.ClassComment.TagNotAllowed"/>
         <exclude name="Squiz.Commenting.FileComment"/>
         <exclude name="Squiz.Commenting.LongConditionClosingComment"/>
         <exclude name="Squiz.Commenting.FunctionComment.ScalarTypeHintMissing"/>
@@ -61,7 +68,7 @@
     </rule>
     <rule ref="Squiz.Functions.FunctionDeclarationArgumentSpacing">
         <properties>
-            <property name="equalsSpacing" value="1" />
+            <property name="equalsSpacing" value="1"/>
         </properties>
     </rule>
     <rule ref="Squiz.Operators">
@@ -78,9 +85,9 @@
     </rule>
     <rule ref="Squiz.WhiteSpace.FunctionSpacing">
         <properties>
-            <property name="spacing" value="1" />
-            <property name="spacingBeforeFirst" value="0" />
-            <property name="spacingAfterLast" value="0" />
+            <property name="spacing" value="1"/>
+            <property name="spacingBeforeFirst" value="0"/>
+            <property name="spacingAfterLast" value="0"/>
         </properties>
     </rule>
 </ruleset>

src/API/Management/Logs.php

@@ -2,34 +2,52 @@
 
 namespace Auth0\SDK\API\Management;
 
+/**
+ * Class Logs.
+ * Access to the v2 Management API Logs endpoint.
+ *
+ * @package Auth0\SDK\API\Management
+ */
 class Logs extends GenericResource
 {
     /**
+     * Get a single Log event.
+     * Required scope: "read:logs"
+     *
+     * @param string $log_id Log entry ID to get.
      *
-     * @param  string $id
      * @return mixed
+     *
+     * @throws \Exception Thrown by Guzzle for API errors.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Logs/get_logs_by_id
      */
-    public function get($id)
+    public function get($log_id)
     {
-        return $this->apiClient->get()
-        ->logs($id)
-        ->call();
+        return $this->apiClient->method('get')
+            ->addPath('logs', $log_id)
+            ->call();
     }
 
     /**
+     * Retrieves log entries that match the specified search criteria (or list all entries if no criteria is used).
+     * Required scope: "read:logs"
+     *
+     * @param array $params Log search parameters to send:
+     *      - Including a restricted "fields" parameter can speed up API calls significantly.
+     *      - Results are paged by default; pass a "page" and "per_page" param to adjust what results are shown.
      *
-     * @param  array $params
      * @return mixed
+     *
+     * @throws \Exception Thrown by Guzzle for API errors.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Logs/get_logs
      */
-    public function search($params = [])
+    public function search(array $params = [])
     {
-        $client = $this->apiClient->get()
-        ->logs();
-
-        foreach ($params as $param => $value) {
-            $client->withParam($param, $value);
-        }
-
-        return $client->call();
+        return $this->apiClient->method('get')
+            ->addPath('logs')
+            ->withDictParams($params)
+            ->call();
     }
 }

tests/API/Management/LogsTest.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace Auth0\Tests\API;
+
+use Auth0\SDK\API\Management;
+
+/**
+ * Class LogsTest.
+ * Tests the Auth0\SDK\API\Management\Logs class.
+ *
+ * @package Auth0\Tests\API
+ */
+class LogsTest extends ApiTests
+{
+
+    /**
+     * Logs API client.
+     *
+     * @var mixed
+     */
+    protected static $api;
+
+    /**
+     * Valid Log ID to test getter.
+     *
+     * @var string
+     */
+    protected static $log_id;
+
+    /**
+     * Sets up API client for entire testing class.
+     *
+     * @return void
+     */
+    public static function setUpBeforeClass()
+    {
+        $env   = self::getEnvStatic();
+        $token = self::getTokenStatic($env, [ 'logs' => [ 'actions' => ['read'] ] ]);
+        $api   = new Management($token, $env['DOMAIN']);
+
+        self::$api = $api->logs;
+    }
+
+    /**
+     * Test a general search.
+     *
+     * @return void
+     */
+    public function testLogSearch()
+    {
+        $search_results = self::$api->search();
+        $this->assertNotEmpty($search_results);
+
+        // Get the 10th log entry to test pagination in self::testLogSearchPagination().
+        self::$log_id = $search_results[9]['log_id'];
+        $this->assertNotEmpty(self::$log_id);
+    }
+
+    /**
+     * Test fields parameter.
+     *
+     * @return void
+     */
+    public function testLogSearchFields()
+    {
+        $search_results = self::$api->search([
+            'fields' => '_id,log_id,date',
+            'include_fields' => true,
+        ]);
+        $this->assertNotEmpty($search_results);
+        $this->assertNotEmpty($search_results[0]['date']);
+        $this->assertNotEmpty($search_results[0]['log_id']);
+        $this->assertCount(3, $search_results[0]);
+    }
+
+    /**
+     * Test pagination parameters.
+     *
+     * @return void
+     */
+    public function testLogSearchPagination()
+    {
+        $expected_count = 10;
+        $search_results = self::$api->search([
+            // Fields here to speed up API call.
+            'fields' => '_id,log_id,date',
+            'include_fields' => true,
+
+            // First page of 10 results.
+            'page' => 0,
+            'per_page' => $expected_count,
+        ]);
+        $this->assertNotEmpty($search_results);
+        $this->assertCount($expected_count, $search_results);
+
+        // Check that the last result (10th) matches the last result with per_page = 10.
+        $last_results = end($search_results);
+        $this->assertEquals(self::$log_id, $last_results['log_id']);
+    }
+
+    /**
+     * Test getting a single log entry with an ID.
+     *
+     * @return void
+     */
+    public function testGetOne()
+    {
+        $one_log = self::$api->get(self::$log_id);
+        $this->assertNotEmpty($one_log);
+        $this->assertEquals(self::$log_id, $one_log['log_id']);
+    }
+}