Introduction

PHP is a foundational language and many websites and frameworks are built on it, notoriously WordPress and Facebook. According to W3Tech, PHP is used in over 76% of indexed websites out there.

At SlashID, we love to support the latest frameworks and technologies such as our Remix SDK, but our mission is to solve real problems for real people. Given the importance of PHP in the ecosystem and the relative lack of modern authentication libraries available, we decided to fill that gap and release a PHP library coupled with a Laravel library.

Laravel is one of the more popular PHP frameworks out there but not the only one: in the next few weeks, we’ll release support for Symfony, Drupal, and more.

Design principles

Our core PHP SDK serves as the base for all the frameworks integrations. At a high level, it provides a wrapper around the SlashID APIs. But the SDK goes beyond that and provides several useful abstractions:

1. Errors in the APIs are mapped to PHP exceptions
2. A SlashID user is mapped to the Person class
3. An abstraction to migrate users
4. An abstraction for the SlashID webhooks

Laravel quickstart

Now that we covered the design principle of the core PHP SDK, let’s see how to deploy SlashID with Laravel.

1. Install the Laravel SlashID package

composer require slashid/laravel

2. Edit the environment file

• SLASHID_ENVIRONMENT: either “sandbox” or “production”
• SLASHID_ORGANIZATION_ID: your organization’s ID. You’ll find it in your SlashID console (https://console.slashid.dev/ for production, https://console.sandbox.slashid.dev/ for sandbox), in the “Settings” tab, at the top of the page.
• SLASHID_API_KEY: your organization’s API Key. You’ll also find it in your SlashID console, in the “Settings” tab, at the very bottom of the page.

Here’s an example configuration for your .env file:

SLASHID_ENVIRONMENT=sandbox
SLASHID_ORGANIZATION_ID=412edb57-ae26-f2aa-9999-770021ed64a0
SLASHID_API_KEY=z0dlY-nluiq8mcvm8YTolSkJV678

3. Publish the resource

Run the following artisan command to publish the resources:

php artisan vendor:publish --provider="SlashId\Laravel\Providers\SlashIdServiceProvider"

You’re ready! Now access /login in your website and enjoy your new login with SlashID.

4. Customize the login flow

The Laravel package comes with a bundle of the SlashID React SDK and a small JavaScript glue piece of code in vendor/slashid/laravel/public/slashid.laravel-web-login.js.

There are two ways to customize the flow:

1. Change the login form: the SlashID login form is rendered in two Blade templates: slashid/login.blade.php and slashid/login-form.blade.php. If you want to wrap the login form in /login inside the layout of the page, you can override the login template as shown here.

2. Customize the bundled React SDK as shown here.

Bonus: migrate users with ease

If you are installing SlashID in an existing Laravel website, you may already have a user base that you’ll want to migrate to SlashID’s database. This is made easy with two migration commands.

1. Run the migration script

First, you have to run the artisan command php artisan slashid:import:create-script. It will ask you the User class in your installation, usually \App\Models\User.

$ php artisan slashid:import:create-script

 Please inform the class of the user model [\App\Models\User]:
 >

The Slash ID migration script has been created at /var/www/html/database/slashid/user-migration.php. Please open the file and modify it according to the instructions in it.

2. Adapt the generated script

A script will be created in database/slashid/user-migration.php. It will look like this:

<?php

use SlashId\Laravel\SlashIdUser;

/** @var \Illuminate\Contracts\Auth\Authenticatable[] */
$laravelUsers = \App\Models\User::all();
$slashIdUsers = [];
foreach ($laravelUsers as $laravelUser) {
    $slashIdUser = new SlashIdUser();
    $slashIdUser
        ->addEmailAddress($laravelUser->email)
        ->setLegacyPasswordToMigrate($laravelUser->getAuthPassword())
        // Uncomment if you want to set the phone number.
        // ->addPhoneNumber($laravelUser->phone_number)
        // Uncomment if you want to set groups.
        // ->setGroups(['Editor'])
        // Uncomment if you want to specify a region for the user.
        // ->setRegion('us-iowa')
        ->setBucketAttributes(\SlashId\Php\PersonInterface::BUCKET_ORGANIZATION_END_USER_NO_ACCESS, [
            // List the user attributes you want to migrate, grouped by bucket.
            'old_id' => $laravelUser->getAuthIdentifier(),
            'firstname' => $laravelUser->firstname,
            'email_verified_at' => $laravelUser->email_verified_at,
            'lastname' => $laravelUser->lastname,
            'username' => $laravelUser->username,
        ]);

    $slashIdUsers[] = $slashIdUser;
}

return $slashIdUsers;

You must change user-migration.php to model the data to be migrated as you want. The script must return an array of \SlashId\Laravel\SlashIdUser with all the users you want to bulk import into SlashID.

3. Execute the migration

After adapting the script to your needs, run php artisan slashid:import:run:

$ php artisan slashid:import:run
+------------------------+---------------+--------+-------+--------+-------------------------------------------------------------------------------------------------------------------------------+
| Emails                 | Phone numbers | Region | Roles | Groups | Attributes                                                                                                                    |
+------------------------+---------------+--------+-------+--------+-------------------------------------------------------------------------------------------------------------------------------+
| [email protected]   |               |        |       |        | {"end_user_no_access":{"old_id":1,"firstname":"Urbano","email_verified_at":null,"lastname":"Rattazzi","username":"rattazzi"}} |
| [email protected]      |               |        |       |        | {"end_user_no_access":{"old_id":2,"firstname":"Francesco","email_verified_at":null,"lastname":"Nitti","username":"nitti"}}    |
| [email protected]     |               |        |       |        | {"end_user_no_access":{"old_id":3,"firstname":"Camillo","email_verified_at":null,"lastname":"Cavour","username":"cavour"}}    |
+------------------------+---------------+--------+-------+--------+-------------------------------------------------------------------------------------------------------------------------------+

 Do you want to proceed with importing 3 users? (yes/no) [no]:
 > yes

2 successfully imported users.
1 user failed to import. Check the file /var/www/html/database/slashid/migration-failed-202403271142.csv for errors.

Any errors that occur in a migration will be output as a CSV. Check the CSV to fix the errors and run again.

Conclusion

In this brief blog post, we have introduced our idiomatic PHP core SDK and the SlashID Laravel SDK. If you’re ready to upgrade your PHP code base to a modern authentication experience, SlashID is here to assist. Don’t hesitate to reach out to us or sign up for free here!