FBSFB Recruiting

A Flarum 2 extension that pulls live college football recruiting rankings from the College Football Data API and displays them on a dedicated /recruiting page inside your Flarum forum.

---

Features

• Live data — recruiting rankings pulled directly from the CFBD API and cached server-side

• Player headshots — automatically sourced from On3's football rankings page; falls back to a star-tier coloured initials avatar when no photo is available

• Full player details — national rank, star rating, numerical rating, position, height, weight, high school, hometown, and commitment status

• Filters — search by name / school / city, filter by position, filter by committed vs. undecided

• Stats bar — total recruits displayed, average rating, committed count

• Responsive grid — adapts from 4–5 columns on desktop down to 2 on mobile

| Mobile view |

|---|

| |

---

Requirements

• Flarum 2.x

• PHP 8.3+

• A free CFBD API key from collegefootballdata.com

• guzzlehttp/guzzle ^7.0 (pulled in automatically via Composer)

---

Installation

php flarum migrate
php flarum cache:clear```

Then enable the extension in **Admin → Extensions**.

---

## Configuration

All settings are found in **Admin → Extensions → FBSFB Recruiting**.

| Setting | Description | Default |

|---|---|---|

| **API Key** | Your CFBD bearer token | *(required)* |

| **Recruiting Year** | Class year to display (e.g. `2026`) | Current calendar year |

| **Team Filter** | Show only recruits committed to a specific team (e.g. `Alabama`). Leave blank for national rankings. | *(blank — national)* |

| **Max Recruits** | How many recruits to display (1–100) | `25` |

| **Cache Duration** | How long to cache CFBD responses in minutes | `360` (6 hours) |

---

## How it works

1. A forum member navigates to `/recruiting` (or clicks the **Recruiting** link in the sidebar nav).
2. The JS frontend calls the internal API route `GET /api/cfbd-recruits`.
3. The PHP controller reads your admin settings, checks Flarum's cache, and if needed proxies a request to `https://api.collegefootballdata.com/recruiting/players?year=…&team=…`.
4. Results are sorted by national ranking, transformed into a clean JSON shape, and cached for the configured duration.
5. Recruit records are enriched with On3 headshots (see below) and returned to the client.
6. Player cards are rendered with national rank, stars, headshot, physical measurements, high school, hometown, and commitment pill.
7. Client-side filters let users narrow by position, commitment status, or keyword search instantly without a second API call.

---

## Player headshots

Headshots are sourced from [**On3**](https://www.on3.com/), which maintains photos for thousands of current and historical high-school recruits.

### How the image lookup works

On3's football rankings page (`on3.com/rivals/rankings/player/football/{year}/`) is fully server-rendered HTML containing 150+ ranked recruits, each with a profile link and headshot image URL embedded directly in the markup.

On the first API call after the cache is empty the extension:

1. Fetches the On3 rankings page for the configured class year (one HTTP request).
2. Parses the HTML to build a **name → image URL** map using positional matching between profile hrefs (`/rivals/jared-curtis-159433/`) and `on3static.com` image paths.
3. Caches the map for **24 hours** — subsequent requests read from cache with zero external HTTP calls.
4. Matches each CFBD recruit to the map by normalised name slug (e.g. `"Jared Curtis"` → `"jared-curtis"`).

### Fallback avatars

When no On3 photo is available the card shows a coloured initials avatar whose background is coded by star rating:

| Stars | Colour |

|---|---|

| ★★★★★ | Gold |

| ★★★★ | Blue |

| ★★★ | Green |

| ★★ / unrated | Slate |

---

## Player card data

Each card displays:

* **National ranking** (`#1`, `#2`, …)
* **Star rating** (★★★★★) and **numerical rating** (e.g. `0.9991`)
* **Headshot** — sourced from On3; coloured initials avatar as fallback
* **Name** and **position** (QB, WR, CB, OT, DE, …)
* **Height · Weight** (e.g. `6'3" · 215 lbs`)
* **High school** name
* **Hometown** (City, State)
* **Commitment pill** — `

✔ Georgia` (green) or `○ Undecided` (grey) --- ## Data sources | Data | Source | |---|---| | Rankings, ratings, recruit details | [College Football Data API](https://collegefootballdata.com/) | | Player headshots | [On3](https://www.on3.com/) rankings page | CFBD provides a free API key with generous rate limits. The extension caches all external responses to minimise outbound requests. --- ## License MIT <https://ernestdefoe.online/extension/ernestdefoe/recruiting>

recruiting v2.0.13

What's Changed

• No changes

Full Changelog: https://github.com/ernestdefoe/recruiting/compare/2.0.12...v2.0.13

View release on GitHub

recruiting 2.0.15

No changes made.

View release on GitHub

recruiting 2.0.15

No commits between v2.0.13 and 2.0.15.

View release on GitHub

recruiting 3.0.0

What's Changed

• Build changelog from commits when release body is a placeholder
• Replace release-drafter with commit-based draft-release workflow
• Add workflow_dispatch trigger to publish-to-flarum.yml
• Convert to TypeScript (audit fix)
• docs: add Floxum marketplace badges to README

Full Changelog: https://github.com/ernestdefoe/recruiting/compare/2.0.15...3.0.0

View release on GitHub

recruiting 3.1.0

What's Changed

A full internal code audit — one new admin setting, plus reliability, ethics, and type-safety fixes under the hood.

New

• Disable On3 headshots. A new admin toggle (Enable On3 player headshots) lets you stop all outbound traffic to On3 entirely — recruits then show star-tier initials avatars. The setting's help text documents exactly what the scrape does, and the admin panel now shows when headshots were last successfully refreshed.

Fixed

• No more request stampede on a cold cache. The first request for a recruiting class used to make two blocking outbound calls (~22 s) with no lock, so a burst of visitors each launched their own pair of fetches. A single-flight lock now guarantees at most one cold fetch; everyone else serves the warmed cache or retries automatically.
• Honest scraping. Removed the spoofed Chrome browser User-Agent used to bypass On3's bot detection (a ToS/identity-spoofing risk that could get the forum's IP blocked). The fetch now identifies itself truthfully.
• Layout-change detection. If On3 returns a page but almost no players parse out, the extension now logs a warning instead of silently dropping all headshots.

Internal

• The outbound HTTP client is now container-managed and injected, so operators can layer forum-wide middleware (logging, retry, proxy).
• The /recruiting page is fully TypeScript-type-checked (the prior @ts-nocheck escape hatch is gone), and the API URL is derived correctly for subdirectory installs.

View release on GitHub

recruiting 3.1.1

Floxum audit hardening (→ ≥95). Cold-lock window 30→60s (headroom for CFBD + On3 timeouts), assertRegistered() guard on the API, native fetch → app.request, and admin settings wired through the translator.

View release on GitHub