apricot / shoutbox

0.5.2 2026-10-15 02:18 UTC

Requires

• php: >=8.4
• apricot/apricot-core: *

Suggests

• apricot/api: Json endpoints for shouts

MIT

• Alex Brindley

• forum
• example
• chat
• shoutbox
• Apricot

Published on Packagist.org on 2026-10-15 02:49 UTC

README

A neat example extension for apricotbb

A tiny shoutbox (apricot/shoutbox) that works as a functional example of how to build an Apricot extension. It touches a bit of everything extensions have access to

I find functional examples a better teacher than endless docs

Try it

From within an apricot install:

composer require apricot/shoutbox
php apricot/apricot db::migrate

composer require automatically runs theme::install which will publish any bundled assets. Same for composer update commands

Where stuff lives

basic	file
package + discovery	composer.json (type and extra.apricot)
entry point	src/Shoutbox.php. this is where its wired up
config defaults	config/addons/shoutbox.php. is read with Config::get('addons.shoutbox.maxLength'). sites override in apricot/config/addons/shoutbox.php
migrations	migrations/. prefixed with shoutbox_ to prevent clashes
default perms	migrations/shoutbox_002_grant_groups.php
routes + handlers	src/Shouts/ShoutRoutes.php + src/Shouts/ShowShoutbox.php, ShowLatest.php, AddShout.php
templates	templates/shoutbox/. Themes and local templates can override
gateway	src/Shouts/Shouts.php (raw sql) and src/Shouts/Shout.php (row object)
permissions	Shoutbox::VIEW and Shoutbox::SHOUT. handlers + twig can()
template slots	src/Shouts/PlaceShoutbox.php uses the index.end slot
listeners	src/Shouts/WelcomeMember.php (signups) + src/Shouts/MoveMentions.php (renames)
refuse posts	src/Shouts/HushCaps.php. prevents all caps posts
custom event	src/Hooks/Events/ShoutCreatedEvent.php. used by AddShout::add(). other extensions can use hook too
notifications	src/Shouts/ChirpMentioned.php notifies anyone @mentioned in a shout
markdown	src/Shouts/Markdown/ adds !!loud!! which also works in normal posts
admin settings	src/Settings/Megaphone.php + templates/admin/shoutbox/settings.twig
admin page	src/Admin/ + templates/admin/shoutbox/index.twig. adds a sidebar link
assets	assets/{css,js,svg}/shoutbox/. queued with boot()
cli + schedule	src/CLI/PruneShouts.php. the shouts::prune command. runs nightly with queue::work worker
flood control	shout normal throttle rule in register()
shared rules	add() in src/Shouts/AddShout.php. form and api both call it so the rules live in one spot
json api	src/Shouts/ServeShouts.php + TakeShout.php + ShapeShout.php. only available when apricot/api is installed. see ShoutRoutes::calls()
data	Api::share('shoutbox', ...) in Shoutbox.php

Things to try

• shout something from the index
• mention someone with @name, they get a notification
• sign up and see a welcome shout (can be turned off)
• turn on Refuse all caps and try and yell
• php apricot/apricot shouts::prune for some cleanup
• install apricot/api and check out /api/v1/shouts