README

Caution

This package is still under development and not ready for production use.

A fluent Laravel package for interacting with WorkOS API.

@TODO: Add package description here.

Why use This package?

✅ The package has been optimised for Laravel 10+.
✅ Offer developer friendly error handling e.g. Get an authorization URL Errors.
✅ Offers language translations .
✅ Build with Saloon PHP. This mean you can benefit from Saloon goodies such as Laravel Plugin which can debug the WorkOS API requests inside your Laravel application.
✅ Users Data Object Transfer for efficient data handling. DTO are powered by Spatie laravel data.
✅ Automatically prevent hitting rate limits and handle retries.
✅ TODO: Add more reasons here

Installation

You can install the package via composer:

composer require njoguamos/laravel-workos

Update your .env file with the following

WORKOS_API_KEY=
WORKOS_CLIENT_ID=

You can publish the config file with:

php artisan vendor:publish --tag="workos-config"

You can publish the translations file with:

php artisan vendor:publish --tag="workos-translations"

Documentation

The documentation is available at https://njoguamos.github.io/laravel-workos.

The response is a AuthUserDTO object which can be used as an object or converted to json or array.

$json = $response->json()

Output

{
    "user": {
        "object": "user",
        "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
        "email": "marcelina.davis@example.com",
        "email_verified": true,
        "created_at": "2021-06-25T19:07:33.155Z",
        "updated_at": "2021-06-25T19:07:33.155Z",
        "first_name": "Marcelina",
        "last_name": "Davis",
        "profile_picture_url": "https://workoscdn.com/images/v1/123abc"
    },
    "access_token": "eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0",
    "refresh_token": "yAjhKk123NLIjdrBdGZPf8pLIDvK",
    "authentication_method": "GoogleOAuth",
    "organization_id": "org_01H945H0YD4F97JN9MATX7BYAG",
    "impersonator": null
}

If the authentication did not succeed, WorkOS API will return a a 400 or 403 error which will be thrown as a \Saloon\Exceptions\Request\RequestException.

400 error occurs when the authentication code is invalid or expired.
403 occur when WorkOS returns predefined Authentication errors, which include email_verification_required, mfa_enrollment, mfa_challenge, organization_selection_required, sso_required, and organization_authentication_methods_required.

You can use try and catch block to handle the errors. Example you can determine if body contains email_verification_required and redirect user to email verification page.

## Testing

```bash
composer test

Changelog

You can find the changes made in the repository Releases page

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

njoguamos / laravel-workos

Maintainers

Details