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 blog platform with user authentication, admin panel, and content management.

Features

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.

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
│   ├── 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_categories_table.php
│   │   ├── *_create_tags_table.php
│   │   └── *_create_queue_tables.php
│   └── seed/               # Database seeders
│
├── public/
│   ├── index.php          # Front controller
│   └── icon.png           # Default favicon
│
├── resources/
│   └── views/
│       ├── admin/         # Admin panel templates
│       │   ├── dashboard/ # Dashboard views
│       │   ├── posts/     # Post management
│       │   ├── categories/
│       │   ├── tags/
│       │   ├── users/
│       │   └── profile/
│       ├── auth/          # Login/password reset
│       ├── blog/          # Public blog views
│       ├── 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.

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 routes, 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:

Customizing Views

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

Scheduling Jobs

Start the scheduler:

php neuron jobs:schedule

This will process scheduled jobs.

Running Background Jobs

Start the queue worker:

php neuron jobs:work

This will process queued jobs like sending emails in the background.

Testing

Run the test suite:

# Run all tests
vendor/bin/phpunit tests

# Run with coverage
vendor/bin/phpunit tests --coverage-text

# Run specific test
vendor/bin/phpunit tests/Cms/BlogControllerTest.php

Configuration

Authentication

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

Routing

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

Default routes provided:

Customize the homepage:

By default, the root URL (/) is rewritten to /blog. To use a custom homepage, edit config/routing.yaml:

rewrites:
  '/': '/custom/landing'  # Route to your custom controller

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

Then create your custom controller:

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

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

See the Routing Reference for complete 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

Dependencies

More Information

License

MIT License - see LICENSE file for details