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
Add Database Configuration - Automatically adds Oracle database configuration to config/database.php
Update Environment Files - Automatically updates .env and .env.example with Oracle database settings
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

The install command automatically adds the Oracle database configuration to your config/database.php file and updates your .env and .env.example files. The following configuration is added to the connections array in config/database.php:

'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' => '.,',
    ],
],

The following environment variables are automatically added to your .env and .env.example files:

DB_CONNECTION=siza
DB_HOST=127.0.0.1
DB_PORT=1521
DB_DATABASE=siza
DB_USERNAME=username
DB_PASSWORD=password

Note: After installation, make sure to update the database credentials in your .env file with your actual Oracle database connection details.

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

The install command automatically configures the Oracle database connection. However, make sure to:

Update your .env file with the correct Oracle database credentials:

DB_CONNECTION=siza
DB_HOST=your-oracle-host
DB_PORT=1521
DB_DATABASE=your-database-name
DB_USERNAME=your-username
DB_PASSWORD=your-password

Ensure 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