README

Authxolote SDK is a Laravel library designed to seamlessly integrate your application with the Authxolote authentication and authorization service.

Installation

You can install the package via composer:

composer require axolote-source/authxolote-sdk

The service provider will automatically register itself.

Configuration

Publish the configuration file using the following command:

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

This will create a config/authxolote.php file where you can configure:

url: The Authxolote API base URL.
token: Your application's authentication token.
cache: Enable or disable caching for user data.
sync_user: Whether to look up users in your local database or use API data directly.

Translations

If you want to customize the SDK messages, you can publish the translation files:

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

This will copy the JSON translation files to lang/vendor/authxolote, where you can modify the strings for different languages.

You can also use environment variables in your .env file:

AUTHXOLOTE_URL=https://api.your-service.com
AUTHXOLOTE_TOKEN=your-app-token
AUTHXOLOTE_CACHE=true
AUTHXOLOTE_SYNC_USER=true

Setup Authentication

To use the Authxolote guard, add it to your config/auth.php:

'guards' => [
    'authxolote' => [
        'driver' => 'authxolote',
        'provider' => 'users',
    ],
],

Usage

Authentication

Once configured, you can use the authxolote guard in your routes or controllers:

Route::middleware('auth:authxolote')->get('/user', function (Request $request) {
    return $request->user();
});

Checking Permissions

You can easily check for permissions using the Authxolote facade:

use Authxolote\Sdk\Authxolote;

// Check a single permission
if (Authxolote::action('edit-posts')->isAllow()) {
    // User has permission
}

// Check multiple permissions (all must be allowed)
if (Authxolote::actions(['edit-posts', 'delete-posts'])->isAllowAll()) {
    // User has all permissions
}

User Registration

use Authxolote\Sdk\Authxolote;

$user = Authxolote::register(
    'user@example.com',
    'John Doe',
    'password123',
    'admin' // role key
);

Validating Credentials

Validate a user's credentials without generating an access token. This endpoint requires authentication and the auth.validate-credentials action.

Make sure AUTHXOLOTE_TOKEN is configured and belongs to a user with that action.

use Authxolote\Sdk\Authxolote;

$isValid = Authxolote::validateCredentials()->run('user@example.com', 'password123');

if ($isValid === null) {
    // The authentication service could not be reached.
} elseif ($isValid) {
    // The credentials are valid.
} else {
    // The credentials are invalid.
}

Reordering Menus

Persist a new order for every item of a menu by sending its flat list of items. Each item defines its new parent (null for root items) and its position among its siblings:

use Authxolote\Sdk\Authxolote;

$service = Authxolote::reorderMenu($menuId, [
    ['id' => $homeId, 'parent_id' => null, 'sort_order' => 0],
    ['id' => $usersId, 'parent_id' => $settingsId, 'sort_order' => 0],
    ['id' => $settingsId, 'parent_id' => null, 'sort_order' => 1],
]);

if (! $service->run()) {
    // Inspect the error with $service->getError().
}

The payload must include every item of the menu, otherwise the API rejects the request.

Console Commands

To synchronize roles and actions, you must first create a config/actions.php file and register the roles with their respective actions:

return [
    'roles' => [
        'admin' => [
            'app.model.action',
        ],
    ],
];

Then, synchronize the roles and actions defined in your configuration:

php artisan authxolote:actions

To synchronize the menu defined in config/authxolote.php, run:

php artisan authxolote:menu

This command creates the application, the menu and its items if they do not exist. It does not delete existing items nor overwrite their names, paths or role assignments.

If you need to discard every manual change and rebuild the menu from the configuration file, use --force:

php artisan authxolote:menu --force

Before deleting anything, the command asks for confirmation because the existing menu and all of its items will be removed and recreated. The roles assigned from the panel, the item order, the icons and any other manual modification will be lost. When the confirmation is declined (or when running with --no-interaction), no request is sent and the menu is left untouched.

Testing

The SDK provides a built-in fake mode to facilitate unit testing without making actual API calls:

use Authxolote\Sdk\Authxolote;

// Fake specific actions
Authxolote::actionsFake(['edit-posts']);

// Now this will return true without calling the API
Authxolote::action('edit-posts')->isAllow(); 

// This will return false
Authxolote::action('other-action')->isAllow();

You can also customize the fake response of a specific SDK class:

use Authxolote\Sdk\Clases\ValidateCredentials;

Authxolote::fake();
Authxolote::fakeResponse(ValidateCredentials::class, [
    'status' => 'OK',
    'data' => ['valid' => false],
]);

Authxolote::validateCredentials()->run('user@example.com', 'wrong-password'); // false

Middleware

The SDK includes a middleware to protect your routes based on permissions. It is automatically registered as isAllow.

Basic Usage

You can use it in your routes:

Route::middleware(['auth:authxolote', 'isAllow:edit-posts'])->get('/posts/edit', function () {
    // Only users with 'edit-posts' permission can access this
});

Controller Groups Example

It is recommended to use a naming convention like project.module.action for your permissions. Here is an example using a controller group:

use App\Http\Controllers\TurnController;
use Illuminate\Support\Facades\Route;

Route::controller(TurnController::class)->group(function () {
    Route::post('', 'store')->middleware('isAllow:gob.turn.store');
    Route::get('/{id}', 'show')->middleware('isAllow:gob.turn.show');
    Route::put('/{id}', 'update')->middleware('isAllow:gob.turn.update');
    Route::delete('/{id}', 'delete')->middleware('isAllow:gob.turn.delete');
});

If the user does not have permission, the middleware will:

Return a JSON response with status 403 if the request expects JSON.
Throw a 403 HTTP exception otherwise.

To use this middleware, your User model (or the object returned by the guard) must use the Authxolote\Sdk\Traits\HasActions trait.

Credits

Luis Ozuna

License

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

axolote-source / authxolote-sdk

Package info

Security

Statistics