Download the PHP package casdoor/casdoor-php-sdk without Composer

Casdoor PHP SDK

Casdoor PHP SDK is the official PHP client library for Casdoor. It lets your PHP backend (Laravel, Symfony, plain PHP, ...) sign users in with Casdoor (OAuth 2.0 / OIDC), verify the JWT tokens issued by Casdoor, and manage users, organizations, applications, roles, permissions and all the other Casdoor objects through the Casdoor APIs.

The SDK has the same features as casdoor-go-sdk.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Authentication
• Resource Management
• API Reference
• Examples
• Development
• Documentation
• License

✨ Features

• OAuth 2.0 Authentication: authorization code, password and refresh token grants, token introspection, SSO logout
• JWT Verification: verify the tokens signed by Casdoor (RS256, RS512, ES256, ES384, ES512)
• Calling APIs as the User: withAccessToken() calls the APIs with the user's own permissions
• User Management: CRUD, lookup by email / phone / user ID, pagination, password check and change
• Organization & Application Management: organizations, applications, groups, certificates, providers, LDAP
• Authorization: roles, permissions, models, adapters, enforcers, policies, enforce() and batchEnforce()
• Billing: products, orders, payments, plans, pricings, subscriptions and transactions
• Messaging: send emails, SMS and notifications
• Multi-Factor Authentication (MFA): TOTP, email and SMS MFA setup
• Other Objects: sessions, tokens, webhooks, syncers, invitations, resources (file upload) and records
• PHP 8.0+

📦 Installation

🚀 Quick Start

⚙️ Configuration

Configuration Parameters

Getting the Configuration from Casdoor

1. endpoint: the URL of your Casdoor server
2. clientId and clientSecret: the application's edit page in the Casdoor admin panel
3. certificate: the certificate of the cert selected in the application's "Cert" field (Certs page → the cert → "Certificate")
4. organizationName: the organization that owns your users
5. applicationName: the name of your application

Custom HTTP Headers

The Authorization header is always managed by the SDK.

Return Values and Errors

• getXxxs() and getXxx() return the objects as associative arrays decoded from Casdoor's JSON, getXxx() returns null when the object doesn't exist
• getPaginationXxxs() returns [$objects, $totalCount]
• addXxx(), updateXxx() and deleteXxx() take the entity classes (Casdoor\User, Casdoor\Role, ...) and return true when the object is changed
• The methods throw Casdoor\Exceptions\CasdoorException with Casdoor's error message when Casdoor returns an error

🔐 Authentication

OAuth 2.0 Flow

Step 1: Redirect the User to Casdoor

getSignupUrl($enablePassword, $redirectUri), getUserProfileUrl($userName, $accessToken) and getMyProfileUrl($accessToken) build the URLs of the other Casdoor pages.

Step 2: Handle the Callback

Casdoor redirects back to your application with code and state. Exchange the code for the tokens and verify the access token:

getOAuthToken() returns a league/oauth2-client AccessToken. parseJwtToken() verifies the signature and the expiration of the token with the certificate, and throws an exception when the token is invalid.

Password Grant, Impersonation and Token Refresh

Calling APIs With the User's Access Token

By default, the SDK calls the Casdoor APIs as the application itself: it authenticates with the client ID and client secret, so the calls have the application's (admin) permissions.

To call the APIs on behalf of the signed-in user instead, use withAccessToken() with the user's access token. It returns a new client that sends the Authorization: Bearer <access_token> header, so Casdoor treats the requests as being made by that user and the user's own permissions apply:

The original client is not changed, so it's safe to create one such client per incoming HTTP request.

Note: a non-admin user can only access their own data. If an API throws a permission error, the user simply isn't allowed to call it — use the application's client (without withAccessToken()) for admin operations.

Logout

📦 Resource Management

Object Owner

Every object in Casdoor is identified by an ID of the form owner/name, where the owner is an organization (role, group, user, product, ldap, ...) or the built-in admin owner (organization, application, token).

By default the SDK fills in the owner for you: the organizationName of the client, or admin for the object types listed above. You can address an object in another organization by passing a qualified owner/name ID instead of a plain name, and by setting the owner field explicitly when creating or updating an object:

[!IMPORTANT] Behavior change: addXxx(), updateXxx() and deleteXxx() used to overwrite the owner field of the object with the client's organization, and to ignore any owner set by the caller. They now only fill owner in when it is empty. If your code sets owner to a value other than the client's organization (for example the literal 'admin'), the request is now sent to that owner instead of being silently redirected, so clear the field or set it to the intended organization.

Method Patterns

Most objects have the same methods:

• getXxxs() - get all the objects of the organization
• getPaginationXxxs($p, $pageSize, $queryMap = []) - get a page of the objects, returns [$objects, $total]. $queryMap can filter and sort, e.g. ['field' => 'name', 'value' => 'abc', 'sortField' => 'createdTime', 'sortOrder' => 'descend']
• getXxx($name) - get an object by name (or owner/name ID)
• addXxx($object) - create an object
• updateXxx($object) - update an object
• updateXxxForColumns($object, $columns) - only update the given columns (users, roles, permissions, sessions, tokens, invitations)
• deleteXxx($object) - delete an object

Users

Permissions and Enforcement

Enforcers and Policies

Billing: Products, Orders, Payments and Transactions

Email, SMS and Notifications

Resources (File Upload)

LDAP

Multi-Factor Authentication

📚 API Reference

💡 Examples

• Laravel: https://github.com/casdoor/casdoor-php-laravel-example

🛠 Development

The tests run against a real Casdoor server. CI starts one with Docker and the data in .ci/casdoor/init_data.json:

Set CASDOOR_TEST_ENDPOINT, CASDOOR_TEST_CLIENT_ID, CASDOOR_TEST_CLIENT_SECRET, CASDOOR_TEST_ORGANIZATION and CASDOOR_TEST_APPLICATION to run the tests against another server.

Releases are tagged automatically by semantic-release when commits are pushed to master, and Packagist picks up the tags.

📖 Documentation

• Casdoor Documentation
• Casdoor PHP SDK Documentation
• Casdoor API Documentation
• Casdoor GitHub Repository

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.