README

A Laravel package for integrating with Bukua Edtech API services, providing easy access to schools data.

Features

• Authentication with Bukua API using client credentials
• Simple methods to fetch paginated schools data

Prerequisites

Before using this package, ensure you have:

1. Bukua Developer Account

   • Register as an app developer at Bukua Platform - Development Environment or Bukua Platform - Production Environment
   • Create a Core Access App in the selected environment above

2. Application Credentials

   • Obtain your client_id and client_secret from the Bukua Developer Dashboard

3. Laravel Application

   • Laravel 8.x or higher
   • Composer for dependency management

Configuration

1. Add the following to your .env file:

BUKUA_CORE_ACCESS_CLIENT_ID=your-client-id
BUKUA_CORE_ACCESS_CLIENT_SECRET=your-client-secret
BUKUA_BASE_URL="https://bukua-core.apptempest.com"  # Development
# BUKUA_BASE_URL="https://app.bukuaplatform.com"    # Production

Installation

1. In your terminal, run

composer require digram/bukua-access

1. Clear your configuration cache by running

   # For development
   php artisan config:clear && php artisan route:clear
   
   # For production
   php artisan config:cache && php artisan route:cache

Usage

Counties

Get a paginated list of counties:

• App permission: county:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $counties = BukuaAccess::counties(page: 1, per_page: 100);

    print_r($counties);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Subjects

Get a paginated list of subjects:

• App permission: subject:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $subjects = BukuaAccess::subjects(page: 1, per_page: 100);

    print_r($subjects);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

TVETs

Get a paginated list of TVET institutions:

• App permission: tvet:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $tvets = BukuaAccess::tvets(page: 1, per_page: 100);

    print_r($tvets);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Academic Year / Term Dates

Get the current academic year and term dates

• App permission: None

use BukuaAccess\Facades\BukuaAccess;

try {
    $academicYear = BukuaAccess::academicYear();

    print_r($academicYear);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Schools

Get a paginated list of schools:

• App permission: school:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $schools = BukuaAccess::schools(page: 1, per_page: 100);

    print_r($schools);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Schools with Subjects

Get a paginated list of schools with subjects taught:

• App permission: school:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $schoolsWithSubjects = BukuaAccess::schoolsWithSubjects(page: 1, per_page: 100);

    print_r($schoolsWithSubjects);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Schools with Subject Combinations

Get a paginated list of schools with subjects combinations:

• App permission: school:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $schoolsWithSubjectCombinations = BukuaAccess::schoolsWithSubjectCombinations(page: 1, per_page: 100);

    print_r($schoolsWithSubjectCombinations);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Schools with Profiles

Get a paginated list of schools with profiles such as mission statement, fee structure, logo etc:

• App permission: school:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $schoolsWithProfiles = BukuaAccess::schoolsWithProfiles(page: 1, per_page: 100);

    print_r($schoolsWithProfiles);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Schools with Departments

Get a paginated list of schools with departments:

• App permission: school:view

use BukuaAccess\Facades\BukuaAccess;

try {
    $schoolsWithDepartments = BukuaAccess::schoolsWithDepartments(page: 1, per_page: 100);

    print_r($schoolsWithDepartments);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Update Basic School Information

Updates basic school information for a specified school.

Request

Required Permissions

• school_info:update - Application must have this permission to access the endpoint

Parameters

Supported Data Fields

Example Usage

use BukuaAccess\Facades\BukuaAccess;

try {
    $response = BukuaAccess::updateSchoolInfo(
        school_uid: 'efd8cccf-861f-4392-8e77-6a08b056e65e',
        data: [
            'domain' => 'jitahidischool',
            'clean_name' => 'Jitahidi Senior School',
            'year_established' => 2000,
        ]
    );

    print_r($response);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}