README

A Laravel package that provides custom authentication for SIZA web-based applications using Laravel Fortify with Oracle database integration.

Features

🔐 Oracle Database Authentication - Authenticates users against Oracle database using custom password encryption
👤 Custom User Model - Extends SIZA Employee model with additional helper methods
🔑 Event-Driven - Built-in events and listeners for authentication tracking
🎨 UI Customization - Automatically updates login views and logo components
⚙️ Easy Installation - Single command setup for all starter kits (Livewire, Vue, React)

Requirements

PHP 8.2 or higher
Laravel 11.x or 12.x
Laravel Fortify 1.3 or higher
Oracle database connection (via siza/database package)

Installation

You can install the package via Composer:

composer require siza/authentication

The package will automatically register its service provider using Laravel's package auto-discovery.

Setup

Important: Before running the install command, make sure you have installed and configured Laravel Fortify. If you haven't already, install Fortify and publish its configuration:
composer require laravel/fortify
php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"

After installation, run the installation command:

# For Livewire starter kit (default)
php artisan siza:auth:install

# For Vue starter kit
php artisan siza:auth:install --kit=vue

# For React starter kit
php artisan siza:auth:install --kit=react

Note: The --kit option accepts livewire, vue, or react. If not specified, it defaults to livewire.

What the Install Command Does

The siza:auth:install command will:

Verify Service Provider Registration - Ensures the package is properly registered
Display Database Configuration - Shows instructions for adding Oracle database configuration
Replace User Model - Replaces App\Models\User with a custom implementation that extends Siza\Database\App\Models\Spsm\Employee
Update Fortify Configuration - Changes 'username' => 'email' to 'username' => 'identifier' in config/fortify.php
Update Login Views - Modifies login views to:
- Change input field name from email to identifier
- Change input field type from email to text
- Change label text from "Email" or "Email address" to "Staff I.D."
- Change placeholder to "Staff I.D."
- Change autocomplete from email to username
Update Logo Components - Replaces default Laravel logo with custom logo in:
- resources/views/components/app-logo.blade.php (Livewire)
- resources/js/components/AppLogo.vue (Vue)
- resources/js/components/app-logo.tsx (React)
Copy Favicon Files - Copies favicon.ico, favicon.svg, and apple-touch-icon.png to public/ directory

Warning: This command will modify and replace several files. You will be prompted to confirm before proceeding.

Configuration

Oracle Database Configuration

Add the following Oracle database configuration to your config/database.php file in the connections array:

'siza' => [
    'driver' => 'oracle',
    'tns' => env('DB_TNS', ''),
    'host' => env('DB_HOST', ''),
    'port' => env('DB_PORT', '1521'),
    'database' => env('DB_DATABASE', ''),
    'service_name' => env('DB_SERVICE_NAME', ''),
    'username' => env('DB_USERNAME', ''),
    'password' => env('DB_PASSWORD', ''),
    'charset' => env('DB_CHARSET', 'AL32UTF8'),
    'prefix' => env('DB_PREFIX', ''),
    'prefix_schema' => env('DB_SCHEMA_PREFIX', ''),
    'edition' => env('DB_EDITION', 'ora$base'),
    'server_version' => env('DB_SERVER_VERSION', '11g'),
    'load_balance' => env('DB_LOAD_BALANCE', 'yes'),
    'max_name_len' => env('ORA_MAX_NAME_LEN', 30),
    'dynamic' => [],
    'sessionVars' => [
        'NLS_TIME_FORMAT' => 'HH24:MI:SS',
        'NLS_DATE_FORMAT' => 'YYYY-MM-DD HH24:MI:SS',
        'NLS_TIMESTAMP_FORMAT' => 'YYYY-MM-DD HH24:MI:SS',
        'NLS_TIMESTAMP_TZ_FORMAT' => 'YYYY-MM-DD HH24:MI:SS TZH:TZM',
        'NLS_NUMERIC_CHARACTERS' => '.,',
    ],
],

Authentication Flow

The package automatically registers custom authentication logic with Laravel Fortify. When a user attempts to log in:

The system retrieves the identifier and password from the request
It queries the Oracle pengguna table using the enpwd() function for password verification
It checks for matching emp_id, nama_login, or nama_login with 's' suffix
If authentication succeeds, it dispatches the EmployeeLoggedIn event
It returns the corresponding User model from the Laravel database

Events

EmployeeLoggedIn

This event is dispatched when an employee successfully authenticates.

Event Properties:

$employeeId - The employee identifier
$password - The password used for authentication

Usage:

use Siza\Authentication\Events\EmployeeLoggedIn;

Event::listen(EmployeeLoggedIn::class, function (EmployeeLoggedIn $event) {
    // Handle successful login
    Log::info('Employee logged in', [
        'employee_id' => $event->employeeId,
    ]);
});

Listeners

DebugEmployee

A built-in listener that logs employee login attempts to a file. This listener is automatically registered and includes error handling.

Location: src/Listeners/DebugEmployee.php

Commands

Install Command

php artisan siza:auth:install [--kit=livewire|vue|react]

Installs and configures the package for your Laravel application. See Setup section for details.

User Model

The package replaces the default App\Models\User model with a custom implementation that:

Extends Siza\Database\App\Models\Spsm\Employee
Provides initials() method to generate user initials
Provides avatarUrl() method to get user avatar URL
Provides imageExists() method to check if avatar image exists
Falls back to UI Avatars service if custom avatar doesn't exist

Architecture

The package follows Laravel best practices:

Service Provider: AuthenticationServiceProvider handles package bootstrapping and Fortify customization
Direct Integration: Authentication logic is directly registered with Fortify (no configuration file needed)
Event-Driven: Uses Laravel's event system for extensibility
PSR-4 Autoloading: Follows PSR-4 standards

Troubleshooting

Service Provider Not Registered

If the service provider is not auto-discovered, you can manually register it in config/app.php:

'providers' => [
    // ...
    Siza\Authentication\AuthenticationServiceProvider::class,
],

Fortify Not Found

Ensure Laravel Fortify is installed:

composer require laravel/fortify
php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"

Oracle Connection Issues

Ensure the Oracle database connection is properly configured in config/database.php and that the siza/database package is installed:

composer require siza/database

User Model Not Found

If you encounter errors related to the User model, ensure the install command has been run:

php artisan siza:auth:install

Testing

Run the test suite:

composer test

Generate test coverage:

composer test-coverage

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email syahril@zakat.com.my instead of using the issue tracker.

siza / authentication

Maintainers

Details