The Descope SDK for PHP provides convenient access to Descope authentication. You can read more on the Descope Website.
Install the package with Composer:
composer require descope/descope-php
You'll need to set up a .env file in the root directory with your Descope Project ID, which you can get from the Console like this:
DESCOPE_PROJECT_ID=<Descope Project ID>
DESCOPE_MANAGEMENT_KEY=<Descope Management Key>
In order to use the SDK you will need to initialize a DescopeSDK object with your Descope Project ID you defined in your .env file, like this:
require 'vendor/autoload.php';
use Descope\SDK\DescopeSDK;
$descopeSDK = new DescopeSDK([
'projectId' => $_ENV['DESCOPE_PROJECT_ID'],
'managementKey' => $_ENV['DESCOPE_MANAGEMENT_KEY'] // Optional, only used for Management functions
]);The Descope PHP SDK uses a caching mechanism to store frequently accessed data, such as JSON Web Key Sets (JWKs) for session token validation. By default, the SDK uses APCu for caching, provided it is enabled and configured in your environment. If APCu is not available, and no other caching mechanism is provided, caching is disabled.
By using the CacheInterface, you can integrate the Descope PHP SDK with any caching mechanism that suits your application, ensuring optimal performance in both small and large-scale deployments.
The SDK allows you to provide a custom caching mechanism by implementing the CacheInterface. This interface defines three methods that any cache implementation should support:
get(string $key): Retrieve a value by key.set(string $key, $value, int $ttl = 3600): bool: Store a value with a specified time-to-live (TTL).delete(string $key): bool: Remove a value by key.
You can provide your custom caching implementation by creating a class that implements CacheInterface. Here’s an example using Laravel’s cache system:
namespace App\Cache;
use Descope\SDK\Cache\CacheInterface;
use Illuminate\Support\Facades\Cache;
class LaravelCache implements CacheInterface
{
public function get(string $key)
{
return Cache::get($key);
}
public function set(string $key, $value, int $ttl = 3600): bool
{
// Laravel TTL is in minutes
return Cache::put($key, $value, max(1, ceil($ttl / 60)));
}
public function delete(string $key): bool
{
return Cache::forget($key);
}
}To use the Laravel cache in the SDK:
use Descope\SDK\DescopeSDK;
use App\Cache\LaravelCache;
$descopeSDK = new DescopeSDK([
'projectId' => $_ENV['DESCOPE_PROJECT_ID'],
'managementKey' => $_ENV['DESCOPE_MANAGEMENT_KEY'],
], new LaravelCache());Once you've configured your caching, you're ready to use the SDK. This SDK will easily allow you integrate Descope functionality with the following built-in functions:
$response = $descopeSDK->auth->password->signUp("loginId", "password123");
print_r($response);$response = $descopeSDK->auth->password->signIn("loginId", "password123");
print_r($response);$response = $descopeSDK->auth->password->sendReset("loginId", "https://example.com/reset");
print_r($response);$descopeSDK->auth->password->update("loginId", "newPassword123", "refreshToken");$response = $descopeSDK->auth->password->replace("loginId", "oldPassword123", "newPassword123");
print_r($response);$response = $descopeSDK->auth->password->getPolicy();
print_r($response);$response = $descopeSDK->auth->sso->signIn(
"tenant",
"https://example.com/callback",
"prompt",
true,
true,
["custom" => "claim"],
"ssoAppId"
);
print_r($response);$response = $descopeSDK->auth->sso->exchangeToken("code");
print_r($response);DescopeSDK->verify($sessionToken)- will validate the session token and return either TRUE or FALSE, depending on if the JWT is valid and expired.DescopeSDK->refreshSession($refreshToken)- will refresh your session and return a new session token, with the refresh token.DescopeSDK->verifyAndRefreshSession($sessionToken, $refreshToken)- will validate the session token and return either TRUE or FALSE, and will refresh your session and return a new session token.DescopeSDK->logout($refreshToken)- will invalidate the refresh token and log the user out of the current session.DescopeSDK->logoutAll($refreshToken)- will invalidate all refresh tokens associated with a given project, thereby signing out of all sessions across multiple applications.
DescopeSDK->getClaims($sessionToken)- will return all of the claims from the JWT in an array format.DescopeSDK->getUserDetails($refreshToken)- will return all of the user information (email, phone, verification status, etc.) using a provided refresh token.
Each of these functions have code examples on how to use them.
Some of these values may be incorrect for your environment, they exist purely as an example for your own implementation.
$response = $descopeSDK->management->user->create(
'testuser1', // loginId
'[email protected]', // email
'+1234567890', // phone
'Updated User', // displayName
'Updated', // givenName
'Middle', // middleName
'User', // familyName
null, // picture
null, // customAttributes
true, // verifiedEmail
true, // verifiedPhone
null, // inviteUrl
['altUser1'], // additionalLoginIds
['app123'], // ssoAppIds
null, // password
['admin', 'editor'], // roleNames
[['tenantId' => 'tenant1']] // userTenants
);
print_r($response);$response = $descopeSDK->management->user->update(
'testuser1', // loginId
'[email protected]', // email
'+1234567890', // phone
'Updated User', // displayName
'Updated', // givenName
'Middle', // middleName
'User', // familyName
'https://example.com/newpic.jpg', // picture
['department' => 'HR'], // customAttributes
true, // verifiedEmail
true, // verifiedPhone
['altUser1'], // additionalLoginIds
[''], // ssoAppIds
);$response = $descopeSDK->management->user->invite(
'newuser1', // loginId
'[email protected]', // email
'+1234567890', // phone
'New User', // displayName
'John', // givenName
'Middle', // middleName
'Doe', // familyName
'https://example.com/profile.jpg', // picture
['department' => 'Engineering'], // customAttributes
true, // verifiedEmail
true, // verifiedPhone
'https://myapp.com/invite', // inviteUrl
true, // sendMail
true // sendSms
);
print_r($response);$users = [
new Descope\SDK\Management\UserObj(
'batchuser1', // loginId
'[email protected]', // email
null, // phone
'Batch User One', // displayName
null, // givenName
null, // middleName
null, // familyName
['admin'], // roleNames
[['tenantId' => 'tenant1']] // userTenants (can be an empty array if no tenant)
),
new Descope\SDK\Management\UserObj(
'batchuser2', // loginId
'[email protected]', // email
null, // phone
'Batch User Two', // displayName
null, // givenName
null, // middleName
null, // familyName
['viewer'], // roleNames
[['tenantId' => 'tenant2']] // userTenants (can be an empty array if no tenant)
)
];
$response = $descopeSDK->management->user->inviteBatch(
$users,
'https://myapp.com/batch-invite', // inviteUrl
true, // sendMail
true // sendSms
);
print_r($response);$descopeSDK->management->user->delete("testuser1");$response = $descopeSDK->management->user->searchAll(
"", // loginId
[], // tenantIds
['admin', 'viewer'], // roleNames
50, // limit
"", // text
1, // page
false, // ssoOnly
false, // testUsersOnly
false, // withTestUser
null, // customAttributes
['enabled'], // statuses
['[email protected]'], // emails
['+1234567890'], // phones
['ssoApp123'], // ssoAppIds
[ // sort
['field' => 'displayName', 'desc' => true]
]
);
print_r($response);$response = $descopeSDK->management->user->addTenant("testuser1", "tenantId1");
print_r($response);$response = $descopeSDK->management->user->removeTenant("testuser1", "tenantId1");
print_r($response);$response = $descopeSDK->management->user->setTenantRoles("testuser1", "tenantId1", ["admin"]);
print_r($response);$response = $descopeSDK->management->user->addTenantRoles("testuser1", "tenantId1", ["user"]);
print_r($response);$response = $descopeSDK->management->user->removeTenantRoles("testuser1", "tenantId1", ["admin"]);
print_r($response);$descopeSDK->management->user->setTemporaryPassword("testuser1", new UserPassword(cleartext: "temporaryPassword123"));$descopeSDK->management->user->setActivePassword("testuser1", new UserPassword(cleartext: "activePassword123"));$descopeSDK->management->user->setPassword("testuser1", new UserPassword(cleartext: "password123"), true);The PHP directory includes unit testing using PHPUnit. You can insert values for session token and refresh tokens in the src/tests/DescopeSDKTest.php file, and run to validate whether or not the functions are operating properly.
To run the tests, run this command:
./vendor/bin/phpunit --bootstrap bootstrap.php --verbose src/tests/DescopeSDKTest.php
In the sample/static/descope.js, replace the projectId with your Descope Project ID, which you can find in the Descope Console.
If you haven't already, make sure you run the composer command listed above, to install the necessary SDK packages.
Then, run this command from the root directory, to start the sample app:
php -S localhost:3000 -t sample/
The app should now be accessible at http://localhost:3000/ from your web browser.
This sample app showcases a Descope Flow using the WebJS SDK and PHP sessions to retain user information across multiple pages. It also showcases initializing the SDK and using it to validate the session token from formData sent from login.php.
We appreciate feedback and contribution to this repository!
To provide feedback or report a bug, please raise an issue on our issue tracker.
This project is licensed under the MIT license. See the LICENSE file for more info.