# Configuration

> Configure a new Pollora project: environment variables, the database, WordPress settings, and fixes for common setup issues.

Source: https://pollora.dev/getting-started/configuration/

- [Initial Configuration](#initial-configuration)
    - [Environment Based Configuration](#environment-based-configuration)
    - [Databases & Migrations](#databases-and-migrations)
    - [Directory Configuration](#directory-configuration)
- [WordPress Configuration](#wordpress-configuration)
    - [Publishing the Configuration File](#publishing-the-configuration-file)
    - [Customizing Route Conditions](#customizing-route-conditions)
    - [WordPress Authentication Keys](#wordpress-authentication-keys)
    - [Multisite Configuration](#multisite-configuration)
    - [Database Caching](#database-caching)
    - [WordPress Constants](#wordpress-constants)
- [Environment Variables](#environment-variables)
- [Development Environments](#development-environments)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)

<a name="initial-configuration"></a>
## Initial Configuration

All configuration files for Pollora are located in the `config` directory. Feel free to familiarize yourself with the options as each one is well-documented.

Out of the box, Pollora requires minimal configuration. However, it might be worthwhile to review the `config/app.php` file and its accompanying documentation to tailor settings like `timezone` and `locale` to your needs.

<a name="environment-based-configuration"></a>
### Environment Based Configuration

Configuration values in Pollora can vary depending on the environment (local vs. production). These values are usually defined in the `.env` file at your application's root.

For security reasons, never commit your `.env` file to source control. Different developers or servers might need different configurations, and exposing sensitive credentials would pose a significant risk.

> **Note**  
> For a deep dive into the `.env` file and environment configurations, peruse the full [configuration documentation](https://laravel.com/docs/13.x/configuration#environment-configuration).

<a name="databases-and-migrations"></a>
### Databases & Migrations

With your Pollora application ready, you might want to store data. The application's `.env` configuration points Pollora at a MySQL database, and that is a requirement: WordPress is only loaded when Laravel's default connection uses the `mysql` driver, which covers MySQL 5.7+ and MariaDB 10.3+. SQLite and PostgreSQL are not supported. If you're on macOS, installing MySQL or MariaDB is a breeze with [DBngin](https://dbngin.com/).

Set the connection in `.env` with Laravel's names (`DB_CONNECTION=mysql`, `DB_HOST`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`). Names from a Bedrock or `wp-config.php` setup, such as `DB_NAME`, are not read; `php artisan pollora:doctor` flags them.

Finally, run your application's [database migrations](https://laravel.com/docs/13.x/migrations) to establish your database tables:

```shell
php artisan migrate
```

<a name="directory-configuration"></a>
### Directory Configuration

Always serve Pollora from the root of the "web directory" set for your server. Avoid serving Pollora from a subdirectory as it could inadvertently expose sensitive files.

<a name="wordpress-configuration"></a>
## WordPress Configuration

Pollora uses a `wordpress.php` configuration file that contains several important settings:

1. **WordPress Route Conditions**: Mappings between WordPress conditional tags and route URIs
2. **WordPress Authentication Keys**: Keys and salts for WordPress security
3. **Multisite Configuration**: Settings for multisite installations
4. **Database Caching**: Options for database caching
5. **WordPress Constants**: Define WordPress behavior through constants

<a name="publishing-the-configuration-file"></a>
### Publishing the Configuration File

To customize these settings, you can publish the configuration file to your application:

```bash
php artisan vendor:publish --tag=wordpress
```

This command will copy the framework's configuration file to your application's `config/` directory, allowing you to customize it according to your needs.

<a name="customizing-route-conditions"></a>
### Customizing Route Conditions

WordPress route conditions are particularly useful for defining routes that match WordPress conditional functions. You can add your own conditions or replace existing ones:

```php
// config/wordpress.php
return [
    'conditions' => [
        // Add your custom conditions
        'is_custom_post_type' => 'custom-post-type',
        
        // Override existing conditions
        'is_page' => ['page', 'static-page'],
    ],
    // ... other configuration options
];
```

For more information on using route conditions, see the [Routing](https://pollora.dev/routing/wordpress-routes/#wordpress-route-conditions) documentation.

<a name="wordpress-authentication-keys"></a>
### WordPress Authentication Keys

The configuration file also contains WordPress authentication keys and salts, which are essential for your application's security:

```php
// config/wordpress.php
return [
    // ... other options
    
    // WordPress authentication keys and salts
    'auth_key' => env('AUTH_KEY'),
    'secure_auth_key' => env('SECURE_AUTH_KEY'),
    'logged_in_key' => env('LOGGED_IN_KEY'),
    'nonce_key' => env('NONCE_KEY'),
    'auth_salt' => env('AUTH_SALT'),
    'secure_auth_salt' => env('SECURE_AUTH_SALT'),
    'logged_in_salt' => env('LOGGED_IN_SALT'),
    'nonce_salt' => env('NONCE_SALT'),
];
```

These values are typically defined in your `.env` file during installation. If you need to generate new keys, you can use the [WordPress Secret Key Generator](https://api.wordpress.org/secret-key/1.1/salt/).

<a name="multisite-configuration"></a>
### Multisite Configuration

WordPress multisite is configured with WordPress constants. Pollora defines every entry of the `constants` array of `config/wordpress.php` as a constant (keys upper-cased), so publish the file (`php artisan vendor:publish --tag=wordpress`) and add the multisite entries to that array — the published file does not contain them:

```php
// config/wordpress.php
'constants' => [
    // ... the authentication keys and salts already there

    // WordPress multisite configuration
    'wp_allow_multisite' => env('WP_ALLOW_MULTISITE'),
    'multisite' => env('MULTISITE'),
    'subdomain_install' => env('SUBDOMAIN_INSTALL'),
    'domain_current_site' => env('DOMAIN_CURRENT_SITE'),
    'path_current_site' => env('PATH_CURRENT_SITE'),
    'site_id_current_site' => env('SITE_ID_CURRENT_SITE'),
    'blog_id_current_site' => env('BLOG_ID_CURRENT_SITE'),
],
```

Then define these variables in your `.env` file. Keys placed at the top level of `config/wordpress.php`, outside `constants`, are not read.

<a name="database-caching"></a>
### Database Caching

Pollora also supports caching WordPress database queries:

```php
// config/wordpress.php
return [
    // ... other options
    
    // Database caching
    'caching' => env('DB_CACHE'),
];
```

Enable this option by setting `DB_CACHE=true` in your `.env` file to improve your application's performance.

<a name="wordpress-constants"></a>
### WordPress Constants

You can define additional WordPress constants in your configuration file. These constants control various aspects of WordPress behavior:

```php
// config/wordpress.php
return [
    // ... other options
    
    // WordPress constants
    'constants' => [
        'WP_AUTO_UPDATE_CORE' => false,
        'DISALLOW_FILE_MODS' => true,
        'DISALLOW_FILE_EDIT' => true,
        'DISABLE_WP_CRON' => true,
        'WP_POST_REVISIONS' => 5,
        // Add your custom constants here
    ],
];
```

By default, Pollora sets several constants for security and performance:

- `WP_AUTO_UPDATE_CORE`: Disables WordPress core auto-updates
- `DISALLOW_FILE_MODS`: Prevents plugin and theme installations from the admin
- `DISALLOW_FILE_EDIT`: Disables the built-in file editor
- `DISABLE_WP_CRON`: Disables the WordPress cron system (a system cron requests `wp-cron.php`, or [choose another scheduling driver](https://pollora.dev/advanced/scheduling/#drivers))
- `WP_POST_REVISIONS`: Limits the number of post revisions stored

You can override these defaults or add your own constants in your application's configuration file.

<a name="environment-variables"></a>
## Environment Variables

The installation process will create a `.env` file with your configuration. Key variables include:

```env
# Application settings
APP_URL=your-site-url
APP_ENV=local
APP_DEBUG=true

# Database settings
DB_CONNECTION=mysql
DB_HOST=your-database-host
DB_PORT=3306
DB_DATABASE=your-database-name
DB_USERNAME=your-database-user
DB_PASSWORD=your-database-password

# WordPress authentication keys and salts
AUTH_KEY=your-auth-key
SECURE_AUTH_KEY=your-secure-auth-key
LOGGED_IN_KEY=your-logged-in-key
NONCE_KEY=your-nonce-key
AUTH_SALT=your-auth-salt
SECURE_AUTH_SALT=your-secure-auth-salt
LOGGED_IN_SALT=your-logged-in-salt
NONCE_SALT=your-nonce-salt

# WordPress multisite configuration (if needed)
# WP_ALLOW_MULTISITE=true
# MULTISITE=true
# SUBDOMAIN_INSTALL=false
# DOMAIN_CURRENT_SITE=example.com
# PATH_CURRENT_SITE=/
# SITE_ID_CURRENT_SITE=1
# BLOG_ID_CURRENT_SITE=1

# WordPress database caching
DB_CACHE=false
```

During installation, the WordPress authentication keys and salts are automatically generated for security. You can regenerate these keys at any time using the [WordPress Secret Key Generator](https://api.wordpress.org/secret-key/1.1/salt/).

<a name="development-environments"></a>
## Development Environments

Pollora runs on `php artisan serve`, Valet, Herd, MAMP, DDEV, and on Apache or nginx with PHP-FPM. Whatever the tool, three things must agree: the document root is `public/`, the site is opened at the address written in `APP_URL`, and `APP_URL` names a scheme. [Local Development Environments](https://pollora.dev/getting-started/local-environments/) compares the tools, shows the setup of each and lists what to check when a site does not answer.

### DDEV

`pollora new my-project --ddev` configures and starts DDEV, and the installation commands pre-fill their questions from the DDEV container. See [DDEV](https://pollora.dev/getting-started/local-environments/#ddev).

### macOS

Valet, Herd, MAMP, `artisan serve` and Apache were run on macOS 15 for 13.38. The setup of each, the Herd driver and the MAMP PHP version are in [Local Development Environments](https://pollora.dev/getting-started/local-environments/#choose-your-environment).

> [!WARNING]
> Do not point MAMP or Apache at the project folder: the site answers a 404 and `.env` is served as a text file. See [The Three Conditions](https://pollora.dev/getting-started/local-environments/#the-three-conditions).

<a name="troubleshooting"></a>
## Troubleshooting

### Database Connection Issues
If you encounter database connection issues:
1. Verify your database credentials
2. Ensure your database server is running
3. Check if the database exists and is accessible
4. Run `php artisan pollora:env:setup` to reconfigure database settings

### Installation Failed

If the WordPress installation fails:

1. Check the error message
2. Verify database permissions
3. Ensure all required PHP extensions are installed
4. Run `php artisan pollora:install` to retry the installation

<a name="next-steps"></a>
## Next Steps

With your Pollora project configured, here are the recommended next steps:

- [Routing](https://pollora.dev/routing/wordpress-routes/) — Learn WordPress routing with `Route::wp()`
- [Theming](https://pollora.dev/theming/theme-structure/) — Create your first theme with Blade templates
- [Post Types](https://pollora.dev/content/post-types/) — Register custom post types with PHP attributes

For Laravel-specific concepts, see the [Laravel documentation](https://laravel.com/docs/13.x).