Links:

Dependencies:

CI

Neuron-PHP CMS

A modern, database-backed Content Management System for PHP 8.4+ built on the Neuron framework. Provides a complete content platform with a blog, CMS-managed pages, an events calendar with registration, contact forms, reusable content shortcodes/widgets, user authentication, and a full admin panel.

Features

Database Compatibility

All three databases are fully supported with identical behavior across platforms:

Performance Notes:

All databases are tested in CI on every commit to ensure consistent behavior.

Installation

Requirements

Install via Composer

composer require neuron-php/cms

Run the Installer

The cms:install command sets up everything automatically:

php neuron cms:install

The installer will:

  1. Create the complete directory structure (app/, config/, db/, public/, resources/, storage/)
  2. Publish all view templates (admin panel, blog, auth, layouts)
  3. Publish application initializers
  4. Create configuration files (neuron.yaml, routing.yaml, auth.yaml, event-listeners.yaml)
  5. Generate the front controller (public/index.php)
  6. Set up database migrations
  7. Optionally run migrations to create database tables
  8. Prompt you to create an admin user

That's it. The installer handles all setup automatically.

Upgrading

After updating the package with Composer, run the upgrade command to copy any new migrations and resources into your installation:

composer update neuron-php/cms
php neuron cms:upgrade

Useful flags:

The upgrade command preserves your customizations (it won't overwrite views by default) and reports any version-specific notes or breaking changes.

Project Structure

After running cms:install, your project will have the following structure:

your-project/
├── app/
│   ├── Controllers/          # Your custom controllers
│   ├── Events/              # Custom event classes
│   ├── Initializers/        # Application initializers
│   │   ├── AuthInitializer.php
│   │   ├── MaintenanceInitializer.php
│   │   ├── PasswordResetInitializer.php
│   │   └── ViewDataInitializer.php
│   ├── Jobs/                # Background jobs
│   ├── Listeners/           # Event listeners
│   ├── Models/              # Domain models
│   ├── Repositories/        # Data repositories
│   └── Services/            # Business logic services
│
├── config/
│   ├── auth.yaml           # Authentication configuration
│   ├── neuron.yaml         # Main application config
│   ├── event-listeners.yaml # Event listener configuration
│   └── routing.yaml        # Routing configuration (URL rewrites, controller paths)
│
├── db/
│   ├── migrate/            # Database migrations
│   │   ├── *_create_users_table.php
│   │   ├── *_create_posts_table.php
│   │   ├── *_create_pages_table.php
│   │   ├── *_create_categories_table.php
│   │   ├── *_create_tags_table.php
│   │   ├── *_create_events_table.php
│   │   ├── *_create_event_categories_table.php
│   │   ├── *_create_event_registrations_table.php
│   │   ├── *_create_contact_submissions_table.php
│   │   └── *_create_queue_tables.php
│   └── seed/               # Database seeders
│
├── public/
│   ├── index.php          # Front controller
│   └── icon.png           # Default favicon
│
├── resources/
│   └── views/
│       ├── admin/         # Admin panel templates
│       │   ├── categories/
│       │   ├── dashboard/   # Dashboard views
│       │   ├── posts/       # Post management
│       │   ├── pages/       # Page management
│       │   ├── events/      # Event management
│       │   ├── event_categories/
│       │   ├── event_registrations/
│       │   ├── contact_submissions/
│       │   ├── media/
│       │   ├── profile/
│       │   ├── tags/
│       │   └── users/
│       ├── auth/          # Login/password reset
│       ├── blog/          # Public blog views
│       ├── calendar/      # Public calendar/event views
│       ├── pages/         # Public CMS page views
│       ├── member/        # Member registration & dashboard
│       │   ├── dashboard/
│       │   ├── profile/
│       │   └── registration/
│       ├── content/       # Content pages
│       ├── emails/        # Email templates
│       ├── http_codes/    # Error pages
│       └── layouts/       # Layout templates
│
├── storage/
│   ├── cache/            # Cache storage
│   ├── logs/             # Application logs
│   └── database.sqlite3  # SQLite database (if using SQLite)
│
└── composer.json

Quick Start

After running cms:install, you're ready to go!

Start the Development Server

php -S localhost:8000 -t public

Visit:

Log in with the admin credentials you created during installation.

Start the Job System (Optional)

For background jobs and scheduled tasks:

vendor/bin/neuron jobs:run

This runs both the scheduler (for scheduled tasks) and worker (for email sending and background jobs).

Optional Configuration

If you need to customize settings, edit config/neuron.yaml:

site:
  name: My Blog
  title: Welcome to My Blog
  description: A blog about technology
  url: https://example.com

database:
  adapter: sqlite  # or mysql, pgsql
  name: storage/database.sqlite3

All routing, authentication settings, and event listeners are pre-configured by the installer.

Usage

Creating a Blog Post

  1. Log in to the admin panel at /admin
  2. Navigate to Posts → New Post
  3. Enter title, content, categories, and tags
  4. Choose status (Draft, Published, or Scheduled)
  5. Click Save

Managing Categories and Tags

Managing Users

Admin users can:

Member Registration

The CMS supports public member registration with email verification:

  1. Enable Registration: Configure in config/neuron.yaml:

    member:
  registration_enabled: true
  require_email_verification: true

  2. Registration Flow:

  1. Security Features:
  1. Member Dashboard:

Pages and Shortcodes

Create CMS-managed pages in the admin panel (Pages → New Page); they're served at /pages/:slug. Page and post bodies support shortcodes that render dynamic widgets:

Shortcode Renders
[latest-posts] The most recent blog posts
[calendar] An events calendar/list
[featured-event] The next available featured event
[event-registration] A registration form for an event or event category
[contact] A contact form

Examples:

[latest-posts limit="5"]
[featured-event]
[event-registration event="open-house-2026"]
[event-registration category="workshops" limit="3"]
[contact]

Events and Registration

  1. Create events in the admin panel (Events → New Event), optionally assigning an event category.
  2. Mark an event as featured to surface it via [featured-event], and/or enable registration on the event.
  3. For registration, choose visibility (public or members-only) and an optional capacity (leave blank for unlimited).
  4. Place an [event-registration] shortcode on a page/post (single event or the next upcoming dates of a category).
  5. Registrations are stored and reviewable under Admin → Event Registrations; the configured admin recipient is emailed for each new registration. See the Events & Registration configuration below.

Customizing Views

All view templates are in resources/views/ and can be customized:

Running the Job System

Neuron Jobs

The CMS includes a complete job system for scheduled tasks and background processing. You can run it in three different modes:

1. Combined Mode (Recommended)

Run both scheduler and queue worker together with a single command:

vendor/bin/neuron jobs:run

This is the easiest way to run the complete job system. It manages both the scheduler and worker in one process.

Options:

Examples:

# Run with defaults (both scheduler and worker)
vendor/bin/neuron jobs:run

# Run with custom schedule interval and specific queues (in order of priority)
vendor/bin/neuron jobs:run --schedule-interval=30 --queue=emails,notifications

2. Scheduler Only

Run just the scheduler for executing scheduled tasks:

vendor/bin/neuron jobs:schedule

Handles recurring tasks and scheduled jobs defined in config/schedule.yaml.

Options:

3. Worker Only

Run just the queue worker for processing background jobs:

vendor/bin/neuron jobs:work

Processes queued jobs including emails and background tasks.

Options:

Configuration

Authentication

The installer creates config/auth.yaml with sensible defaults. You can customize:

Routing

The CMS uses attribute-based routing defined directly on controller methods. The installer creates config/routing.yaml to configure URL rewrites and controller paths.

URL Rewrites

By default, the CMS rewrites the root URL (/) to /blog. You can customize this in config/routing.yaml:

# config/routing.yaml
rewrites:
  '/': '/custom/landing'  # Rewrite root to your custom controller

controller_paths:
  - path: 'app/Controllers'        # Your controllers first (takes precedence)
    namespace: 'App\Controllers'
  - path: 'vendor/neuron-php/cms/src/Cms/Controllers'
    namespace: 'Neuron\Cms\Controllers'

Then create your custom landing controller:

// app/Controllers/Landing.php
use Neuron\Mvc\Controller;
use Neuron\Routing\Attributes\Get;

class Landing extends Controller
{
    #[Get('/custom/landing', name: 'landing')]
    public function index()
    {
        return $this->renderHtml(OK, [], 'custom-home');
    }
}

URL rewrites are transparent (no HTTP redirect) - the browser URL stays the same while the application routes to a different path internally.

Available Routes

The CMS provides these pre-configured routes via controller attributes:

For more information about routing configuration, URL rewrites, and attribute-based routing, see the MVC Routing Documentation.

Email

Configure email in config/neuron.yaml:

email:
  driver: smtp                    # smtp, sendmail, or mail
  host: smtp.example.com
  port: 587
  username: [email protected]
  password: your_password
  encryption: tls                 # tls or ssl
  from_address: [email protected]
  from_name: My Blog
  test_mode: false               # optional - logs emails instead of sending

Events & Registration

Event registration notifications are configured under the events.registration section of config/neuron.yaml:

events:
  registration:
    notify_email: "[email protected]"  # admin recipient for new-registration emails
                                                # (falls back to email.from_address when blank)
    confirmation_enabled: false                 # also email a confirmation to the registrant
    success_message: "Thank you for registering. We look forward to seeing you!"

Rate Limiting

The resend verification email endpoint is protected by rate limiting to prevent DOS attacks and spam. The default configuration is:

These limits are enforced server-side using the ResendVerificationThrottle service, which:

To customize rate limits, modify the throttle configuration in your application initialization:

// app/Initializers/CustomRateLimitInitializer.php
$throttle = new ResendVerificationThrottle(null, [
    'ip_limit' => 10,           // 10 requests per window
    'ip_window' => 600,         // 10 minutes
    'email_limit' => 2,         // 2 resends per window
    'email_window' => 900       // 15 minutes
]);

CLI Commands

The CMS registers the following neuron console commands:

Installation & upgrades

User management

Maintenance mode

Run any command with php neuron <command> (for example, php neuron cms:user:create).

Dependencies

More Information

License

MIT License - see LICENSE file for details