Neuron CMS Documentation

Overview

Neuron CMS is a database-backed content management system built on the Neuron PHP framework. It provides a complete solution for user authentication, content management, member registration, and administrative operations. The system is designed as a standalone Composer package that integrates seamlessly with the Neuron framework's modular architecture.

Architecture

The CMS component follows a service-oriented architecture with clear separation of concerns:

• Controllers: Handle HTTP request/response cycles for admin, authentication, member, and public interfaces
• Models: Domain entities (User, Post, Category, Tag) with business logic
• Repositories: Data persistence layer with database abstraction
• Services: Business logic encapsulation for complex operations
• Events: Decoupled communication between system components
• Middleware: Request filtering for authentication, CSRF protection, and authorization

System Requirements

• PHP 8.4 or higher
• PDO extension with driver support for SQLite, MySQL, or PostgreSQL
• Composer dependency manager
• ext-curl and ext-json extensions

Dependencies

The CMS package declares the following framework dependencies:

• neuron-php/mvc (0.8.*): MVC framework foundation
• neuron-php/cli (0.8.*): Command-line interface system
• neuron-php/jobs (0.2.*): Background job processing and scheduling
• neuron-php/orm (0.1.*): Object-relational mapping layer
• phpmailer/phpmailer (^6.9): Email delivery subsystem

Feature Overview

Authentication System

• Session-based authentication with configurable lifetime
• Password hashing using Argon2id or Bcrypt algorithms
• CSRF token protection for state-changing operations
• Brute force protection with account lockout mechanism
• "Remember me" functionality with secure token rotation
• Role-based access control (Admin, Editor, Author, Subscriber)

Member Registration

• Public user registration with email verification
• Token-based email verification system
• Rate limiting for verification email resends
• Enumeration protection to prevent email discovery
• Member dashboard with profile management

Content Management

• Blog Posts: Time-based content with categories, tags, and RSS feeds
• Static Pages: Block-based page builder using Editor.js for "About", "Contact", etc.
• Shortcodes/Widgets: WordPress-style shortcodes for dynamic content ([latest-posts], [calendar], [contact-form])
• Category and tag organization with hierarchical support
• SEO-friendly URL slug generation
• Post/page status workflow (Draft, Published, Scheduled)
• View count tracking and analytics
• Extensible widget system for custom shortcodes

Administrative Interface

• Dashboard with system statistics
• User management (CRUD operations, role assignment)
• Post management with bulk operations
• Page management with Editor.js block editor
• Category and tag administration
• Profile management for administrators

Email Subsystem

• PHPMailer integration for reliable delivery
• Template-based email composition
• Password reset email workflow
• Email verification for member registration
• Configurable SMTP, Sendmail, or PHP mail() transports

Background Processing

• Job queue system for asynchronous operations
• Scheduled task execution (cron-like functionality)
• Email queue for bulk sending
• Database or file-based queue storage

Database Support

• PDO-based database abstraction
• Support for SQLite, MySQL, and PostgreSQL
• Phinx integration for schema migrations
• Prepared statement security throughout

Documentation Structure

Getting Started

• Quick Start Guide: Minimal steps to get the CMS operational
• Installation Guide: Comprehensive installation procedures and configuration
• Upgrading Guide: Upgrading CMS to newer versions safely and efficiently

Feature Guides

• Authentication: Session management, login/logout, CSRF protection
• Member Registration: Public registration, email verification, rate limiting
• Requests and DTOs: Request handling, DTO validation, form processing
• User Management: User CRUD operations, role assignment, CLI commands
• Content Management: Posts, categories, tags, publishing workflow
• Database Migrations: Schema versioning, migration commands, seeding
• Email System: SMTP configuration, templates, sending emails
• Background Jobs: Job queue, scheduling, worker processes
• Maintenance Mode: System maintenance, IP whitelisting
• Customization: Extending controllers, creating services, event system

Technical Reference

• Configuration Reference: Complete configuration option documentation
• CLI Commands: Command-line interface reference
• Routing: Route configuration, filters, URL generation
• Models: Data model specifications and relationships
• Services: Service layer architecture and usage
• Events: Complete reference for all 31+ framework events
• Scaffolding: Code generation commands for controllers, events, jobs

Practical Resources

• Common Tasks: Frequently performed operations and recipes
• Security Best Practices: Hardening, authentication, authorization
• Troubleshooting: Common issues and resolution procedures

Quick Navigation by Role

For System Administrators

1. Installation Guide
2. Upgrading Guide
3. Configuration Reference
4. CLI Commands
5. Maintenance Mode

For Developers

1. Getting Started
2. Customization Guide
3. Events Reference - 31+ events across all components
4. Database Migrations Guide
5. Scaffolding Reference
6. Models Reference
7. Services Reference

For Content Managers

1. Content Management Guide
2. User Management Guide
3. Common Tasks

Core Concepts

Repositories

All data access is abstracted through repository interfaces. The CMS provides implementations for:

• IUserRepository: User account management
• IPostRepository: Blog post persistence
• ICategoryRepository: Category organization
• ITagRepository: Tag management
• IPasswordResetTokenRepository: Password reset token storage
• IEmailVerificationTokenRepository: Email verification token storage

Services

Business logic is encapsulated in service classes organized by domain:

• User Services: Creator, Updater, Deleter
• Post Services: Creator, Updater, Publisher, Deleter
• Category Services: Creator, Updater, Deleter
• Tag Services: Creator, Resolver
• Email Services: Sender
• Member Services: RegistrationService

Events

The Neuron framework provides a comprehensive event system with 31+ events across all components:

Framework Events:

• Application (4 events): ApplicationCrashedEvent, ApplicationShuttingDownEvent, ErrorOccurredEvent, FatalErrorEvent
• Jobs (6 events): JobProcessedEvent, JobFailedEvent, JobMaxAttemptsReachedEvent, WorkerStartedEvent, WorkerStoppedEvent, SchedulerJobTriggeredEvent
• MVC (4 events): RequestReceivedEvent, ViewCacheHitEvent, ViewCacheMissEvent, RateLimitExceededEvent

CMS Events (17 events):

• Authentication: UserLoginEvent, UserLoginFailedEvent, UserLogoutEvent
• Email Verification: EmailVerifiedEvent
• Password Reset: PasswordResetRequestedEvent, PasswordResetCompletedEvent
• Maintenance: MaintenanceModeEnabledEvent, MaintenanceModeDisabledEvent
• Content: UserCreated/Updated/DeletedEvent, PostCreated/Published/DeletedEvent, PageCreated/Published/Updated/DeletedEvent, CategoryCreated/Updated/DeletedEvent

Common Use Cases:

• Security monitoring (brute force detection, rate limiting)
• Error tracking (send to Sentry, PagerDuty)
• Performance monitoring (cache effectiveness, job times)
• Audit trails (user actions, system changes)

See Events Reference for complete documentation.

Controllers

The CMS provides pre-built controllers for common operations:

• Admin Controllers: Dashboard, Users, Posts, Categories, Tags, Profile
• Auth Controllers: Login, PasswordReset
• Member Controllers: Registration, Dashboard, Profile
• Public Controllers: Blog, Content, Home

CLI Commands

Command-line utilities for system administration:

• Installation: cms:install
• User Management: cms:user:create, cms:user:list, cms:user:delete
• Maintenance: cms:maintenance:enable, cms:maintenance:disable, cms:maintenance:status
• Queue: queue:install
• Code Generation: mail:generate

Version Information

Current Version: 0.8.x Minimum PHP Version: 8.4 Stability: Development

Support and Resources

• GitHub Repository: github.com/neuron-php/cms
• Issue Tracker: github.com/neuron-php/cms/issues
• Packagist: packagist.org/packages/neuron-php/cms
• Framework Documentation: neuronphp.com

License

MIT License - See LICENSE file for complete terms.