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
composer require ernestdefoe/recruiting
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
- A forum member navigates to
/recruiting (or clicks the Recruiting link in the sidebar nav).
- The JS frontend calls the internal API route
GET /api/cfbd-recruits.
- 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=….
- Results are sorted by national ranking, transformed into a clean JSON shape, and cached for the configured duration.
- Recruit records are enriched with On3 headshots (see below) and returned to the client.
- Player cards are rendered with national rank, stars, headshot, physical measurements, high school, hometown, and commitment pill.
- 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, 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:
- Fetches the On3 rankings page for the configured class year (one HTTP request).
- 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.
- Caches the map for 24 hours — subsequent requests read from cache with zero external HTTP calls.
- 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 |
| Player headshots | On3 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
