README

Laravel Sanctum API Only

Overview

This Laravel project is an API-only application designed for robust authentication and authorization using Laravel Sanctum. It includes seamless support for handling UUIDs in binary format across both MySQL and PostgreSQL, along with essential features like root user management, seeders, and role-based policies.

Key Features

1. UUID Handling

Models requiring UUIDs can use the HasUuid trait (App\Traits\HasUuid) to automatically handle UUID generation and binary storage (16 bytes).
Custom validation rule: BinaryUuidExists for checking object existence during validation steps.
Database configuration supports both MySQL and PostgreSQL UUID handling.

2. API Authentication

Sanctum-based authentication with /register and /login routes.
Upon successful authentication, the server responds with a JSON object containing a ['token'] structure.
Default custom validation rules are implemented for both /register and /login requests.

3. Extended Token Management

Includes a modified version of HasApiTokens as HasApiTokensWithLocation to track device name and location alongside tokens.

4. Root User Management

Pre-configured root user with a dedicated role (root or admin).
Artisan command app:generate-root-password generates a secure root user password and stores it in the .env file.
- Ensure the .env file exists before running the command.
Default seeders create:
- root role (or custom role based on your .env configuration).
- Root user with credentials stored in the .env file.

5. Role Management

Includes an implemented policy and controller for the Role model.
Role-based access control is applied using Sanctum's auth:sanctum middleware.

Getting Started

1. Installation

Clone the repository:
```
git clone <repository_url>
```
Navigate to the project directory:
```
cd <project_name>
```
Install dependencies:
```
composer install
```
Copy the .env.example file to .env:
```
cp .env.example .env
```
Generate the application key:
```
php artisan key:generate
```

2. Database Configuration

Configure your database connection in the .env file:

DB_CONNECTION=mysql      # or pgsql
DB_HOST=127.0.0.1
DB_PORT=3306             # or 5432 for PostgreSQL
DB_DATABASE=your_db
DB_USERNAME=your_user
DB_PASSWORD=your_password

3. UUID Configuration

For MySQL, UUIDs are stored as BINARY(16).
For PostgreSQL, UUIDs use the native UUID type.

Usage

Root User Setup

Generate a root password:
```
php artisan app:generate-root-password
```
- This will generate a secure password in the .env file.
Run seeders to create the root role and root user:
```
php artisan db:seed
```

Routes

Define your API routes in the routes/api.php file.

Protect routes with Sanctum middleware:

Route::middleware('auth:sanctum')->group(function () {
    // Your protected routes here
});

Example Endpoints

Registration

POST /register
Content-Type: application/json

{
    "name": "Your Name",
    "email": "your@example.com",
    "password": "securepassword",
    "password_confirmation": "securepassword"
}

Login

POST /login
Content-Type: application/json

{
    "email": "your@example.com",
    "password": "securepassword"
}

Seeders

Default seeders are included for Role and User models.

Policies and Validation

Policies

Role Policy is pre-configured for the Role model.

Validation Rules

BinaryUuidExists ensures UUID existence during validation.
Custom rules for /register and /login routes ensure robust input validation.

Contributing

Feel free to fork this repository and submit pull requests. Contributions are always welcome!

License

This project is open-sourced and licensed under the MIT License.

yarazan / laravel-sanctum-api-only

Maintainers

Details