DEV Community: Daud A. Mabena

Integrating Spatie Laravel Permission with React for Role-Based Access Control

Daud A. Mabena — Sat, 23 Aug 2025 15:57:58 +0000

This tutorial will guide you through the process of setting up a robust role-based access control (RBAC) system using the Spatie Laravel Permission package for your Laravel backend and a React frontend. We will cover everything from initial setup to advanced features like real-time permission updates.

Introduction

In modern web applications, it is crucial to control what actions a user can perform. Role-based access control is a common and effective way to manage user permissions. The Spatie Laravel Permission package is a powerful and flexible tool for implementing RBAC in Laravel applications. When combined with a React frontend, it allows for a dynamic and secure user experience.

This tutorial will cover:

Backend Setup: Installing and configuring the Spatie Laravel Permission package.
API Endpoints: Creating secure API endpoints to manage roles and permissions.
Frontend Setup: Integrating React with your Laravel backend.
Role-Based Rendering: Conditionally rendering UI components in React based on user roles and permissions.
Real-Time Updates: Using WebSockets to instantly reflect permission changes in the frontend.

By the end of this tutorial, you will have a solid understanding of how to build a secure and scalable application with role-based access control using Laravel and React.

Part 1: Backend Setup with Laravel and Spatie Permission

In this section, we will set up our Laravel backend, install the Spatie Laravel Permission package, and configure it for our application.

1.1. Create a New Laravel Project

First, let's create a new Laravel project. Open your terminal and run the following command:

composer create-project --prefer-dist laravel/laravel laravel-react-permissions
cd laravel-react-permissions

1.2. Set Up the Database

Next, you need to configure your database. Open the .env file and update the database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_react_permissions
DB_USERNAME=root
DB_PASSWORD=

After configuring the database, run the migrations:

php artisan migrate

1.3. Install and Configure Spatie Laravel Permission

Now, let's install the Spatie Laravel Permission package via Composer:

composer require spatie/laravel-permission

Publish the package's configuration and migration files:

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

This will publish the config/permission.php file and the necessary migration files. Now, run the migrations to create the roles and permissions tables:

php artisan migrate

1.4. Set Up the User Model

To enable role and permission management for your User model, you need to add the HasRoles trait to it. Open app/Models/User.php and add the trait:

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable, HasRoles;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<int, string>
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [
        'email_verified_at' => 'datetime',
    ];
}

Part 2: Creating API Endpoints for Roles and Permissions

In this section, we will create the necessary API endpoints to manage roles and permissions, and to get user data with their assigned roles and permissions.

2.1. Create Roles and Permissions

Let's create some roles and permissions for our application. You can do this in a seeder or directly in your code. For this tutorial, we will create a seeder.

First, create a new seeder:

php artisan make:seeder RolesAndPermissionsSeeder

Now, open the seeder file in database/seeders/RolesAndPermissionsSeeder.php and add the following code:

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

class RolesAndPermissionsSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        // Reset cached roles and permissions
        app()[
            \Spatie\Permission\PermissionRegistrar::class
        ]->forgetCachedPermissions();

        // create permissions
        Permission::create(["name" => "edit articles"]);
        Permission::create(["name" => "delete articles"]);
        Permission::create(["name" => "publish articles"]);
        Permission::create(["name" => "unpublish articles"]);

        // create roles and assign created permissions

        // this can be done as separate statements
        $role = Role::create(["name" => "writer"]);
        $role->givePermissionTo("edit articles");

        // or may be done by chaining
        $role = Role::create(["name" => "moderator"])->givePermissionTo([
            "publish articles",
            "unpublish articles",
        ]);

        $role = Role::create(["name" => "super-admin"]);
        $role->givePermissionTo(Permission::all());
    }
}

Now, run the seeder:

php artisan db:seed --class=RolesAndPermissionsSeeder

2.2. Create API Routes

Now, let's create the API routes for our application. Open routes/api.php and add the following code:

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\AuthController;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| is assigned the "api" middleware group. Enjoy building your API!
|
*/

Route::post("/register", [AuthController::class, "register"]);
Route::post("/login", [AuthController::class, "login"]);

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

Route::middleware("auth:sanctum")->group(function () {
    Route::get("/user-permissions", [AuthController::class, "userPermissions"]);
});

2.3. Create AuthController

Now, let's create the AuthController to handle user registration, login, and getting user permissions. Create a new controller:

php artisan make:controller AuthController

Open app/Http/Controllers/AuthController.php and add the following code:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $validatedData = $request->validate([
            "name" => "required|string|max:255",
            "email" => "required|string|email|max:255|unique:users",
            "password" => "required|string|min:8",
        ]);

        $user = User::create([
            "name" => $validatedData["name"],
            "email" => $validatedData["email"],
            "password" => Hash::make($validatedData["password"]),
        ]);

        $token = $user->createToken("auth_token")->plainTextToken;

        return response()->json([
            "access_token" => $token,
            "token_type" => "Bearer",
        ]);
    }

    public function login(Request $request)
    {
        if (!Auth::attempt($request->only("email", "password"))) {
            return response()->json([
                "message" => "Invalid login details",
            ], 401);
        }

        $user = User::where("email", $request["email"])->firstOrFail();

        $token = $user->createToken("auth_token")->plainTextToken;

        return response()->json([
            "access_token" => $token,
            "token_type" => "Bearer",
        ]);
    }

    public function userPermissions(Request $request)
    {
        return response()->json([
            "roles" => $request->user()->getRoleNames(),
            "permissions" => $request->user()->getAllPermissions()->pluck("name"),
        ]);
    }
}

Part 3: Frontend Setup with React

In this section, we will set up our React frontend, connect it to the Laravel backend, and handle user authentication.

3.1. Create a New React App

First, let's create a new React app. Open a new terminal window and run the following command:

npx create-react-app react-permissions-frontend
cd react-permissions-frontend

3.2. Install Dependencies

Next, we need to install some dependencies for our React app. We will use axios for making API requests and react-router-dom for routing.

npm install axios react-router-dom

3.3. Create API Service

Let's create a simple API service to handle communication with our Laravel backend. Create a new file src/api.js and add the following code:

import axios from "axios";

const api = axios.create({
    baseURL: "http://localhost:8000/api",
    headers: {
        "Content-Type": "application/json",
    },
});

api.interceptors.request.use(
    (config) => {
        const token = localStorage.getItem("token");
        if (token) {
            config.headers["Authorization"] = `Bearer ${token}`;
        }
        return config;
    },
    (error) => {
        return Promise.reject(error);
    }
);

export default api;

3.4. Create Auth Context

Now, let's create a React context to manage user authentication state and permissions. Create a new file src/AuthContext.js and add the following code:

import React, { createContext, useState, useContext } from "react";
import api from "./api";

const AuthContext = createContext();

export const AuthProvider = ({ children }) => {
    const [user, setUser] = useState(null);
    const [roles, setRoles] = useState([]);
    const [permissions, setPermissions] = useState([]);

    const login = async (email, password) => {
        const response = await api.post("/login", { email, password });
        localStorage.setItem("token", response.data.access_token);
        await getUser();
    };

    const register = async (name, email, password) => {
        await api.post("/register", { name, email, password });
    };

    const logout = () => {
        localStorage.removeItem("token");
        setUser(null);
        setRoles([]);
        setPermissions([]);
    };

    const getUser = async () => {
        const response = await api.get("/user");
        setUser(response.data);
        const permissionsResponse = await api.get("/user-permissions");
        setRoles(permissionsResponse.data.roles);
        setPermissions(permissionsResponse.data.permissions);
    };

    return (
        <AuthContext.Provider value={{ user, roles, permissions, login, register, logout, getUser }}>
            {children}
        </AuthContext.Provider>
    );
};

export const useAuth = () => useContext(AuthContext);

3.5. Update App.js

Now, let's update our App.js to use the AuthProvider and set up our routes.

import React from "react";
import { BrowserRouter as Router, Routes, Route, Link } from "react-router-dom";
import { AuthProvider, useAuth } from "./AuthContext";
import Login from "./Login";
import Register from "./Register";

const Home = () => {
    const { user, roles, permissions, logout } = useAuth();

    return (
        <div>
            <h1>Welcome, {user ? user.name : "Guest"}</h1>
            {user ? (
                <div>
                    <p>Email: {user.email}</p>
                    <p>Roles: {roles.join(", ")}</p>
                    <p>Permissions: {permissions.join(", ")}</p>
                    <button onClick={logout}>Logout</button>
                </div>
            ) : (
                <div>
                    <Link to="/login">Login</Link> | <Link to="/register">Register</Link>
                </div>
            )}
        </div>
    );
};

const App = () => {
    return (
        <Router>
            <AuthProvider>
                <Routes>
                    <Route path="/" element={<Home />} />
                    <Route path="/login" element={<Login />} />
                    <Route path="/register" element={<Register />} />
                </Routes>
            </AuthProvider>
        </Router>
    );
};

export default App;

3.6. Create Login and Register Components

Finally, let's create the Login and Register components. Create two new files, src/Login.js and src/Register.js.

src/Login.js

import React, { useState } from "react";
import { useAuth } from "./AuthContext";
import { useNavigate } from "react-router-dom";

const Login = () => {
    const [email, setEmail] = useState("");
    const [password, setPassword] = useState("");
    const { login } = useAuth();
    const navigate = useNavigate();

    const handleSubmit = async (e) => {
        e.preventDefault();
        await login(email, password);
        navigate("/");
    };

    return (
        <form onSubmit={handleSubmit}>
            <h2>Login</h2>
            <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
            <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />
            <button type="submit">Login</button>
        </form>
    );
};

export default Login;

src/Register.js

import React, { useState } from "react";
import { useAuth } from "./AuthContext";
import { useNavigate } from "react-router-dom";

const Register = () => {
    const [name, setName] = useState("");
    const [email, setEmail] = useState("");
    const [password, setPassword] = useState("");
    const { register } = useAuth();
    const navigate = useNavigate();

    const handleSubmit = async (e) => {
        e.preventDefault();
        await register(name, email, password);
        navigate("/login");
    };

    return (
        <form onSubmit={handleSubmit}>
            <h2>Register</h2>
            <input type="text" value={name} onChange={(e) => setName(e.target.value)} placeholder="Name" />
            <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
            <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />
            <button type="submit">Register</button>
        </form>
    );
};

export default Register;

Part 4: Role-Based Rendering in React

In this section, we will implement role-based rendering in our React frontend to show or hide UI components based on the user's roles and permissions.

4.1. Create a Protected Route Component

First, let's create a protected route component that checks if a user has the required permission to access a route. Create a new file src/ProtectedRoute.js and add the following code:

import React from "react";
import { Navigate } from "react-router-dom";
import { useAuth } from "./AuthContext";

const ProtectedRoute = ({ children, permission }) => {
    const { permissions } = useAuth();

    if (!permissions.includes(permission)) {
        return <Navigate to="/" />;
    }

    return children;
};

export default ProtectedRoute;

4.2. Create a Can Component

Next, let's create a Can component that conditionally renders its children based on the user's permissions. Create a new file src/Can.js and add the following code:

import { useAuth } from "./AuthContext";

const Can = ({ children, permission }) => {
    const { permissions } = useAuth();

    if (!permissions.includes(permission)) {
        return null;
    }

    return children;
};

export default Can;

4.3. Update App.js with Protected Routes and Components

Now, let's update our App.js to use the ProtectedRoute and Can components.

import React from "react";
import { BrowserRouter as Router, Routes, Route, Link } from "react-router-dom";
import { AuthProvider, useAuth } from "./AuthContext";
import Login from "./Login";
import Register from "./Register";
import ProtectedRoute from "./ProtectedRoute";
import Can from "./Can";

const Dashboard = () => <h2>Dashboard</h2>;
const Articles = () => <h2>Articles</h2>;

const Home = () => {
    const { user, roles, permissions, logout } = useAuth();

    return (
        <div>
            <h1>Welcome, {user ? user.name : "Guest"}</h1>
            {user ? (
                <div>
                    <p>Email: {user.email}</p>
                    <p>Roles: {roles.join(", ")}</p>
                    <p>Permissions: {permissions.join(", ")}</p>
                    <nav>
                        <Link to="/">Home</Link> | <Link to="/dashboard">Dashboard</Link> | <Link to="/articles">Articles</Link>
                    </nav>
                    <Can permission="edit articles">
                        <button>Edit Articles</button>
                    </Can>
                    <Can permission="delete articles">
                        <button>Delete Articles</button>
                    </Can>
                    <button onClick={logout}>Logout</button>
                </div>
            ) : (
                <div>
                    <Link to="/login">Login</Link> | <Link to="/register">Register</Link>
                </div>
            )}
        </div>
    );
};

const App = () => {
    return (
        <Router>
            <AuthProvider>
                <Routes>
                    <Route path="/" element={<Home />} />
                    <Route path="/login" element={<Login />} />
                    <Route path="/register" element={<Register />} />
                    <Route
                        path="/dashboard"
                        element={
                            <ProtectedRoute permission="view dashboard">
                                <Dashboard />
                            </ProtectedRoute>
                        }
                    />
                    <Route
                        path="/articles"
                        element={
                            <ProtectedRoute permission="view articles">
                                <Articles />
                            </ProtectedRoute>
                        }
                    />
                </Routes>
            </AuthProvider>
        </Router>
    );
};

export default App;

Now, you need to add the view dashboard and view articles permissions to your seeder and assign them to the appropriate roles.

Part 5: Real-Time Permission Updates with WebSockets

In this section, we will implement real-time permission updates using WebSockets to instantly reflect any changes in user permissions on the frontend.

5.1. Install Pusher and Laravel Echo

First, let's install the necessary packages for broadcasting events from our Laravel backend.

composer require pusher/pusher-php-server
npm install --save-dev laravel-echo pusher-js

5.2. Configure Broadcasting

Next, you need to configure broadcasting in your Laravel application. Open config/app.php and uncomment the App\Providers\BroadcastServiceProvider.

Then, open your .env file and configure the broadcast driver and Pusher credentials:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-pusher-app-id
PUSHER_APP_KEY=your-pusher-app-key
PUSHER_APP_SECRET=your-pusher-app-secret
PUSHER_APP_CLUSTER=mt1

5.3. Create a Permission Changed Event

Now, let's create an event that will be broadcasted whenever a user's permissions change. Create a new event:

php artisan make:event UserPermissionsChanged

Open app/Events/UserPermissionsChanged.php and add the following code:

<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use App\Models\User;

class UserPermissionsChanged implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $user;

    /**
     * Create a new event instance.
     *
     * @return void
     */
    public function __construct(User $user)
    {
        $this->user = $user;
    }

    /**
     * Get the channels the event should broadcast on.
     *
     * @return \Illuminate\Broadcasting\Channel|array
     */
    public function broadcastOn()
    {
        return new PrivateChannel("user." . $this->user->id);
    }
}

5.4. Broadcast the Event

Now, you need to broadcast the UserPermissionsChanged event whenever a user's permissions are updated. You can do this in your AuthController or a dedicated service. For this tutorial, we will add a new method to our AuthController to update user permissions.

// app/Http/Controllers/AuthController.php

public function updateUserPermissions(Request $request, User $user)
{
    $validatedData = $request->validate([
        "permissions" => "required|array",
    ]);

    $user->syncPermissions($validatedData["permissions"]);

    event(new \App\Events\UserPermissionsChanged($user));

    return response()->json(["message" => "Permissions updated successfully"]);
}

5.5. Listen for the Event in React

Finally, let's update our AuthContext.js to listen for the UserPermissionsChanged event and update the user's permissions in real-time.

// src/AuthContext.js

import Echo from "laravel-echo";
import Pusher from "pusher-js";

// ...

export const AuthProvider = ({ children }) => {
    // ...

    useEffect(() => {
        if (user) {
            const echo = new Echo({
                broadcaster: "pusher",
                key: "your-pusher-app-key",
                cluster: "mt1",
                encrypted: true,
            });

            echo.private(`user.${user.id}`).listen("UserPermissionsChanged", (e) => {
                getUser();
            });
        }
    }, [user]);

    // ...
};

Now, whenever a user's permissions are updated in the backend, the UserPermissionsChanged event will be broadcasted, and the frontend will automatically fetch the updated permissions.

Conclusion

In this tutorial, you have learned how to integrate the Spatie Laravel Permission package with a React frontend to create a robust role-based access control system. You have also learned how to implement real-time permission updates using WebSockets.

By following this tutorial, you can build secure and scalable applications with granular control over user permissions. Now I have finished writing the tutorial. I will deliver it to the user.

Roadmap to Financial Freedom (April 1, 2025 - March 31, 2030)

Daud A. Mabena — Mon, 31 Mar 2025 09:01:16 +0000

Introduction
Financial freedom is a goal that many aspire to but few achieve without a structured plan. It is about reaching a point where your finances are no longer a source of stress, and your income—both active and passive—comfortably sustains your lifestyle and long-term goals. This roadmap outlines a clear, actionable strategy to achieve financial independence within five years. It covers key aspects such as increasing income, managing expenses, securing family needs, and investing in wealth-generating assets.

By following this plan with commitment and discipline, you can break free from financial constraints and build a future of stability, security, and prosperity. Let us dive into the step-by-step phases that will guide you toward financial independence.
Phase 1: Financial Assessment & Goal Setting (Months 1-3)

Evaluate Current Financial Status:
- Calculate total income, expenses, savings, and debts.
- Identify unnecessary expenses and create a budget.
Set Clear Goals:
- Short-term: Build emergency fund (3-6 months of expenses).
- Midterm: Increase alternative income sources.
- Long-term: Attain debt-free status and invest in assets.
Create a Budget & Debt Repayment Plan:
- Allocate funds for essential expenses, savings, and investments.
- Prioritize high-interest debt repayments.

Phase 2: Building a Stable Alternative Income (Months 4-12)

Identify and Establish Additional Income Streams:
- Freelancing, business, investments, rental property, digital assets.
- Start with manageable side hustle and scale gradually.
Optimize Primary Income:
- Seek salary increment, job upgrade, or upskill for higher pay.
- Negotiate better contracts if self-employed.
Save & Reinvest Profits:
- Allocate additional earnings to investments and emergency fund.
- Maintain a disciplined savings habit (e.g., 30-50% of extra income).

Phase 3: Securing Family’s Financial Stability (Year 2-3)

Ensure Basic Needs are Covered:
- Housing: Secure a mortgage or savings’ plan for home ownership.
- Education: Start a school fees fund or invest in an education plan.
- Healthcare: Obtain comprehensive health insurance.
Invest in Income-Generating Assets:
- Buy rental properties, dividend stocks, or profitable businesses.
- Scale up side hustles into fully operational businesses.
Reduce Liabilities & Improve Credit Score:
- Pay off remaining debts (loans, credit cards, mortgages).
- Maintain a good credit score for future opportunities.

Phase 4: Wealth Growth & Lifestyle Upgrade (Year 3-4)

Enhance Investment Portfolio:
- Diversify assets (real estate, stocks, bonds, digital assets).
- Explore passive income avenues (royalties, automated businesses).
Improve Lifestyle While Maintaining Financial Discipline:
- Purchase a vehicle (if necessary) within financial means.
- Travel, leisure, and family experiences within a budget.
Scale Business Ventures & Income Streams:
- Automate and delegate to maximize efficiency.
- Increase revenue sources without overextending workload.

Phase 5: Achieving Full Financial Freedom (Year 5)

Reach Self-Sustaining Wealth:
- Ensure passive income covers living expenses.
- Continue reinvesting in growing assets.
Establish Generational Wealth & Financial Security:
- Set up trusts, inheritance plans, or family businesses.
- Educate family on financial literacy and investment strategies.
Enjoy Financial Freedom Responsibly:
- Live comfortably within sustainable wealth limits.
- Continue personal growth and philanthropy.

Commitments for Success:

Monthly financial check-ins and progress tracking.
Strict adherence to the budget and financial discipline.
Continuous learning (investment, financial management, wealth-building).
Adaptability to market and economic changes.

By following this structured plan, financial freedom can be achieved within five years, ensuring stability, security, and sustainable wealth.

Applicant Registration Form

Daud A. Mabena — Sat, 22 Mar 2025 01:55:50 +0000

Design Applicant Registration Form Specification

This form facilitates applicant registration. It comprises sections for academic history, personal data, contact details, and account creation.

Application Category
Secondary School
Primary School
Personal Details
Contact Details
Password

This React application uses Ant Design components, including but not limited to Tabs, Form, Input, Button, and Select, to render conditionally displayed sections based on data availability. State management is implemented using React hooks, specifically useState and useEffect, while backend interactions are simulated using mock JSON data. The following sections detail the individual components, their input parameters, and their corresponding React implementation strategies.

Project Setup

Before diving into the sections, set up your React project with Vite and Ant Design:

Main Component: Create a RegistrationForm component as the parent, managing the overall form state and submission.
State Management: Use a single useState hook in RegistrationForm to hold all form data, passing props to child components for each section.
Ant Design: Utilize Form for form handling, validation, and submission.
Mock Data: Use mock JSON objects or a mock API tool (e.g., json-server) to simulate backend responses.

Here is a suggested state structure for the form:

const [formData, setFormData] = useState({
  programme_level_id: "",
  academic_year: "",
  intake_description: "",
  csee_country_id: "",
  index_number: "",
  exam_year: "",
  primary_school: "",
  primary_school_region: "",
  primary_school_district: "",
  first_name: "",
  middle_name: "",
  surname: "",
  dob: "",
  country_id_nationality: "",
  country_id_residence: "",
  marital_status: "",
  impairment_id: "",
  email: "",
  phone: "",
  password: "",
  re_password: "",
});
const [nectaData, setNectaData] = useState(null); // For Secondary School NECTA data
const [showProfile, setShowProfile] = useState(false); // Controls visibility of profile sections

1. Application Category Section

Description

This section collects the applicant’s intended area of study and displays the current academic year and intake. It is the first step in the form.

Inputs

Applying For (programme_level_id):
- Type: Dropdown (<Select> from Antd)
- Options: List of active application categories (e.g., Undergraduate, Postgraduate)
- Required: Yes
Year (academic_year):
- Type: Text input (<Input> from Antd)
- Read-only: Yes
- Value: Current academic year (e.g., "2023/2024")
Intake (intake_description):
- Type: Text input (<Input> from Antd)
- Read-only: Yes
- Value: Current intake description (e.g., "September Intake")

Steps

Fetch the list of application categories for the dropdown when the component mounts.
Fetch the current academic settings (year and intake) to populate the read-only fields.
Allow the user to select an application category from the dropdown.

When to Fetch Data from Backend

Application Categories: Fetch when the component mounts to populate the dropdown.

Request: GET /api/application-categories
Sample Response:

[
  { "id": 1, "title": "Undergraduate", "programme_level_id": 1 },
  { "id": 2, "title": "Postgraduate", "programme_level_id": 2 }
]

Academic Settings: Fetch when the component mounts to set the year and intake.
- Request: GET /api/academic-settings
- Sample Response:
```
{
  "academic_year": "2023/2024",
  "intake_description": "September Intake"
}
```

React Implementation

import { Form, Select, Input } from "antd";
import { useEffect, useState } from "react";

const ApplicationCategorySection = ({ formData, setFormData }) => {
  const [categories, setCategories] = useState([]);

  useEffect(() => {
    // Simulate fetching categories
    const fetchCategories = async () => {
      const response = [
        { id: 1, title: "\"Undergraduate\", programme_level_id: 1 },"
        { id: 2, title: "\"Postgraduate\", programme_level_id: 2 },"
      ];
      setCategories(response);
    };
    const fetchSettings = async () => {
      const settings = { academic_year: "2023/2024", intake_description: "\"September Intake\" };"
      setFormData((prev) => ({ ...prev, ...settings }));
    };
    fetchCategories();
    fetchSettings();
  }, [setFormData]);

  return (
    <div>
      <h5>Application Category</h5>
      <Form.Item label="Applying For" required>
        <Select
          value={formData.programme_level_id}
          onChange={(value) => setFormData({ ...formData, programme_level_id: value })}
          placeholder="Choose Area of Study"
        >
          {categories.map((cat) => (
            <Select.Option key={cat.id} value={cat.programme_level_id}>
              {cat.title}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="Year">
        <Input value={formData.academic_year} readOnly />
      </Form.Item>
      <Form.Item label="Intake">
        <Input value={formData.intake_description} readOnly />
      </Form.Item>
    </div>
  );
};

Notes

If the category list is empty, display a warning: "Window for new Application is currently closed," and disable the rest of the form.

2. Secondary School Section

Description

This section collects secondary school examination details (e.g., NECTA Form Four in Tanzania) and fetches additional data based on the input. It is only shown if there are active application categories.

Inputs

CSEE Country (csee_country_id):
- Type: Dropdown (<Select> from Antd)
- Options: List of countries
- Required: Yes
Index Number (index_number):
- Type: Text input (<Input> from Antd)
- Placeholder: "CSEE or Equivalent Index Number"
- Read-only: Optional (can be editable for now)
- Format Note: "SXXXX/XXXX" or "PXXXX/XXXX" for NECTA, "EQYYYYXXXXXX" for equivalents
Exam Year (exam_year):
- Type: Dropdown (<Select> from Antd)
- Options: Years from 1970 to the previous year (generate dynamically)
- Required: Yes

Steps

Fetch the list of countries for the CSEE Country dropdown.
Generate the Exam Year options dynamically (1970 to current year - 1).
When the user changes the Index Number or Exam Year, fetch NECTA data if both fields are filled and the Index Number is at least 10 characters long.
Display a loading indicator (e.g., <Spin> from Antd) while fetching.
Show the fetched school name and applicant name below the inputs.

When to Fetch Data from Backend

Countries: Fetch when the component mounts.

Request: GET /api/countries
Sample Response:

[
  { "id": 1, "name": "Tanzania" },
  { "id": 2, "name": "Kenya" }
]

NECTA Data: Fetch when Index Number or Exam Year changes.

Request: POST /api/get-necta-data
Request Body:

{
  "index_number": "S1234/5678",
  "exam_year": "2020",
  "csee_country_id": 1,
  "exam_type_id": 1
}

Sample Success Response:

{
  "status": 1,
  "message": "Data fetched successfully",
  "csee_school_name": "Sample School",
  "result_string": "John Middle Doe"
}

Sample Error Response:

{
  "status": 0,
  "message": "Invalid index number"
}

React Implementation

import { Form, Select, Input, Spin } from "antd";
import { useEffect, useState } from "react";

const SecondarySchoolSection = ({ formData, setFormData, setNectaData, setShowProfile }) => {
  const [countries, setCountries] = useState([]);
  const [years] = useState(() => {
    const currentYear = new Date().getFullYear() - 1;
    return Array.from({ length: currentYear - 1970 + 1 }, (_, i) => currentYear - i);
  });
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const fetchCountries = async () => {
      const response = [
        { id: 1, name: "Tanzania" },
        { id: 2, name: "Kenya" },
      ];
      setCountries(response);
    };
    fetchCountries();
  }, []);

  const fetchNectaData = async () => {
    if (formData.index_number && formData.exam_year && formData.index_number.length >= 10) {
      setLoading(true);
      const mockResponse = {
        status: 1,
        message: "Data fetched successfully",
        csee_school_name: "Sample School",
        result_string: "John Middle Doe",
      };
      setLoading(false);
      if (mockResponse.status === 1) {
        setNectaData(mockResponse);
        const [first_name, ...rest] = mockResponse.result_string.split(" ");
        const surname = rest.pop();
        const middle_name = rest.join(" ");
        setFormData((prev) => ({
          ...prev,
          first_name,
          middle_name,
          surname,
        }));
        setShowProfile(true);
      }
    }
  };

  return (
    <div>
      <h5>Secondary School</h5>
      <p>
        <strong>Note:</strong> For NECTA, use format SXXXX/XXXX or PXXXX/XXXX. For equivalents, use
        EQYYYYXXXXXX.
      </p>
      <Form.Item label="CSEE Country" required>
        <Select
          value={formData.csee_country_id}
          onChange={(value) => setFormData({ ...formData, csee_country_id: value })}
          placeholder="Select O' Level Country"
        >
          {countries.map((country) => (
            <Select.Option key={country.id} value={country.id}>
              {country.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="Index Number" required>
        <Input
          value={formData.index_number}
          onChange={(e) => {
            setFormData({ ...formData, index_number: e.target.value });
            fetchNectaData();
          }}
          placeholder="CSEE or Equivalent Index Number"
        />
      </Form.Item>
      <Form.Item label="Exam Year" required>
        <Select
          value={formData.exam_year}
          onChange={(value) => {
            setFormData({ ...formData, exam_year: value });
            fetchNectaData();
          }}
          placeholder="Select CSEE Year"
        >
          {years.map((year) => (
            <Select.Option key={year} value={year}>
              {year}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      {loading && <Spin />}
      {nectaData && (
        <div>
          <p><strong>O'LEVEL SCHOOL NAME:</strong> {nectaData.csee_school_name}</p>
          <p><strong>APPLICANT NAME:</strong> {nectaData.result_string}</p>
        </div>
      )}
    </div>
  );
};

Notes

After a successful NECTA fetch, parse result_string (e.g., "John Middle Doe") into first_name, middle_name, and surname for form submission, even though these fields aren’t editable in the UI.

3. Primary School Section

Description

This section collects primary school details and is shown only after NECTA data is successfully fetched (controlled by showProfile).

Inputs

Primary School (primary_school):
- Type: Text input (<Input> from Antd)
- Required: Yes
Primary School Region (primary_school_region):
- Type: Dropdown (<Select> from Antd)
- Options: List of regions
- Required: Yes
Primary School District (primary_school_district):
- Type: Dropdown (<Select> from Antd)
- Options: List of districts, dependent on the selected region
- Required: Yes

Steps

Fetch the list of regions when the component mounts.
When the user selects a region, fetch the corresponding districts.
Allow the user to input the primary school name and select a region and district.

When to Fetch Data from Backend

Regions: Fetch when the component mounts.

Request: GET /api/regions
Sample Response:

[
  { "id": 1, "name": "Dar es Salaam" },
  { "id": 2, "name": "Arusha" }
]

Districts: Fetch when the region changes.
- Request: GET /api/districts?region_id=1
- Sample Response:
```
[
  { "id": 1, "name": "Ilala" },
  { "id": 2, "name": "Kinondoni" }
]
```

React Implementation

import { Form, Input, Select } from "antd";
import { useEffect, useState } from "react";

const PrimarySchoolSection = ({ formData, setFormData }) => {
  const [regions, setRegions] = useState([]);
  const [districts, setDistricts] = useState([]);

  useEffect(() => {
    const fetchRegions = async () => {
      const response = [
        { id: 1, name: "Dar es Salaam" },
        { id: 2, name: "Arusha" },
      ];
      setRegions(response);
    };
    fetchRegions();
  }, []);

  const fetchDistricts = async (regionId) => {
    const response = [
      { id: 1, name: "Ilala" },
      { id: 2, name: "Kinondoni" },
    ];
    setDistricts(response);
  };

  return (
    <div>
      <h5>Primary School</h5>
      <Form.Item label="Primary School" required>
        <Input
          value={formData.primary_school}
          onChange={(e) => setFormData({ ...formData, primary_school: e.target.value })}
        />
      </Form.Item>
      <Form.Item label="Region" required>
        <Select
          value={formData.primary_school_region}
          onChange={(value) => {
            setFormData({ ...formData, primary_school_region: value, primary_school_district: "" });
            fetchDistricts(value);
          }}
          placeholder="Select Region"
        >
          {regions.map((region) => (
            <Select.Option key={region.id} value={region.id}>
              {region.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="District" required>
        <Select
          value={formData.primary_school_district}
          onChange={(value) => setFormData({ ...formData, primary_school_district: value })}
          placeholder="Select District"
          disabled={!formData.primary_school_region}
        >
          {districts.map((district) => (
            <Select.Option key={district.id} value={district.id}>
              {district.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
    </div>
  );
};

4. Personal Details Section

Description

This section collects personal information and is shown only after NECTA data is fetched (showProfile is true).

Inputs

Date of Birth (dob):
- Type: Date picker (<DatePicker> from Antd)
- Format: "YYYY-MM-DD"
- Year Range: 1970 to 10 years ago
- Required: Yes
Nationality (country_id_nationality):
- Type: Dropdown (<Select> from Antd)
- Options: List of countries
- Required: Yes
Country of Residence (country_id_residence):
- Type: Dropdown (<Select> from Antd)
- Options: List of countries
- Required: Yes
Marital Status (marital_status):
- Type: Dropdown (<Select> from Antd)
- Options: "Single", "Married", "Other"
- Required: Yes
Impairment (impairment_id):
- Type: Dropdown (<Select> from Antd)
- Options: List of impairments
- Required: Yes

Steps

Fetch countries and impairments when the component mounts.
Allow the user to select their date of birth, nationality, residence, marital status, and impairment.

When to Fetch Data from Backend

Countries: Reuse the /api/countries endpoint from the Secondary School section.
Impairments: Fetch when the component mounts.
- Request: GET /api/impairments
- Sample Response:
```
[
  { "id": 1, "name": "None" },
  { "id": 2, "name": "Visual" }
]
```

React Implementation

import { Form, Select, DatePicker } from "antd";
import { useEffect, useState } from "react";
import moment from "moment";

const PersonalDetailsSection = ({ formData, setFormData }) => {
  const [countries, setCountries] = useState([]);
  const [impairments, setImpairments] = useState([]);
  const maritalOptions = ["Single", "Married", "Other"];

  useEffect(() => {
    const fetchData = async () => {
      setCountries([
        { id: 1, name: "Tanzania" },
        { id: 2, name: "Kenya" },
      ]);
      setImpairments([
        { id: 1, name: "None" },
        { id: 2, name: "Visual" },
      ]);
    };
    fetchData();
  }, []);

  return (
    <div>
      <h5>Personal Details</h5>
      <Form.Item label="Date of Birth" required>
        <DatePicker
          value={formData.dob ? moment(formData.dob) : null}
          onChange={(date) =>
            setFormData({ ...formData, dob: date ? date.format("YYYY-MM-DD") : "" })
          }
          format="YYYY-MM-DD"
          disabledDate={(current) =>
            current && (current < moment("1970-01-01") || current > moment().subtract(10, "years"))
          }
        />
      </Form.Item>
      <Form.Item label="Nationality" required>
        <Select
          value={formData.country_id_nationality}
          onChange={(value) => setFormData({ ...formData, country_id_nationality: value })}
          placeholder="Select Nationality"
        >
          {countries.map((country) => (
            <Select.Option key={country.id} value={country.id}>
              {country.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="Country of Residence" required>
        <Select
          value={formData.country_id_residence}
          onChange={(value) => setFormData({ ...formData, country_id_residence: value })}
          placeholder="Select Country of Residence"
        >
          {countries.map((country) => (
            <Select.Option key={country.id} value={country.id}>
              {country.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="Marital Status" required>
        <Select
          value={formData.marital_status}
          onChange={(value) => setFormData({ ...formData, marital_status: value })}
          placeholder="Select Marital Status"
        >
          {maritalOptions.map((status) => (
            <Select.Option key={status} value={status}>
              {status}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
      <Form.Item label="Impairment" required>
        <Select
          value={formData.impairment_id}
          onChange={(value) => setFormData({ ...formData, impairment_id: value })}
          placeholder="Select Impairment"
        >
          {impairments.map((impairment) => (
            <Select.Option key={impairment.id} value={impairment.id}>
              {impairment.name}
            </Select.Option>
          ))}
        </Select>
      </Form.Item>
    </div>
  );
};

5. Contact Details Section

Description

This section collects the applicant’s contact information and is shown only after NECTA data is fetched.

Inputs

Email (email):
- Type: Text input (<Input> from Antd)
- Validation: Remove spaces on input
- Required: Yes
Phone (phone):
- Type: Text input (<Input> from Antd)
- Required: Yes

Steps

Allow the user to input their email and phone number.
Remove spaces from the email input in real-time.

React Implementation

import { Form, Input } from "antd";

const ContactDetailsSection = ({ formData, setFormData }) => {
  return (
    <div>
      <h5>Contact Details</h5>
      <Form.Item label="Email" required>
        <Input
          value={formData.email}
          onChange={(e) =>
            setFormData({ ...formData, email: e.target.value.replace(/\s/g, "") })
          }
        />
      </Form.Item>
      <Form.Item label="Phone" required>
        <Input
          value={formData.phone}
          onChange={(e) => setFormData({ ...formData, phone: e.target.value })}
        />
      </Form.Item>
    </div>
  );
};

6. Password Section

Description

This section collects the applicant’s password and is shown only after NECTA data is fetched.

Inputs

Password (password):
- Type: Password input (<Input.Password> from Antd)
- Required: Yes
Re-enter Password (re_password):
- Type: Password input (<Input.Password> from Antd)
- Required: Yes
- Validation: Must match password

Steps

Allow the user to input and confirm their password.
Validate that the passwords match on the form submission.

React Implementation

import { Form, Input } from "antd";

const PasswordSection = ({ formData, setFormData }) => {
  return (
    <div>
      <h5>Password</h5>
      <Form.Item label="Password" required>
        <Input.Password
          value={formData.password}
          onChange={(e) => setFormData({ ...formData, password: e.target.value })}
        />
      </Form.Item>
      <Form.Item label="Re-enter Password" required>
        <Input.Password
          value={formData.re_password}
          onChange={(e) => setFormData({ ...formData, re_password: e.target.value })}
        />
      </Form.Item>
    </div>
  );
};

Form Submission

Description

The form ends with "Register" and "Cancel" buttons. Submitting the form sends all collected data to the backend.

Steps

Validate the form (e.g., required fields, password match).
Send the form data to the backend via a POST request.
Display success or error messages based on the response.

When to Fetch Data from Backend

Registration: On form submission.

Request: POST /api/register
Request Body:

{
  "programme_level_id": 1,
  "academic_year": "2023/2024",
  "intake_description": "September Intake",
  "csee_country_id": 1,
  "index_number": "S1234/5678",
  "exam_year": "2020",
  "primary_school": "Sample Primary",
  "primary_school_region": 1,
  "primary_school_district": 1,
  "first_name": "John",
  "middle_name": "Middle",
  "surname": "Doe",
  "dob": "2000-01-01",
  "country_id_nationality": 1,
  "country_id_residence": 1,
  "marital_status": "Single",
  "impairment_id": 1,
  "email": "user@example.com",
  "phone": "1234567890",
  "password": "password123",
  "re_password": "password123"
}

Sample Success Response:

{
  "status": "success",
  "message": "Registration successful"
}

Sample Error Response:

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["Email is already taken"],
    "password": ["Password must be at least 8 characters"]
  }
}

React Implementation (Parent Component)

import { Form, Button, message } from "antd";
import { useState } from "react";
import ApplicationCategorySection from "./ApplicationCategorySection";
import SecondarySchoolSection from "./SecondarySchoolSection";
import PrimarySchoolSection from "./PrimarySchoolSection";
import PersonalDetailsSection from "./PersonalDetailsSection";
import ContactDetailsSection from "./ContactDetailsSection";
import PasswordSection from "./PasswordSection";

const RegistrationForm = () => {
  const [formData, setFormData] = useState({
    programme_level_id: "",
    academic_year: "",
    intake_description: "",
    csee_country_id: "",
    index_number: "",
    exam_year: "",
    primary_school: "",
    primary_school_region: "",
    primary_school_district: "",
    first_name: "",
    middle_name: "",
    surname: "",
    dob: "",
    country_id_nationality: "",
    country_id_residence: "",
    marital_status: "",
    impairment_id: "",
    email: "",
    phone: "",
    password: "",
    re_password: "",
  });
  const [nectaData, setNectaData] = useState(null);
  const [showProfile, setShowProfile] = useState(false);

  const handleSubmit = async () => {
    if (formData.password !== formData.re_password) {
      message.error("Passwords do not match");
      return;
    }
    // Simulate API call
    const response = { status: "success", message: "Registration successful" };
    if (response.status === "success") {
      message.success(response.message);
    } else {
      message.error(response.message);
    }
  };

  return (
    <Form onFinish={handleSubmit}>
      <ApplicationCategorySection formData={formData} setFormData={setFormData} />
      {formData.programme_level_id && (
        <SecondarySchoolSection
          formData={formData}
          setFormData={setFormData}
          setNectaData={setNectaData}
          setShowProfile={setShowProfile}
        />
      )}
      {showProfile && (
        <>
          <PrimarySchoolSection formData={formData} setFormData={setFormData} />
          <PersonalDetailsSection formData={formData} setFormData={setFormData} />
          <ContactDetailsSection formData={formData} setFormData={setFormData} />
          <PasswordSection formData={formData} setFormData={setFormData} />
          <Form.Item>
            <Button type="primary" htmlType="submit">
              Register
            </Button>
            <Button style={{ marginLeft: 8 }} danger onClick={() => window.location.href = "/"}>
              Cancel
            </Button>
          </Form.Item>
        </>
      )}
    </Form>
  );
};

export default RegistrationForm;

Summary for the Developer

Structure: Use a parent RegistrationForm component with child components for each section.
Initial Data: Fetch application categories, countries, regions, and impairments on mount.
Dynamic Fetching: Fetch NECTA data on Secondary School input changes and districts on region selection.
Conditional Rendering: Show Secondary School if categories exist, and profile sections after NECTA data is fetched.
UI: Use Ant Design components (Form, Select, Input, DatePicker, Button, Spin) for consistency.
Validation: Implement client-side checks (e.g., required fields, password match).
Submission: Send all form data to /api/register and handle responses.

This document outlines the UI development process using mock JSON data. Backend implementation details are outside the scope of this guide; however, you may use any suitable backend technology such as Laravel, Node.js, or Python. The choice of backend technology depends on project requirements.