feat: replace built-in pddikti with pluggable provider api

feat: add wastu.fyi provider

Author: sooluh

README.md

@@ -24,7 +24,7 @@ Install the package with:
 composer require wastukancana/nim
 ```
 
-## Example
+## Usage
 
 ```php
 <?php
@@ -42,13 +42,60 @@ try {
 }
 ```
 
+Example dump without provider (name/gender/isGraduated null):
+
+```php
+$student = (new Nim('211351143'))->dump();
+/* object(Wastukancana\Student) {
+    nim: "211351143",
+    name: null,
+    gender: null,
+    isGraduated: null,
+    admissionYear: 2021,
+    study: "Teknik Informatika",
+    educationLevel: "S1",
+    firstSemester: 1,
+    sequenceNumber: 143
+} */
+```
+
+### Provider (optional)
+
+You can enrich student data by plugging one optional provider class (FQCN). Without a provider, only parser-derived fields are available (year, study, level, semester, sequence). Fields like name, gender, and graduation status will be null until a provider is used.
+
+```php
+use Wastukancana\Nim;
+use Wastukancana\Provider\PDDikti;
+use Wastukancana\Provider\WastuFyi;
+
+$nim = '211351143';
+
+// Using PDDikti provider (pass FQCN)
+$student = (new Nim($nim, PDDikti::class))->dump();
+
+// Using Wastu.FYI provider (requires a Bearer token)
+$token = getenv('WASTU_FYI_TOKEN');
+$student = (new Nim($nim, WastuFyi::class, ['token' => $token])))->dump();
+/* object(Wastukancana\Student) {
+    nim: "211351143",
+    name: "SULUH SULISTIAWAN",
+    gender: "M",
+    isGraduated: true,
+    admissionYear: 2021,
+    study: "Teknik Informatika",
+    educationLevel: "S1",
+    firstSemester: 1,
+    sequenceNumber: 143
+} */
+```
+
 ## Development
 
 Run code style checks and tests locally:
 
 ```bash
 composer psr2check
-php vendor/bin/phpunit --testdox tests
+composer tests
 ```
 
 This repository uses GitHub Actions to run the matrix CI against PHP 7.4 and 8.x with coverage reporting to Codecov.

composer.json

@@ -1,47 +1,48 @@
 {
-    "name": "wastukancana/nim",
-    "type": "library",
-    "description": "STT Wastukancana Student ID (NIM) Parser",
-    "version": "1.2.1",
-    "homepage": "https://github.com/sooluh/waska-nim",
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "Abu Masyail",
-            "email": "suluhs@aol.com",
-            "homepage": "https://suluh.my.id",
-            "role": "Maintainer"
-        }
+  "name": "wastukancana/nim",
+  "type": "library",
+  "description": "STT Wastukancana Student ID (NIM) Parser",
+  "version": "1.2.1",
+  "homepage": "https://github.com/sooluh/waska-nim",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Abu Masyail",
+      "email": "suluhs@aol.com",
+      "homepage": "https://suluh.my.id",
+      "role": "Maintainer"
+    }
+  ],
+  "support": {
+    "source": "http://github.com/sooluh/waska-nim",
+    "docs": "https://github.com/sooluh/waska-nim/blob/master/README.md",
+    "issues": "https://github.com/sooluh/waska-nim/issues"
+  },
+  "scripts": {
+    "psr2check": [
+      "@php vendor/bin/phpcs --standard=PSR2 --ignore=tests/*,vendor/* ."
+    ],
+    "psr2autofix": [
+      "@php vendor/bin/phpcbf --standard=PSR2 --ignore=tests/*,vendor/* ."
     ],
-    "support": {
-        "source": "http://github.com/sooluh/waska-nim",
-        "docs": "https://github.com/sooluh/waska-nim/blob/master/README.md",
-        "issues": "https://github.com/sooluh/waska-nim/issues"
-    },
-    "scripts": {
-        "psr2check": [
-            "@php vendor/bin/phpcs --standard=PSR2 --ignore=tests/*,vendor/* ."
-        ],
-        "psr2autofix": [
-            "@php vendor/bin/phpcbf --standard=PSR2 --ignore=tests/*,vendor/* ."
-        ],
-        "tests": [
-            "@php vendor/bin/phpunit --testdox tests",
-            "@php vendor/bin/phpunit --coverage-html reports"
-        ]
-    },
-    "autoload": {
-        "psr-4": {
-            "Wastukancana\\": "src/"
-        }
-    },
-    "require": {
-        "php": "^7.4|^8.0",
-        "guzzlehttp/guzzle": "^7.8"
-    },
-    "require-dev": {
-        "squizlabs/php_codesniffer": "^3.7",
-        "phpunit/phpunit": "^9.6",
-        "mikey179/vfsstream": "^1.6"
+    "tests": [
+      "@php vendor/bin/phpunit --testdox tests",
+      "@php vendor/bin/phpunit --coverage-html reports"
+    ]
+  },
+  "autoload": {
+    "psr-4": {
+      "Wastukancana\\": "src/"
     }
+  },
+  "require": {
+    "php": "^7.4|^8.0",
+    "guzzlehttp/guzzle": "^7.8",
+    "laravel/pint": "^1.25"
+  },
+  "require-dev": {
+    "squizlabs/php_codesniffer": "^3.7",
+    "phpunit/phpunit": "^9.6",
+    "mikey179/vfsstream": "^1.6"
+  }
 }

example.php

@@ -1,11 +1,12 @@
 <?php
 
 use Wastukancana\Nim;
+use Wastukancana\Provider\PDDikti;
 
 require __DIR__.'/vendor/autoload.php';
 
 try {
-    $nim = new Nim('91151001');
+    $nim = new Nim('91151001', PDDikti::class);
 
     var_dump($nim->dump());
 } catch (\Exception $e) {

src/Nim.php

@@ -8,14 +8,24 @@ class Nim extends Parser
 {
     private const MIN_YEAR = 2001;
 
-    private PDDikti $pddikti;
+    private ?StudentProviderInterface $provider = null;
 
-    public function __construct($nim)
+    public function __construct($nim, ?string $provider = null, array $options = [])
     {
         parent::__construct($nim);
 
         $this->isValid();
-        $this->pddikti = new PDDikti($this->nim);
+
+        if (is_string($provider)
+            && class_exists($provider)
+            && is_subclass_of($provider, StudentProviderInterface::class)
+        ) {
+            if (array_key_exists('token', $options)) {
+                $this->provider = new $provider($this->nim, $options['token']);
+            } else {
+                $this->provider = new $provider($this->nim);
+            }
+        }
     }
 
     private function isValid(): bool
@@ -41,17 +51,17 @@ private function isValid(): bool
 
     public function getName()
     {
-        return $this->pddikti->getName();
+        return $this->provider ? $this->provider->getName() : null;
     }
 
     public function getGender()
     {
-        return $this->pddikti->getGender();
+        return $this->provider ? $this->provider->getGender() : null;
     }
 
     public function getIsGraduated()
     {
-        return $this->pddikti->getIsGraduated();
+        return $this->provider ? $this->provider->getIsGraduated() : null;
     }
 
     public function isValidAdmissionYear(): bool

src/PDDikti.php src/Provider/PDDikti.phpsrc/PDDikti.php renamed to src/Provider/PDDikti.php

@@ -1,12 +1,13 @@
 <?php
 
-namespace Wastukancana;
+namespace Wastukancana\Provider;
 
 use Exception;
 use GuzzleHttp\Client;
 use Psr\Http\Message\ResponseInterface;
+use Wastukancana\StudentProviderInterface;
 
-class PDDikti
+class PDDikti implements StudentProviderInterface
 {
     private Client $http;
 
@@ -20,9 +21,9 @@ class PDDikti
 
     private ?bool $isGraduated = null;
 
-    public function __construct(string $nim)
+    public function __construct(string $nim, ?Client $client = null)
     {
-        $this->http = new Client([
+        $this->http = $client ?? new Client([
             'base_uri' => 'https://api-pddikti.kemdiktisaintek.go.id',
             'verify' => false,
         ]);

src/Provider/WastuFyi.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace Wastukancana\Provider;
+
+use Exception;
+use GuzzleHttp\Client;
+use Psr\Http\Message\ResponseInterface;
+use Wastukancana\StudentProviderInterface;
+
+class WastuFyi implements StudentProviderInterface
+{
+    private Client $http;
+
+    private string $nim;
+
+    private ?string $name = null;
+
+    private ?string $gender = null;
+
+    private ?bool $isGraduated = null;
+
+    public function __construct(string $nim, string $bearerToken, ?Client $client = null)
+    {
+        $this->http = $client ?? new Client([
+            'base_uri' => 'https://api.wastu.fyi',
+            'verify' => false,
+            'headers' => ['Authorization' => 'Bearer '.$bearerToken],
+        ]);
+        $this->nim = ltrim($nim, '0');
+    }
+
+    private function fetchData(string $endpoint): ?object
+    {
+        try {
+            $response = $this->http->request('GET', $endpoint);
+
+            return $this->parseResponse($response);
+        } catch (Exception $e) {
+            return null;
+        }
+    }
+
+    private function parseResponse(ResponseInterface $response): ?object
+    {
+        $content = $response->getBody()->getContents();
+
+        return json_decode($content);
+    }
+
+    private function prepare(): void
+    {
+        if ($this->name !== null || $this->gender !== null || $this->isGraduated !== null) {
+            return;
+        }
+
+        $response = $this->fetchData('students/detail?student_id='.$this->nim);
+
+        if (! $response) {
+            return;
+        }
+
+        $data = $response->data ?? null;
+
+        if (! $data) {
+            return;
+        }
+
+        $status = isset($data->status) ? strtolower((string) $data->status) : null;
+
+        $this->name = $data->name ?? null;
+        $this->gender = $data->gender ?? null;
+        $this->isGraduated = $status !== null ? ($status === 'lulus') : null;
+    }
+
+    public function getName(): ?string
+    {
+        $this->prepare();
+
+        return $this->name;
+    }
+
+    public function getGender(): ?string
+    {
+        $this->prepare();
+
+        return $this->gender;
+    }
+
+    public function getIsGraduated(): ?bool
+    {
+        $this->prepare();
+
+        return $this->isGraduated;
+    }
+}

src/Student.php

@@ -5,13 +5,20 @@
 class Student
 {
     public string $nim;
+
     public ?string $name = null;
+
     public ?string $gender = null;
+
     public ?bool $isGraduated = null;
 
     public int $admissionYear;
+
     public string $study;
+
     public string $educationLevel;
+
     public int $firstSemester;
+
     public int $sequenceNumber;
 }

src/StudentProviderInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Wastukancana;
+
+interface StudentProviderInterface
+{
+    public function getName(): ?string;
+
+    public function getGender(): ?string;
+
+    public function getIsGraduated(): ?bool;
+}