Download the PHP package weeklify/ez-knowledge-base without Composer

EzKnowledgeBase

A self-contained Laravel package that provides a fully themed knowledge base with categorised articles, full-text search, support tickets, and a REST API — all configurable via a single config file.

Features

• Responsive landing page with hero search, category grid, and featured articles
• Category and article browsing with sidebar navigation
• Full-text fuzzy search powered by Laravel Scout + TNTSearch
• Markdown article bodies rendered to HTML with auto-generated table of contents
• Session-based unique view counting
• Article feedback (helpful yes/no)
• Support ticket submission form with Cloudflare Turnstile spam protection
• Email notifications on admin/staff ticket replies with direct email reply support
• Inbound email processing via Brevo webhook for customer replies
• Trait-based user integration (customer, staff, and admin roles)
• REST API with dual authentication (API key or Sanctum)
• Fully configurable branding: logo, colours, fonts, copy, footer links
• Built-in caching with automatic invalidation
• Dark mode support

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Laravel Scout + TNTSearch driver (for search)
• Laravel Sanctum (optional, for token-based API auth)

Installation

1. Install via Composer

The service provider is auto-discovered via Laravel's package discovery. If you need to register it manually, add to config/app.php providers array:

2. Publish config and assets

3. Run migrations

This creates the kb_categories, kb_articles, kb_tags, kb_article_tag, kb_tickets, and kb_ticket_replies tables, along with a user_id foreign key on kb_tickets.

4. Seed sample data (optional)

5. Set up search (optional but recommended)

Add to .env:

The host app should extend the package's base KbArticle model and add the Searchable trait:

Import existing articles into the search index:

6. Set up user integration

Add the KB traits to your User model depending on the roles you need:

Configure admin email addresses in config/kb.php:

7. Set up email ticket replies (optional)

When enabled, admin/staff replies to support tickets automatically email the customer. Customers can reply directly to those emails, which are processed via Brevo's inbound parse webhook and stored as ticket replies.

Add to your .env:

Brevo inbound parse setup:

1. In your Brevo account, go to Transactional → Settings → Inbound Parse
2. Add a new inbound rule for your reply domain (e.g. parse.yourdomain.com)
3. Set the webhook URL to https://yourdomain.com/webhook/kb/inbound
4. Ensure your DNS MX record for the reply domain points to Brevo's inbound servers

Webhook authentication: The webhook is secured via the X-Brevo-Secret header. You must set KB_REPLY_WEBHOOK_SECRET — the webhook will return 403 if no secret is configured. The secret is only accepted via the X-Brevo-Secret header (query parameters are not supported).

Brevo dependency: The getbrevo/brevo-php package is suggested but not required. Install it if you need Brevo API integration beyond inbound webhooks:

CSRF exemption: The webhook route is registered outside the web middleware group, but you should also add webhook/kb/inbound to your VerifyCsrfToken middleware's $except array if your app applies CSRF globally.

How it works:

1. Admin/staff replies to a ticket in the admin panel
2. The KbTicketReplied event fires, triggering the SendTicketReplyNotification queued listener
3. An email is sent to the customer with a Reply-To address containing an HMAC-signed token (e.g. ticket+{token}@parse.yourdomain.com)
4. When the customer replies, Brevo's inbound parse POSTs the email to your webhook
5. The webhook verifies the token (valid for 30 days by default), validates the sender email matches the ticket, checks spam score, sanitizes the HTML body, and stores the reply

The feature degrades gracefully — when KB_REPLY_ENABLED=false (the default), admin replies work normally with no emails sent.

8. Set up Cloudflare Turnstile (optional but recommended)

The ticket submission form supports Cloudflare Turnstile for spam protection. Add your Turnstile keys to config/services.php:

And in your .env:

When configured, the Turnstile widget is automatically rendered on the ticket form and verified server-side on submission. When not configured, the form works without it.

User Traits

The package provides three traits for integrating the ticket system with your User model:

CanKbTicket (Customer)

ManageKbTicket (Staff/Agent)

AdminKbTicket (Admin)

Ticket Submission (Guests & Authenticated Users)

The ticket form supports both guest and authenticated submissions:

• Guest: must provide name and email in the form
• Authenticated user: name and email are auto-filled from the user model, and the ticket is linked via user_id

Web Routes

All web routes are prefixed with /help-center and use the web middleware group.

API Endpoints

All API routes are prefixed with /api/kb, rate-limited, and require authentication.

API Authentication

The API accepts either of these authentication methods:

Option 1 — Static API Key (simplest)

Set a key in .env:

Then pass it via header:

Option 2 — Sanctum Bearer Token

Use a standard Sanctum personal access token:

Example API Responses

GET /api/kb

GET /api/kb/categories/{slug}/{article}

Configuration

After publishing (php artisan vendor:publish --tag=kb-config), edit config/kb.php to customise your knowledge base.

Environment Variables

Config Sections

The config/kb.php file is organised into these sections:

• brand — name, tagline, copyright, address
• logo — url, alt text, height classes
• colors — primary, background light/dark
• font — family, Google Fonts URL
• search — placeholder text
• hero — landing page title and subtitle
• support — enabled toggle, label, email, website
• footer — configurable link columns
• api — key, rate limit
• reply — email reply feature: enabled toggle, domain, from address/name, token/webhook secrets, spam threshold, token TTL
• users — user model class, admin email list

Package Structure

Models

The package provides five Eloquent models in the EzKnowledgeBase\Models namespace:

• KbCategory — kb_categories table. Has many articles. Supports is_active flag and sort_order.
• KbArticle — kb_articles table. Belongs to a category, has many tags. Supports is_published, is_featured, view counting, and helpfulness votes. The host app can extend this model to add Laravel Scout.
• KbTag — kb_tags table. Many-to-many with articles via kb_article_tag pivot.
• KbTicket — kb_tickets table. Stores support ticket submissions. Optionally linked to a user via user_id.
• KbTicketReply — kb_ticket_replies table. Stores replies to tickets with is_admin flag and optional user_id.

Caching

The package caches expensive queries with automatic invalidation:

Cache invalidation is handled via Eloquent model event listeners registered in the service provider.

Customising Views

To override any Blade view, publish them to your app:

Views will be copied to resources/views/vendor/kb/ where you can edit them freely. The package will use your custom views over its built-in ones.

Adding Articles

Articles are stored in database/seeders/data/kb/ as PHP arrays with markdown bodies using nowdoc syntax:

After adding articles to the seeder data files, run:

Articles can also be managed through the Filament admin panel.