Skip to content

Commit 8b82c5b

Browse files
datamwebdatamweb
authored
Merge pull request #35 from sammyskills/make-oauth
Dev: Make command to create new OAuth
2 parents 01de7b1 + e8804a8 commit 8b82c5b

File tree

4 files changed

+536
-51
lines changed

4 files changed

+536
-51
lines changed

‎docs/add_other_oauth.md

Lines changed: 186 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,202 @@
1-
# Add New OAuth To Shield OAuth
1+
# Adding New OAuth To Shield OAuth
22

3-
As you know, `Shield OAuth` supports `Google OAuth` and `Github OAuth` by default. But you can connect any server that offers `OAuth` to it.
4-
It is very simple, first, create a file named `NewOAuth` in path `app\Libraries\ShieldOAuth`. Existence of extension `OAuth` is mandatory in creating each new class. For example, if you want to add Yahoo, you should create a file named `YahooOAuth` in path `app\Libraries\ShieldOAuth`.
3+
Shield OAuth supports *Google OAuth* and *Github OAuth* out-of-the-box and also provides an easy way to connect any server that offers **OAuth** to it. This guide explains how to achieve this.
54

6-
Implement methods `makeGoLink($state)`, `fetchAccessTokenWithAuthCode($allGet)`, `fetchUserInfoWithToken()` and `setColumnsName(string $nameOfProcess, $userInfo)` according to the documents of each server.
5+
- [Adding New OAuth to Shield OAuth](#adding-new-oauth-to-shield-oauth)
6+
- [Setup Instruction](#setup-instruction)
7+
- [Command Setup](#command-setup)
8+
- [Manual Setup](#manual-setup)
79

8-
`NewOAuth` have only one requirement: they must extends `Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth`.
10+
## Setup Instruction
911

10-
The `AbstractOAuth` defines four methods for `NewOAuth`:
12+
### Command Setup
1113

12-
1. `makeGoLink($state)` In this method, you need to create a link to transfer the user to the new provider. The output of this method is a `string` in the form of URL. For example, regarding Yahoo, you can follow the instructions available [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-2-get-an-authorization-url-and-authorize-access) to create this link.
13-
14-
2. `fetchAccessTokenWithAuthCode($allGet)` In this method, you should try to get the value of `access_token` according to the code received from the previous method. The output of this method is of `void`. For Yahoo, you can see the description [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-4-exchange-authorization-code-for-access-token). Everything is ready, just replace.
14+
1. Run the following command. This command handles steps 1 - 3 of *Manual Setup*.
1515

16-
3. `fetchUserInfoWithToken()` In this method, you try to receive user information (including first name, last name, email, etc) according to the token code set in the previous step.The output of this method is a `object` of user info(email, name, ...). See [here](https://developer.yahoo.com/oauth2/guide/OpenID2) for more details about Yahoo.
16+
```console
17+
php spark make:oauth Example
18+
```
1719

18-
4. `setColumnsName(string $nameOfProcess, $userInfo)` In this method, you set the fields received from each service OAuth to be recorded in each column of the table.
20+
> **Note** The name of the new OAuth you want to create doesn't need to contain the `OAuth` suffix. The command will automatically add it to the class name for you.
21+
22+
This command will automatically generate new files *ExampleOAuth.php*, *ShieldOAuthLang.php* in the **app/Libraries/ShieldOAuth**, **app/Language/en** paths respectively and also update the *ShieldOAuthConfig.php* file in the **app/Config** path.
23+
24+
> **Note** The *ShieldOAuthConfig.php* file must be present in your **app/Config** path for this command to run successfully. So ensure that you have run the `make:oauthconfig` command first, as stated [here](install.md#set-keys).
25+
26+
2. Configure the files.
27+
28+
```php
29+
// updated file - app/Config/ShieldOAuthConfig.php
30+
<?php
31+
public array $oauthConfigs = [
32+
// ..
33+
'example' => [
34+
'client_id' => 'Get this from the OAuth server',
35+
'client_secret' => 'Get this from the OAuth server',
36+
37+
'allow_login' => true
38+
],
39+
];
40+
41+
```
42+
43+
```php
44+
// new file - app/Libraries/ShieldOAuth/ExampleOAuth.php
45+
<?php
46+
47+
declare(strict_types=1);
48+
49+
namespace App\Libraries\ShieldOAuth;
50+
51+
use Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth;
52+
53+
class ExampleOAuth extends AbstractOAuth
54+
{
55+
private static $API_CODE_URL = '';
56+
private static $API_TOKEN_URL = '';
57+
private static $API_USER_INFO_URL = '';
58+
private static $APPLICATION_NAME = 'ShieldOAuth';
59+
60+
protected string $token;
61+
protected string $client_id;
62+
protected string $client_secret;
63+
protected string $callback_url;
64+
65+
public function __construct(string $token = '')
66+
{
67+
// your code here
68+
}
69+
70+
public function makeGoLink(string $state): string
71+
{
72+
// your code here
73+
return '';
74+
}
75+
76+
public function fetchAccessTokenWithAuthCode(array $allGet): void
77+
{
78+
// your code here
79+
}
1980

20-
I have given an example for Yahoo below:
81+
public function fetchUserInfoWithToken(): object
82+
{
83+
// your code here
84+
return json_decode('');
85+
}
2186

22-
- [Writing Class Yahoo OAuth](#writing-class-yahoo-oauth)
23-
- [Add Keys To Config File](#add-keys-to-config-file)
24-
- [Add lang file](#add-lang-file)
87+
public function setColumnsName(string $nameOfProcess, object $userInfo): array
88+
{
89+
// your code here
90+
return [];
91+
}
92+
}
93+
```
2594

95+
> See [YahooOAuth](#yahoooauth-example-class) example for full code.
2696
27-
## Writing Class Yahoo OAuth
97+
### Manual Setup
2898

29-
Create a file in path `app\Libraries\ShieldOAuth\YahooOAuth.php` with the following contents.
99+
1. Create a file *ExampleOAuth* in the **app/Libraries/ShieldOAuth** path with the following contents. The **OAuth** suffix is mandatory in creating each new class. For example, if you want to add Yahoo, you should create a file named **YahooOAuth**.
30100

31101
```php
102+
<?php
103+
104+
declare(strict_types=1);
105+
106+
namespace App\Libraries\ShieldOAuth;
107+
108+
use Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth;
109+
110+
class ExampleOAuth extends AbstractOAuth
111+
{
112+
private static $API_CODE_URL = '';
113+
private static $API_TOKEN_URL = '';
114+
private static $API_USER_INFO_URL = '';
115+
private static $APPLICATION_NAME = 'ShieldOAuth';
116+
117+
protected string $token;
118+
protected string $client_id;
119+
protected string $client_secret;
120+
protected string $callback_url;
32121

122+
public function __construct(string $token = '')
123+
{
124+
// your code here
125+
}
126+
127+
public function makeGoLink(string $state): string
128+
{
129+
// your code here
130+
return '';
131+
}
132+
133+
public function fetchAccessTokenWithAuthCode(array $allGet): void
134+
{
135+
// your code here
136+
}
137+
138+
public function fetchUserInfoWithToken(): object
139+
{
140+
// your code here
141+
return json_decode('');
142+
}
143+
144+
public function setColumnsName(string $nameOfProcess, object $userInfo): array
145+
{
146+
// your code here
147+
return [];
148+
}
149+
}
150+
```
151+
152+
> See [YahooOAuth](#yahoooauth-example-class) example for full code.
153+
154+
2. **Config Setup** Add the new OAuth config keys to the **app/Config/ShieldOAuthConfig.php** file.
155+
156+
```php
157+
<?php
158+
public array $oauthConfigs = [
159+
//...
160+
'example' => [
161+
'client_id' => 'Get this from the OAuth server',
162+
'client_secret' => 'Get this from the OAuth server',
163+
164+
'allow_login' => true
165+
],
166+
//...
167+
];
168+
169+
```
170+
171+
3. **Language setup** Add the following values to the **app/Language/en/ShieldOAuthLang.php** file. Create the file if it doesn't exist.
172+
173+
```php
174+
return [
175+
// ...
176+
'Example' => [
177+
'not_allow' => 'Now you can\'t login or register with Example!',
178+
'example' => 'Example',
179+
],
180+
// ...
181+
];
182+
```
183+
184+
4. **Translations** Depending on the requirements of your application, you can translate the language file using the same keys, in as many languages as possible. See [CodeIgniter docs](https://codeigniter.com/user_guide/outgoing/localization.html#creating-language-files) for more information. Also note that the file name for each language must be **ShieldOAuthLang.php**.
185+
186+
## Available Methods
187+
188+
Your new *OAuth* file/class has just one requirement. It must extend `Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth`. The abstract class `AbstractOAuth` implement methods `makeGoLink($state)`, `fetchAccessTokenWithAuthCode($allGet)`, `fetchUserInfoWithToken()` and `setColumnsName(string $nameOfProcess, $userInfo)`, which should be built according to the documentation of each server.
189+
190+
The `AbstractOAuth` defines four methods for your usage:
191+
192+
1. `makeGoLink($state)` In this method, you need to create a link to transfer the user to the new provider. The output of this method is a `string` in the form of URL. For example, regarding Yahoo, you can follow the instructions available [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-2-get-an-authorization-url-and-authorize-access) to create this link.
193+
2. `fetchAccessTokenWithAuthCode($allGet)` In this method, you should try to get the value of `access_token` according to the code received from the previous method. The output of this method is of `void`. For Yahoo, you can see the description [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-4-exchange-authorization-code-for-access-token). Everything is ready, just replace.
194+
3. `fetchUserInfoWithToken()` In this method, you try to receive user information (including first name, last name, email, etc) according to the token code set in the previous step.The output of this method is a `object` of user info(email, name, ...). See [here](https://developer.yahoo.com/oauth2/guide/OpenID2) for more details about Yahoo.
195+
4. `setColumnsName(string $nameOfProcess, $userInfo)` In this method, you set the fields received from each service OAuth to be recorded in each column of the table.
196+
197+
## YahooOAuth Example Class
198+
199+
```php
33200
<?php
34201

35202
declare(strict_types=1);
@@ -88,15 +255,15 @@ class YahooOAuth extends AbstractOAuth
88255
],
89256
'http_errors' => false,
90257
]);
91-
258+
92259
} catch (Exception $e) {
93260
die($e->getMessage());
94261
}
95262

96263
$token = json_decode($response->getBody())->access_token;
97264
$this->setToken($token);
98265
}
99-
266+
100267
protected function fetchUserInfoWithToken(): object
101268
{
102269
// send request to API URL
@@ -138,37 +305,5 @@ class YahooOAuth extends AbstractOAuth
138305

139306
return $usersColumnsName;
140307
}
141-
142308
}
143-
144-
```
145-
146-
## Add Keys To Config File
147-
For each new OAuth service you create, you must add the following values in file `Config\ShieldOAuthConfig.php`. For Yahoo, it is as follows.
148-
149-
```php
150-
public array $oauthConfigs = [
151-
//...
152-
'yahoo' => [
153-
'client_id' => 'from yahoo ...',
154-
'client_secret' => 'from yahoo ...',
155-
156-
'allow_login' => true
157-
],
158-
//...
159-
];
160309
```
161-
162-
## Add lang file
163-
For each new OAuth service you create, you must add the following values in file `Language\en\ShieldOAuthLang.php` and `Language\fa\ShieldOAuthLang.php`. For Yahoo, it is as follows.
164-
165-
```php
166-
return [
167-
// ...
168-
'Yahoo' => [
169-
'not_allow' => 'Now you can\'t login or register with Yahoo!',
170-
'yahoo' => 'Yahoo',
171-
],
172-
// ...
173-
];
174-
```

0 commit comments

Comments
 (0)