Configuration

Ava CMS's configuration is simple and transparent. All settings live in app/config/ as plain PHP files.

'site' => [
    'name'        => 'My Awesome Site',
    'base_url'    => 'https://example.com',    // Full URL, no trailing slash
    'timezone'    => 'Europe/London',          // php.net/timezones
    'locale'      => 'en_GB',                  // php.net/setlocale
    'date_format' => 'F j, Y',                 // php.net/datetime.format
],

Why PHP Configs?

We use PHP arrays instead of YAML or JSON because:

1. It's Readable: You can add comments to explain why you changed a setting.
2. It's Powerful: You can use constants, logic, or helper functions right in your config.
3. It's Standard: No special parsers or hidden .env files to debug.

The Config Files

Main Settings (ava.php)

This is where you set up your site's identity and behavior.

Site Identity

return [
    'site' => [
        'name'        => 'My Awesome Site',
        'base_url'    => 'https://example.com',    // Full URL, no trailing slash
        'timezone'    => 'Europe/London',          // php.net/timezones
        'locale'      => 'en_GB',                  // php.net/setlocale
        'date_format' => 'F j, Y',                 // php.net/datetime.format
    ],
    // ...
];

In templates: Access site info via $site['name'], $site['url'], and $site['timezone']. See Theming - Template Variables.

Paths

Directory locations for your content, themes, plugins, and other assets.

'paths' => [
    'content'  => 'content',       // Where your Markdown files live
    'themes'   => 'app/themes',    // Where theme folders live
    'plugins'  => 'app/plugins',   // Where plugin folders live
    'snippets' => 'app/snippets',  // Snippets for [snippet] shortcode
    'storage'  => 'storage',       // Cache, logs, and temporary files

    'aliases' => [
        '@media‎:' => '/media/',
    ],
],

All paths are relative to your project root unless they start with /.

Theme

'theme' => 'default',

See: Theming for theme structure, template variables, and development documentation.

Content Index

The content index is a binary snapshot of your content metadata—used to avoid parsing Markdown files on every request.

'content_index' => [
    'mode'           => 'auto',   // When to rebuild: auto, never, always
    'backend'        => 'array',  // Storage: array or sqlite
    'use_igbinary'   => true,     // Faster serialization if available
    'prerender_html' => false,    // Pre-render Markdown during rebuild
],

See: Performance - Content Indexing for detailed explanations of modes, backends, tiered caching, and benchmarks.

Webpage Cache

The webpage cache stores fully-rendered HTML for near-instant serving.

'webpage_cache' => [
    'enabled' => true,
    'ttl'     => null,       // Seconds, or null = until rebuild
    'exclude' => ['/api/*'], // URL patterns to never cache
],

See: Performance - Webpage Caching for how it works, fast-path optimization, and cache management.

Routing

'routing' => [
    'trailing_slash' => false,
],

See: Routing for URL styles, custom routes, and taxonomy URLs.

Content Parsing

Controls how Ava CMS processes your Markdown content files.

'content' => [
    'frontmatter' => [
        'format' => 'yaml',
    ],
    'markdown' => [
        'allow_html'       => true,
        'heading_ids'      => true,
        'disallowed_tags'  => ['script', 'noscript'],
    ],
    'id' => [
        'type' => 'ulid',
    ],
],

See: Writing Content for frontmatter fields and Markdown syntax.

Security

'security' => [
    'shortcodes' => [
        'allow_php_snippets' => true,
    ],
    'preview_token' => null,
],

Preview token usage: Access drafts via https://example.com/path?preview=1&token=your-token

See: Shortcodes - Snippets and Routing - Preview Mode.

Admin Dashboard

The admin dashboard provides a web-based interface for managing your site.

'admin' => [
    'enabled' => false,
    'path'    => '/admin',
    'theme'   => 'cyan',

    'media' => [
        'enabled'          => true,
        'path'             => 'public/media',
        'organize_by_date' => true,
        'max_file_size'    => 10 * 1024 * 1024,   // 10 MB
        'allowed_types'    => [
            'image/jpeg', 'image/png', 'image/gif',
            'image/webp', 'image/svg+xml', 'image/avif',
        ],
    ],
],

See: Admin Dashboard for features, security, and user management.

Debug Mode

Control error visibility and logging for development and troubleshooting.

'debug' => [
    'enabled'        => false,
    'display_errors' => false,
    'log_errors'     => true,
    'level'          => 'errors',
],

Logs

Control log file size and automatic rotation.

'logs' => [
    'max_size'  => 10 * 1024 * 1024,   // 10 MB
    'max_files' => 3,
],

See: CLI - Logs for log viewing and management commands.

CLI Appearance

'cli' => [
    'theme' => 'cyan',
],

Plugins

'plugins' => [
    'sitemap',
    'feed',
    'redirects',
],

Array of plugin folder names to activate. Plugins load in the order listed.

See: Bundled Plugins for sitemap, RSS feed, and redirects configuration.

Custom Settings

Add your own site-specific configuration. Access values in templates with $ava->config():

// In ava.php
'analytics' => [
    'tracking_id' => 'G-XXXXXXXXXX',
    'enabled'     => true,
],

// In templates
<?php if ($ava->config('analytics.enabled')): ?>
    <!-- Analytics code for <?= $ava->config('analytics.tracking_id') ?> -->
<?php endif; ?>

Content Types: content_types.php

Define what kinds of content your site has. Each content type specifies where files live, how URLs are generated, and which templates to use.

<?php

return [
    'page' => [
        'label'       => 'Pages',
        'content_dir' => 'pages',
        'url' => [
            'type' => 'hierarchical',
            'base' => '/',
        ],
        'templates' => [
            'single' => 'page.php',
        ],
        'taxonomies' => [],
        'fields'     => [],
        'sorting'    => 'manual',
    ],

    'post' => [
        'label'       => 'Posts',
        'content_dir' => 'posts',
        'url' => [
            'type'    => 'pattern',
            'pattern' => '/blog/{slug}',
            'archive' => '/blog',
        ],
        'templates' => [
            'single'  => 'post.php',
            'archive' => 'archive.php',
        ],
        'taxonomies' => ['category', 'tag'],
        'sorting'    => 'date_desc',
    ],
];

Content Type Options

Example with Custom Fields

Here's a more complete example showing custom fields for a blog post type:

'post' => [
    'label'       => 'Blog Posts',
    'content_dir' => 'posts',
    'url' => [
        'type'    => 'pattern',
        'pattern' => '/blog/{slug}',
        'archive' => '/blog',
    ],
    'templates' => [
        'single'  => 'post.php',
        'archive' => 'archive.php',
    ],
    'taxonomies' => ['category', 'tag'],
    'sorting'    => 'date_desc',
    
    // Custom fields for validation and admin UI
    'fields' => [
        'author' => [
            'type'     => 'text',
            'label'    => 'Author Name',
            'required' => true,
        ],
        'featured_image' => [
            'type'  => 'text',
            'label' => 'Featured Image URL',
        ],
        'reading_time' => [
            'type'    => 'number',
            'label'   => 'Reading Time (minutes)',
            'min'     => 1,
            'max'     => 60,
            'default' => 5,
        ],
        'featured' => [
            'type'    => 'boolean',
            'label'   => 'Featured Post',
            'default' => false,
        ],
    ],
    
    // Include these fields in archive cache for fast listing access
    'cache_fields' => ['author', 'featured_image', 'reading_time', 'featured'],
],

See: Fields for all available field types (text, number, boolean, select, date, etc.) and validation options.

Taxonomies: taxonomies.php

Taxonomies organize content into groups (categories, tags, authors, etc.).

<?php

return [
    'category' => [
        'label'        => 'Categories',
        'hierarchical' => true,
        'public'       => true,

        'rewrite' => [
            'base'      => '/category',
            'separator' => '/',
        ],

        'behaviour' => [
            'allow_unknown_terms' => true,
            'hierarchy_rollup'    => true,
        ],

        'ui' => [
            'show_counts' => true,
            'sort_terms'  => 'name_asc',
        ],
    ],

    'tag' => [
        'label'        => 'Tags',
        'hierarchical' => false,
        'public'       => true,

        'rewrite' => [
            'base' => '/tag',
        ],

        'behaviour' => [
            'allow_unknown_terms' => true,
        ],

        'ui' => [
            'show_counts' => true,
            'sort_terms'  => 'count_desc',
        ],
    ],
];

Taxonomy Options

Using taxonomies in content:

---
title: My PHP Tutorial
category: Tutorials
tag:
  - php
  - beginner
---

See: Writing Content - Taxonomy Fields for usage examples and Routing - Taxonomy Routes for URL generation.

Environment-Specific Config

Use PHP logic to override settings per environment:

// app/config/ava.php

$config = [
    'site' => [
        'name'     => 'My Site',
        'base_url' => 'https://example.com',
    ],
    'content_index' => ['mode' => 'never'],
    'debug' => ['enabled' => false],
];

// Development overrides
if (getenv('APP_ENV') === 'development') {
    $config['site']['base_url'] = 'http://localhost:8000';
    $config['content_index']['mode'] = 'auto';
    $config['admin']['enabled'] = true;
    $config['debug'] = [
        'enabled'        => true,
        'display_errors' => true,
        'level'          => 'all',
    ];
}

return $config;

Set the environment variable in your server config:

export APP_ENV=development