Rewrite README; add news and notes to CHANGELOG #253

joshcanhelp · 2018-05-02T15:53:18Z

Complete re-write of the main README file for this repo. Highlights:

Better, more complete installation steps
Better, more complete examples for basic tasks
Removal of deprecated or removed methods
Moved "news" and notes for unmaintained branches into the CHANGELOG

joshcanhelp · 2018-05-02T16:23:07Z

examples/basic-webapp/index.php

@@ -66,7 +66,7 @@
            <?php endif; ?>
            <?php if ( $userinfo ) :
                $picture = filter_var( $userinfo['picture'], FILTER_SANITIZE_URL );
-                $nickname = filter_var( $userinfo['email'], FILTER_SANITIZE_STRING );
+                $nickname = filter_var( $userinfo['nickname'], FILTER_SANITIZE_STRING );


tamigoodall

Suggested editorial changes.

tamigoodall · 2018-05-02T20:31:58Z

README.md

@@ -7,290 +7,505 @@
 [![License](https://poser.pugx.org/auth0/auth0-php/license)](https://packagist.org/packages/auth0/auth0-php)
 [![Total Downloads](https://poser.pugx.org/auth0/auth0-php/downloads)](https://packagist.org/packages/auth0/auth0-php)

+The Auth0 PHP SDK was created to provide straight-forward and tested methods for accessing Authentication and Management API endpoints. This README provides the basics for getting started along with a few simple examples of how to use the SDK. 


Suggested change: The Auth0 PHP SDK provides straight-forward and tested methods for accessing Authentication and Management API endpoints. This README describes how to get started and provides simple examples of how to use the SDK.

tamigoodall · 2018-05-02T20:34:13Z

README.md

@@ -7,290 +7,505 @@
 [![License](https://poser.pugx.org/auth0/auth0-php/license)](https://packagist.org/packages/auth0/auth0-php)
 [![Total Downloads](https://poser.pugx.org/auth0/auth0-php/downloads)](https://packagist.org/packages/auth0/auth0-php)

+The Auth0 PHP SDK was created to provide straight-forward and tested methods for accessing Authentication and Management API endpoints. This README provides the basics for getting started along with a few simple examples of how to use the SDK. 
+
+For a more detailed guide on how to install this in an existing project or to download a pre-configured seed project:


Suggested change: For more details about how to install this SDK into an existing project or how to download a preconfigured seed project, see:

tamigoodall · 2018-05-02T20:36:33Z

README.md

 ## Installation

-Installing via composer
+We recommend installing the SDK with [Composer](https://getcomposer.org/doc/00-intro.md). If you have Composer installed globally, it's as simple as:


Suggested change: We recommend installing the PHP SDK with Composer. If you already have Composer installed globally, run the following:

tamigoodall · 2018-05-02T20:42:03Z

README.md


-## Security Upgrade Notes 5.1.0+
+Include the Composer autoload file in your project and you're ready to use the SDK:


Suggested change: Include the Composer autoload file in your project to use the SDK:

tamigoodall · 2018-05-02T20:43:45Z

README.md


-### Decoding and verifying tokens
+1. Go to [auth0.com/signup](https://auth0.com/signup) and create your account


Suggested change: Go to auth0.com/signup and create your account.

tamigoodall · 2018-05-02T21:09:54Z

README.md


-### from 0.6.6
+- Maintain the minimum PHP version (found under `require.php` in `composer.json`)
+- Code to the [PSR-2 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)


Suggested change: Add a period at the end of the sentence.

tamigoodall · 2018-05-02T21:10:01Z

README.md

-### from 0.6.6
+- Maintain the minimum PHP version (found under `require.php` in `composer.json`)
+- Code to the [PSR-2 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
+- Write tests and run them with `composer test`


Suggested change: Add a period at the end of the sentence.

tamigoodall · 2018-05-02T21:10:13Z

README.md

+- Maintain the minimum PHP version (found under `require.php` in `composer.json`)
+- Code to the [PSR-2 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
+- Write tests and run them with `composer test`
+- Keep PRs focused and change the minimum number of lines to achieve your goal


Suggested change: Add a period at the end of the sentence.

tamigoodall · 2018-05-02T21:11:32Z

README.md

-4. Configure the callback url to point `{your-base-url}\callback.php`.
-5. Open `examples/{example-name}/config.php` and replace all placeholder parameters.
-6. On your browser, open the Auth0 example project. Make sure `index.php` is being loaded.
+- download this CA database `https://curl.haxx.se/ca/cacert.pem` to `c:/cacert.pem`


Suggested change: Download this CA database https://curl.haxx.se/ca/cacert.pem to c:/cacert.pem.

tamigoodall · 2018-05-02T21:11:50Z

README.md

-5. Open `examples/{example-name}/config.php` and replace all placeholder parameters.
-6. On your browser, open the Auth0 example project. Make sure `index.php` is being loaded.
+- download this CA database `https://curl.haxx.se/ca/cacert.pem` to `c:/cacert.pem`
+- edit your php.ini and add `openssl.cafile=c:/cacert.pem` (it should point to the file you downloaded)


Suggested change: Edit your php.ini and add openssl.cafile=c:/cacert.pem. (It should point to the file you downloaded.)

jeffreylees · 2018-05-02T21:19:28Z

Anywhere you have the docs site URL https://www.auth0.com/docs/foo/bar or such, you should replace that with local URLs such as /foo/bar.

joshcanhelp · 2018-05-02T21:42:33Z

@jeffreylees - This is not a docs page so that's not possible :)

jeffreylees · 2018-05-02T21:43:11Z

Oh, I’m an idiot, thanks for not also being an idiot :D

…

On May 2, 2018, at 5:42 PM, Josh Cunningham ***@***.***> wrote: @jeffreylees <https://github.com/jeffreylees> - This is not a docs page so that's not possible :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACnNXH5NeNJYQb2-8UuUhU9JFapQPSwWks5tuihLgaJpZM4TvttX>.

joshcanhelp · 2018-05-02T22:01:29Z

@tamigoodall - All fixed up, great suggestions, thank you!

lbalmaceda

enjoy 🦀

lbalmaceda · 2018-05-03T15:36:30Z

README.md

+
+For more details about how to install this SDK into an existing project or how to download a preconfigured seed project, see:
+
+* [Basic PHP application quickstart](https://auth0.com/docs/quickstart/webapp/php/)


I'd remove "basic"

lbalmaceda · 2018-05-03T15:41:28Z

README.md

+AUTH0_MANAGEMENT_AUDIENCE="https://${AUTH0_DOMAIN}/api/v2/"
+
+# API token for accessing the Management API (not required for authentication calls)
+AUTH0_MANAGEMENT_API_TOKEN="App token goes here"


App or API?

lbalmaceda · 2018-05-03T15:45:32Z

README.md

+
+## Usage - Authentication API
+
+This SDK provides easy-to-implement methods to access the [Authentication API](https://auth0.com/docs/api/authentication). Some common authentication operations are explained below with examples. For additional information and capabilities, please see the methods in the `\Auth0\SDK\API\Authentication` class. Avoid using any methods marked `@deprecated` as they will be removed in the next major version and may not be enabled for your account.


Avoid using any methods marked @deprecated

A warning should be added for "public but internal methods". Does that apply for this SDK as well?

No. WP is like that because the hooks system needs a public function to call.

lbalmaceda · 2018-05-03T15:46:49Z

README.md

+
+This SDK provides easy-to-implement methods to access the [Authentication API](https://auth0.com/docs/api/authentication). Some common authentication operations are explained below with examples. For additional information and capabilities, please see the methods in the `\Auth0\SDK\API\Authentication` class. Avoid using any methods marked `@deprecated` as they will be removed in the next major version and may not be enabled for your account.
+
+The examples below assume that you followed the installation steps above and are using a `.env` file and loader to store credentials.


I guess you meant something like the https://github.com/josegonzalez/php-dotenv you mentioned before. Maybe it's easier to copy-paste that paragraph here for people skipping that section and going straight to authentication.

I'll add a direct link to the top. I'd rather not repeat steps here as the getenv() function is used throughout.

lbalmaceda · 2018-05-03T15:50:47Z

README.md


+The PHP SDK handles most of the previous steps. Your application needs to:
+
+1. Determine a log in action (for example: click a link, visit walled content, etc.) and call  `Auth0::login()`


visit walled content

what do you mean?

auth-required

lbalmaceda · 2018-05-03T19:23:09Z

README.md

+
+In order to use the Management API, you must authenticate one of two ways:
+
+- For temporary access or testing, you can [manually generate an API token](https://auth0.com/docs/api/management/v2/tokens#get-a-token-manually) and save it in your `.env` file


I'd add a warning stating that the tokens cannot be revoked once generated, and that they will be valid until the expiration time specified on the text field next to the "regenerate token" button of the MGMT API's settings page. The doc page is already linked so that's OK.

I'll leave the details to that docs link

auth0/docs#6138

lbalmaceda · 2018-05-03T19:23:49Z

README.md

+In order to use the Management API, you must authenticate one of two ways:
+
+- For temporary access or testing, you can [manually generate an API token](https://auth0.com/docs/api/management/v2/tokens#get-a-token-manually) and save it in your `.env` file
+- For extended access, you can create and execute and Client Credentials grant (detailed above) when access is required


if by "above" you meant the doc, say instead "detailed in the link above" as this sounds more like "above in this readme"

It does mean "above in this readme" but I'll add a link as well 👍

lbalmaceda · 2018-05-03T19:26:30Z

README.md

-The auth0 domain, is the one you pick when you created your auth0 account.
-You need to set this callback url in your app allowed callbacks.
-The app token is used in the 'create user' page and needs `create:users` scope. To create one, you need to use the token generator in the [API V2 documentation page](https://auth0.com/docs/apiv2)
+The `Management` class stores access to endpoints as properties of its instances. The best way to see what endpoints are covered is to read through the `\Auth0\SDK\API\Management::__construct()` method. 


I'm not saying you're lazy for not listing them, but a short list would probably be better. Check how I'm doing that in java. This comment is tied to the "official API documentation" one above

Thank you for not saying I'm lazy ... this already took more than a day (not including review comments 😆 )!

I need to generate a list of what's covered but I don't think it's essential for this re-write. I have this task captured on my end.

lbalmaceda · 2018-05-03T19:29:00Z

README.md

+- `APP_CLIENT_ID` - Client ID for the test Application
+- `APP_CLIENT_SECRET` - Client Secret for the test Application
+- `GLOBAL_CLIENT_ID` - Client ID for your tenant (found in Tenant > Settings > Advanced)
+- `GLOBAL_CLIENT_SECRET` - Client Secret for your tenant (found in Tenant > Settings > Advanced)


Just below this I'd add "note that the .env file is added to the .gitignore file so it's not commited." or something like that :D

lbalmaceda · 2018-05-03T19:30:03Z

README.md


-## Configure example
+This is a common issue with latest PHP versions under windows (related to a incompatibility between windows and openssl CAs database).


Windows OS (capital, bold)

lbalmaceda · 2018-05-04T20:31:19Z

README.md

@@ -95,7 +95,7 @@ echo 'My Auth0 domain is ' . getenv('AUTH0_DOMAIN') . '!';

 This SDK provides easy-to-implement methods to access the [Authentication API](https://auth0.com/docs/api/authentication). Some common authentication operations are explained below with examples. For additional information and capabilities, please see the methods in the `\Auth0\SDK\API\Authentication` class. Avoid using any methods marked `@deprecated` as they will be removed in the next major version and may not be enabled for your account.

-The examples below assume that you followed the installation steps above and are using a `.env` file and loader to store credentials.
+The examples below assume that you followed the steps in the [Installation section](#installation) section above and are using a `.env` file and loader to store credentials.


section section

github-actions · 2022-08-24T00:20:42Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

Rewrite README; add news and notes to CHANGELOG

a1c6afa

joshcanhelp added the CH: Fixed label May 2, 2018

joshcanhelp added this to the v5-Next milestone May 2, 2018

joshcanhelp commented May 2, 2018

View reviewed changes

joshcanhelp requested a review from tamigoodall May 2, 2018 17:46

tamigoodall suggested changes May 2, 2018

View reviewed changes

Docs team PR feedback

f10484d

lbalmaceda suggested changes May 3, 2018

View reviewed changes

lbalmaceda reviewed May 4, 2018

View reviewed changes

PR review changes

edae4bf

joshcanhelp force-pushed the fix-readme branch from 1771742 to edae4bf Compare May 4, 2018 20:36

lbalmaceda approved these changes May 4, 2018

View reviewed changes

joshcanhelp merged commit 909e6da into master May 4, 2018

joshcanhelp deleted the fix-readme branch May 4, 2018 21:31

github-actions bot locked as resolved and limited conversation to collaborators Aug 24, 2022


		## Security Upgrade Notes 5.1.0+
		Include the Composer autoload file in your project and you're ready to use the SDK:


		### Decoding and verifying tokens
		1. Go to [auth0.com/signup](https://auth0.com/signup) and create your account


		For more details about how to install this SDK into an existing project or how to download a preconfigured seed project, see:

		* [Basic PHP application quickstart](https://auth0.com/docs/quickstart/webapp/php/)


		## Usage - Authentication API

		This SDK provides easy-to-implement methods to access the [Authentication API](https://auth0.com/docs/api/authentication). Some common authentication operations are explained below with examples. For additional information and capabilities, please see the methods in the `\Auth0\SDK\API\Authentication` class. Avoid using any methods marked `@deprecated` as they will be removed in the next major version and may not be enabled for your account.


		This SDK provides easy-to-implement methods to access the [Authentication API](https://auth0.com/docs/api/authentication). Some common authentication operations are explained below with examples. For additional information and capabilities, please see the methods in the `\Auth0\SDK\API\Authentication` class. Avoid using any methods marked `@deprecated` as they will be removed in the next major version and may not be enabled for your account.

		The examples below assume that you followed the installation steps above and are using a `.env` file and loader to store credentials.


		The PHP SDK handles most of the previous steps. Your application needs to:

		1. Determine a log in action (for example: click a link, visit walled content, etc.) and call `Auth0::login()`


		In order to use the Management API, you must authenticate one of two ways:

		- For temporary access or testing, you can [manually generate an API token](https://auth0.com/docs/api/management/v2/tokens#get-a-token-manually) and save it in your `.env` file


		## Configure example
		This is a common issue with latest PHP versions under windows (related to a incompatibility between windows and openssl CAs database).

Rewrite README; add news and notes to CHANGELOG #253

Rewrite README; add news and notes to CHANGELOG #253

Conversation

joshcanhelp commented May 2, 2018 • edited Loading

Choose a reason for hiding this comment

tamigoodall left a 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeffreylees commented May 2, 2018

joshcanhelp commented May 2, 2018

jeffreylees commented May 2, 2018 via email

joshcanhelp commented May 2, 2018

lbalmaceda left a 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

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

joshcanhelp May 3, 2018 • edited Loading

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

github-actions bot commented Aug 24, 2022

joshcanhelp commented May 2, 2018 •

edited

Loading

joshcanhelp May 3, 2018 •

edited

Loading