Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

faktas2 · 2023-08-03T22:13:45Z

Summary

This pull request enhances the documentation, providing valuable information on the options parameter usage.

Changes Made

I have added an extensive section about the available options parameter in the README.md file. This section now explains each option in detail, allowing users to customize the MinFraud client's behavior effectively.

horgh · 2023-08-04T18:00:42Z

README.md

@@ -84,7 +84,7 @@ and [Report Transaction](https://dev.maxmind.com/minfraud/report-transaction/) A
 ### minFraud API ###

 To use the minFraud API, create a new `\MaxMind\MinFraud` object. The constructor
-takes your MaxMind account ID, license key, and an optional options array as
+takes your MaxMind account ID, license key, and an optional [options](#Options) array as


I think we could link to the API docs that have separate docs about these in the README - see here.

For GeoIP2 APIs, we reference the other hosts like so. Could we do the same here for the sandbox?

horgh · 2023-08-04T18:04:16Z

README.md

+
+| Option           | Description                                                                                                                                                                          |
+|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **host**         | The host to use when connecting to the web service. By default, the client connects to the production host. However, during testing and development, you can set this option to '[sandbox.maxmind.com](sandbox.maxmind.com)' to use the sandbox host. The sandbox host allows you to experiment with the API without affecting your production data. |


I think this kind of stuff would belong in the API docs. See here for how we mention the alternate host for the GeoIP2-php API.

horgh · 2023-08-04T19:21:36Z

README.md

-takes your MaxMind account ID, license key, and an optional options array as
-arguments. This object is immutable. You then build up the request using the
-`->with*` methods as shown below. Each method call returns a new object. The
+To use the MinFraud API, you'll need to create a new `MaxMind\MinFraud` object. The constructor


Why'd we lose the \? Can we keep this as minFraud API? The original phrasing seems fine.

horgh · 2023-08-04T19:22:12Z

README.md

+];
+
+// Create a MinFraud object with your account ID, license key, and options
+$mf = new MaxMind\MinFraud(1, 'ABCD567890', $options);


This could be just new MinFraud I think - see example below.

horgh · 2023-08-04T19:30:38Z

README.md

-arguments. This object is immutable. You then build up the request using the
-`->with*` methods as shown below. Each method call returns a new object. The
+To use the MinFraud API, you'll need to create a new `MaxMind\MinFraud` object. The constructor
+requires your MaxMind account ID, license key, and an optional [`options`](https://maxmind.github.io/minfraud-api-php/doc/v1.23.0/classes/MaxMind-MinFraud.html#method___construct) array as arguments. The `options` array can be used to set additional parameters such as `host` and `timeout`. Remember that this object is immutable.


Hmm, having the version number in the URL is not ideal. I think that was a poor suggestion on my part. Maybe we can refer to the API documentation generally instead, e.g. "See the API documentation for the possible options."

horgh · 2023-08-04T19:32:39Z

README.md

+<?php
+// Set any options you need, such as the host for the Sandbox environment
+$options = [
+    'host' => 'sandbox.maxmind.com'


Can we update the API docs to discuss the sandbox host too, like we do for the geolite host for the GeoIP2 APIs? That is, we could expand the comment about the host option.

horgh · 2023-08-04T19:34:18Z

README.md

+
+// Now you can use the $mf object to interact with the MinFraud API
+?>
+```


Can we make this more succinct? This is a big block in the summary section of the docs. I think it would be good to keep this section as clear and simple as possible.

e.g.

For instance, to call the Sandbox environment instead of the minFraud 2 web service:

$client = new MinFraud(1, 'ABCD567890', [ 'host' => 'sandbox.maxmind.com' ]);

horgh · 2023-08-08T16:57:01Z

src/MinFraud.php

@@ -62,6 +62,10 @@ class MinFraud extends MinFraud\ServiceClient
     * @param array  $options    An array of options. Possible keys:
     *
     * * `host` - The host to use when connecting to the web service.
+     *   By default, the client connects to the production host. However,
+     *   during testing and development, you can set this option to
+     *   'sandbox.maxmind.com' to use the sandbox host. The sandbox host


How about:

"to use the Sandbox environment's host. The Sandbox allows you"

horgh · 2023-08-08T16:58:48Z

README.md

+takes your MaxMind account ID, license key, and an optional `options` array as
+arguments. This object is immutable. See the API documentation for the possible options.
+
+For instance, to call the Sandbox environment instead of the minFraud 2 web service:


How about:

"For instance, to use the Sandbox web service instead of the production web service, you can provide the host option:"

I realize I suggested the original but it reads funny to me today 😿

I'm not sold on "production" as a widely recognizable term, but I see we use it in the support site docs too, so I guess it's fine.

Add an options section to README

cc53690

horgh requested changes Aug 4, 2023

View reviewed changes

faktas2 force-pushed the fatih/readme-updates branch 3 times, most recently from 44f451c to 247bfc0 Compare August 4, 2023 18:29

Remove options, update section

f1d4476

faktas2 force-pushed the fatih/readme-updates branch from 247bfc0 to f1d4476 Compare August 4, 2023 18:29

horgh requested changes Aug 4, 2023

View reviewed changes

Make summary smaller, extend host in API docs

a5300be

faktas2 force-pushed the fatih/readme-updates branch from 635afce to a5300be Compare August 7, 2023 13:29

horgh requested changes Aug 8, 2023

View reviewed changes

Minimal changes in README

375650e

faktas2 force-pushed the fatih/readme-updates branch from c49b5c2 to 375650e Compare August 8, 2023 19:17

horgh approved these changes Aug 9, 2023

View reviewed changes

horgh merged commit 64ca614 into main Aug 9, 2023
32 checks passed

horgh deleted the fatih/readme-updates branch August 9, 2023 15:21

oschwald mentioned this pull request Sep 6, 2023

How to tell the API to use Sandbox? #151

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

faktas2 commented Aug 3, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 4, 2023

horgh Aug 8, 2023

horgh Aug 8, 2023

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

Enhance MinFraud Documentation: Add Detailed Information on Available Options #152

Conversation

faktas2 commented Aug 3, 2023

Summary

Changes Made

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment