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' => true,     // 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/*', '/preview/*'], // 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

Ava includes security settings for shortcodes, preview tokens, and HTTP security headers.

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

    'headers' => [
        'content_security_policy' => [
            "default-src 'self'",
            "base-uri 'none'",
            "object-src 'none'",
            "frame-ancestors 'none'",
            "frame-src 'self' https://www.youtube.com https://www.youtube-nocookie.com https://player.vimeo.com",
            "form-action 'self'",
            "connect-src 'self' https:",        // External APIs, analytics
            "img-src 'self' data: https:",      // External images
            "font-src 'self' data: https:",     // Google Fonts, CDNs
            "style-src 'self' 'unsafe-inline' https:",
            "script-src 'self' 'unsafe-inline' https:",
        ],
        'permissions_policy' => [
            'camera=()',
            'microphone=()',
            'geolocation=()',
            'payment=()',
            'usb=()',
            'interest-cohort=()',
        ],
    ],

    'preview_token' => null,
],

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

'headers' => [
    'content_security_policy' => [
        "default-src 'self'",
        "base-uri 'none'",
        "object-src 'none'",
        "frame-ancestors 'none'",
        "frame-src 'self' https://www.youtube.com",
        "form-action 'self'",
        "connect-src 'self' https://www.google-analytics.com",
        "img-src 'self' data:",
        "font-src 'self' data: https://fonts.gstatic.com",
        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
        "script-src 'self' https://www.googletagmanager.com",
    ],
    // ... other headers
],

Permissions Policy disables browser features you don't need. The defaults block camera, microphone, geolocation, payment APIs, USB access, and FLoC tracking. Remove items from the array if your site legitimately needs these features.

HSTS (Strict Transport Security) should be configured at your web server level (Apache, Nginx, Caddy), not in Ava's config.

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'    => '/ava-admin',
    'theme'   => 'cyan',

    'session' => [
        'timeout'    => 1800,  // 30 minutes
        'ip_binding' => false,
    ],

    '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',
        'icon'        => 'description',
        'content_dir' => 'pages',
        'url' => [
            'type' => 'hierarchical',
            'base' => '/',
        ],
        'templates' => [
            'single' => 'page.php',
        ],
        'taxonomies' => [],
        'fields'     => [],
        'sorting'    => 'manual',
        'search' => [
            'enabled' => true,
            'fields'  => ['title', 'body'],
        ],
    ],

    'post' => [
        'label'       => 'Posts',
        'icon'        => 'article',
        'content_dir' => 'posts',
        'url' => [
            'type'    => 'pattern',
            'pattern' => '/blog/{slug}',
            'archive' => '/blog',
        ],
        'templates' => [
            'single'  => 'post.php',
            'archive' => 'archive.php',
        ],
        'taxonomies' => ['category', 'tag'],
        'fields'     => [],
        'sorting'    => 'date_desc',
        'search' => [
            'enabled' => true,
            'fields'  => ['title', 'excerpt', 'body'],
        ],
    ],
];

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'    => 'checkbox',
            '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, checkbox, select, date, etc.) and validation options.

Taxonomies: taxonomies.php

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

<?php

return [
    'category' => [
        'label'        => 'Categories',
        'icon'         => 'folder',
        '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',
        'icon'         => 'tag',
        'hierarchical' => false,
        'public'       => true,

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

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

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

Taxonomy Options

See: Taxonomies for assigning terms to content, term storage, hierarchical terms, and template helpers.

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