refactor(console): update python and php guide (#6136)

* refactor(console): update python/php console guide * refactor(console): improve php guide * refactor(console): improve python guide --------- Co-authored-by: Gao Sun <[email protected]>
logto-io · Jun 29, 2024 · 16be0f9 · 16be0f9
1 parent 97b8201
commit 16be0f9
Show file tree

Hide file tree

Showing 3 changed files with 162 additions and 117 deletions.
diff --git a/packages/console/src/assets/docs/fragments/_redirect-uris-web.mdx b/packages/console/src/assets/docs/fragments/_redirect-uris-web.mdx
@@ -3,13 +3,17 @@ import UriInputField from '@/mdx-components/UriInputField';
 
 import ExperienceOverview from './_experience-overview.md';
 
+export const defaultOrigin = 'http://localhost:3000/';
+export const defaultCallbackUri = `${defaultOrigin}callback`;
+export const defaultPostSignOutUri = defaultOrigin;
+
 <ExperienceOverview />
 
 <InlineNotification>
-  In the following steps, we assume your app is running on <code>http://localhost:3000</code>.
+  In the following steps, we assume your app is running on <code>{defaultOrigin}</code>.
 </InlineNotification>
 
-Now, let's configure your redirect URI. E.g. {`${props.defaultUri ?? 'http://localhost:3000/callback'}`}.
+Now, let's configure your redirect URI. E.g. {`${props.defaultUri ?? defaultCallbackUri}`}.
 
 <UriInputField name="redirectUris" />
 

diff --git a/packages/console/src/assets/docs/guides/web-php/README.mdx b/packages/console/src/assets/docs/guides/web-php/README.mdx
@@ -4,17 +4,18 @@ import TabItem from '@mdx/components/TabItem';
 import InlineNotification from '@/ds-components/InlineNotification';
 import Steps from '@/mdx-components/Steps';
 import Step from '@/mdx-components/Step';
+import Checkpoint from '../../fragments/_checkpoint.md';
+import RedirectUrisWeb, { defaultCallbackUri, defaultPostSignOutUri } from '../../fragments/_redirect-uris-web.mdx';
 
 <Steps>
 
 <Step title="Get started">
 
 This tutorial will show you how to integrate Logto into your PHP web application.
 
-<ul>
-  <li>The example uses Laravel, but the concepts are the same for other frameworks.</li>
-  <li>This tutorial assumes your website is hosted on <code>{props.sampleUrls.origin}</code>.</li>
-</ul>
+<InlineNotification>
+  The example uses Laravel, but the concepts are the same for other frameworks.
+</InlineNotification>
 
 ```bash
 composer require logto/sdk
@@ -26,7 +27,7 @@ composer require logto/sdk
 
 Insert the following code into your PHP file:
 
-<Code className="language-php">
+<Code title="index.php" className="language-php">
 {`use logto\sdk\LogtoClient;
 use Logto\Sdk\LogtoConfig;
 
@@ -41,51 +42,28 @@ $client = new LogtoClient(
 
 By default, the SDK uses the built-in PHP session to store the Logto data. If you want to use other storage, you can pass a custom storage object as the second parameter:
 
-```php
-$client = new LogtoClient(
+<Code title="index.php" className="language-php">
+{`$client = new LogtoClient(
   new LogtoConfig(
     // ...
   ),
   new YourCustomStorage(),
-);
-```
+);`}
+</Code>
 
 </Step>
 
 <Step title="Implement the sign-in route">
 
-<p>
-First, let’s enter your redirect URI. E.g. <code>{props.sampleUrls.callback}</code>. This is where Logto will redirect users after they sign in.
-</p>
-
-<UriInputField name="redirectUris" />
-
-<Code className="language-php">
-{`Route::get('/sign-in', function () {
-  return redirect($client->signIn('${props.redirectUris[0] || props.sampleUrls.callback}'));
-});`}
-</Code>
-
-If you want to show the sign-up page on the first screen, you can set `interactionMode` to `signUp`:
-
-<Code className="language-php">
-{`Route::get('/sign-in', function () {
-  return redirect($client->signIn('${props.redirectUris[0] || props.sampleUrls.callback}', InteractionMode::signUp));
-});`}
-</Code>
-
-Now, whenever your users visit `/sign-in`, it will start a new sign-in attempt and redirect the user to the Logto sign-in page.
-
-> **Note**
-> Creating a sign-in route isn't the only way to start a sign-in attempt. You can always use the `signIn` method to get the sign-in URL and redirect the user to it.
+<RedirectUrisWeb />
 
 </Step>
 
-<Step title="Implement the callback route">
+<Step title="Handle the callback">
 
 After the user signs in, Logto will redirect the user to the callback URL you set in the Logto Console. In this example, we use `/callback` as the callback URL:
 
-```php
+```php title="index.php"
 Route::get('/callback', function () {
   try {
     $client->handleSignInCallback(); // Handle a lot of stuff
@@ -98,19 +76,38 @@ Route::get('/callback', function () {
 
 </Step>
 
-<Step title="Implement the sign-out route">
+<Step title="Implement sign-in and sign-out">
 
-To clean up the Python session and Logto session, we can designate a post sign-out redierct URI. This is where Logto will redirect users after they sign out.
+There are various ways to invoke sign-in and sign-out in your application. For example, you can implement two routes in your PHP application:
 
-<UriInputField name="postLogoutRedirectUris" />
+<Code title="index.php" className="language-php">
+{`Route::get('/sign-in', function () {
+  return redirect($client->signIn('${props.redirectUris[0] || defaultCallbackUri}'));
+});`}
+</Code>
+
+If you want to show the sign-up page on the first screen, you can set `interactionMode` to `signUp`:
+
+<Code title="index.php" className="language-php">
+{`Route::get('/sign-in', function () {
+  return redirect($client->signIn('${props.redirectUris[0] || defaultCallbackUri}', InteractionMode::signUp));
+});`}
+</Code>
+
+Now, whenever your users visit `/sign-in`, it will start a new sign-in attempt and redirect the user to the Logto sign-in page.
+
+> **Note**
+> Creating a sign-in route isn't the only way to start a sign-in attempt. You can always use the `signIn` method to get the sign-in URL and redirect the user to it.
+
+To clean up the Python session and Logto session, we can designate a post sign-out redierct URI. This is where Logto will redirect users after they sign out.
 
 And a sign-out route can be implemented as follows:
 
-<Code className="language-php">
+<Code title="index.php" className="language-php">
 {`Route::get('/sign-out', function () {
   return redirect(
     // Redirect the user to the home page after a successful sign-out
-    $client->signOut('${props.postLogoutRedirectUris[0] || props.sampleUrls.origin}')
+    $client->signOut('${props.postLogoutRedirectUris[0] || defaultPostSignOutUri}')
   );
 });`}
 </Code>
@@ -128,7 +125,7 @@ We also need to implement a home page for demonstration:
 - If the user is not signed in, show a sign-in button;
 - If the user is signed in, show some basic information about the user.
 
-```php
+```php title="index.php"
 Route::get('/', function () {
   if ($client->isAuthenticated() === false) {
     return "Not authenticated <a href='/sign-in'>Sign in</a>";
@@ -157,14 +154,30 @@ To learn more about scopes and claims, see [Get user information](https://docs.l
 
 <Step title="Checkpoint: Test your application">
 
-Now, you can test your application:
+<Checkpoint />
+
+</Step>
 
-<ol>
-  <li>Visit <code>{props.sampleUrls.origin}</code>, and you should see a "Not authenticated" message with a "Sign in" button.</li>
-  <li>Click the "Sign in" button, and you should be redirected to the Logto sign-in page.</li>
-  <li>After you sign in, you should be redirected back to <code>{props.sampleUrls.origin}</code>, and you should see your user info and a "Sign out" button.</li>
-  <li>Click the "Sign out" button, and you should be redirected back to <code>{props.sampleUrls.origin}</code>, and you should see a "Not authenticated" message with a "Sign in" button.</li>
-</ol>
+<Step title="Display user information">
+
+To display the user's information, you can use either the `getIdTokenClaims` method or `fetchUserInfo` method to get user information. While `getIdTokenClaims` returns the user information contains in the ID token, `fetchUserInfo` fetches the user information from the userinfo endpoint.
+
+```php title="index.php"
+Route::get('/userinfo', function () {
+  if ($client->isAuthenticated() === false) {
+    return "Not authenticated <a href='/sign-in'>Sign in</a>";
+  }
+
+  return (
+    // Get local ID token claims
+    json_decode($client->getIdTokenClaims())
+    . "<br>"
+    // Fetch user info from Logto userinfo endpoint
+    json_decode($client->fetchUserInfo())
+    . "<br>"
+  );
+});
+```
 
 </Step>