Getting Started

Prerequisites

Before proceeding, ensure the following requirements are satisfied:

• PHP 8.4 or higher with PDO extension
• Composer installed and available in PATH
• Database server (SQLite recommended for development, MySQL/PostgreSQL for production)
• Write permissions in the target installation directory

Installation

Install the CMS package via Composer:

composer require neuron-php/cms

Automated Setup

The CMS provides an interactive installation command that configures the complete system:

./vendor/bin/neuron cms:install

The installer executes the following operations:

1. Creates application directory structure
2. Publishes view templates to resources/views/
3. Publishes application initializers to app/Initializers/
4. Generates configuration files in config/
5. Creates database migration files
6. Prompts for database configuration
7. Optionally executes migrations to create schema
8. Creates the initial administrative user account

Installer Prompts

The installation process requires the following information:

Database Configuration

• Adapter type (sqlite, mysql, pgsql)
• Connection parameters (host, port, database name)
• Authentication credentials
• Character set (MySQL/MariaDB only)

Application Settings

• System timezone identifier (e.g., America/New_York)
• Site name and title
• Base URL for the application
• Site description

Administrative User

• Username (alphanumeric with underscores/hyphens)
• Email address
• Password (must meet complexity requirements)

Directory Structure

After installation, the following directory structure will exist:

project-root/
├── app/
│   ├── Controllers/          # Application-specific controllers
│   ├── Events/               # Custom event definitions
│   ├── Initializers/         # Bootstrap initializers
│   ├── Jobs/                 # Background job classes
│   ├── Listeners/            # Event listener implementations
│   ├── Models/               # Extended or custom models
│   ├── Repositories/         # Custom repository implementations
│   └── Services/             # Business logic services
├── config/
│   ├── auth.yaml            # Authentication configuration
│   ├── event-listeners.yaml # Event-to-listener mappings
│   ├── neuron.yaml          # Primary application configuration
│   └── routing.yaml         # Routing configuration (URL rewrites, controller paths)
├── db/
│   ├── migrate/             # Phinx migration files
│   └── seed/                # Database seeding scripts
├── public/
│   ├── index.php            # Front controller
│   └── icon.png             # Default favicon
├── resources/
│   └── views/               # Template files
│       ├── admin/           # Administrative interface
│       ├── auth/            # Authentication views
│       ├── blog/            # Public blog templates
│       ├── content/         # Content page templates
│       ├── emails/          # Email templates
│       ├── home/            # Home page templates
│       ├── http_codes/      # Error page templates
│       ├── layouts/         # Layout templates
│       └── member/          # Member area templates
├── storage/
│   ├── cache/               # Application cache
│   ├── logs/                # Log files
│   └── database.sqlite3     # SQLite database (if applicable)
└── vendor/                  # Composer dependencies

Starting the Development Server

Navigate to the public directory and start PHP's built-in web server:

php -S localhost:8000 -t public

Accessing the System

The following endpoints are now available:

• Admin Panel: http://localhost:8000/admin
• Login Page: http://localhost:8000/login
• Public Blog: http://localhost:8000/blog
• Member Registration: http://localhost:8000/register
• Member Dashboard: http://localhost:8000/member (requires authentication)

Initial Login

Access the administrative interface at http://localhost:8000/login using the credentials created during installation.

Background Job Processing (Optional)

If utilizing the job queue or scheduled tasks, start the job processor:

./vendor/bin/neuron jobs:run

This command initiates both the scheduler (for cron-like tasks) and the queue worker (for asynchronous job processing).

Alternatively, run components separately:

# Scheduler only
./vendor/bin/neuron jobs:schedule

# Queue worker only
./vendor/bin/neuron jobs:work

Verification

To verify successful installation:

1. Access the login page and authenticate with the administrative account
2. Navigate to the dashboard at /admin
3. Verify database connectivity by accessing user management at /admin/users
4. Create a test blog post at /admin/posts/create

Common Initial Tasks

Creating Additional Users

./vendor/bin/neuron cms:user:create

Listing Existing Users

./vendor/bin/neuron cms:user:list

Enabling Maintenance Mode

./vendor/bin/neuron cms:maintenance:enable "System updates in progress"

Checking Maintenance Status

./vendor/bin/neuron cms:maintenance:status

Next Steps

• Configuration: Review and customize settings in config/neuron.yaml and config/auth.yaml
• Email Setup: Configure SMTP settings for password reset and member verification emails
• Customization: Extend controllers, create custom services, or modify view templates
• Production Deployment: Consult the Installation Guide for production-specific configuration

Troubleshooting

Database Connection Failures

SQLite: Verify the storage directory exists and has write permissions (755 or 775).

MySQL/PostgreSQL: Confirm the database exists, credentials are correct, and the database server is accessible from the application host.

Session Issues

Ensure the storage directory has appropriate write permissions. Session data is stored in the system's default session directory unless configured otherwise.

View Template Not Found

Verify that view templates were published to resources/views/ during installation. Re-run cms:install if necessary, or manually copy templates from vendor/neuron-php/cms/resources/views/.

Migration Failures

If migrations fail to execute, manually create the database and verify connection parameters in config/neuron.yaml. Ensure the database user has sufficient privileges (CREATE, ALTER, INSERT, UPDATE, DELETE, SELECT).

Additional Documentation

• Installation Guide: Comprehensive installation procedures
• Configuration Reference: Complete configuration options
• CLI Commands: Command-line interface reference
• Authentication Guide: Authentication system details