Grav

https://learn.getgrav.org/20
Admin
Grav is a fast, simple, and flexible file-based CMS platform that requires zero installation and...
Tokens:580,152
Snippets:5,861
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Plugin Example

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Use this snippet to install a plugin from the GPM repository. Ensure the 'package' and 'type' parameters are correctly set.

```json
{"package": "sitemap", "type": "plugin"}
```

--------------------------------

### Basic .env File Setup

Source: https://learn.getgrav.org/20/basics/grav-configuration

Create a .env file in your Grav install root to set environment variables. Each line defines a single variable.

```env
GRAV_ENVIRONMENT=production
MY_API_KEY=super-secret-value

```

--------------------------------

### Start Grav Built-in Server

Source: https://learn.getgrav.org/20/webservers-hosting/servers/grav-built-in

Navigate to your Grav installation's root directory in the terminal and run this command to start the built-in web server.

```bash
➜ bin/grav server
```

--------------------------------

### Deployer Output Example for Package Upgrade

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

This output demonstrates the process of Deployer executing Grav's package upgrade command, including package discovery, download, installation, and cache clearing.

```text
Executing task packages

GPM Releases Configuration: Stable

Found 8 packages installed of which 1 need updating

01. Email           [v2.5.2 -> v2.5.3]

GPM Releases Configuration: Stable

Preparing to install Email [v2.5.3]
  |- Downloading package...   100%
  |- Checking destination...  ok
  |- Installing package...    ok
  '- Success!

Clearing cache

Cleared:  /home/username/public_html/deployer/grav/cache/twig/*
Cleared:  /home/username/public_html/deployer/grav/cache/doctrine/*
Cleared:  /home/username/public_html/deployer/grav/cache/compiled/*

Touched: /home/username/public_html/deployer/grav/user/config/system.yaml

```

--------------------------------

### Grav Built-in Server Output Example

Source: https://learn.getgrav.org/20/webservers-hosting/servers/grav-built-in

This output shows the server starting, logging information, and confirming it's listening. The URL provided is used to access your site in a browser.

```bash
Grav Web Server
===============

Tailing Web Server log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)

[OK] Web server listening
The Web server is using PHP FPM 8.0.8
https://127.0.0.1:8000


[Web Server ] Jul 30 14:54:53 |DEBUG  | PHP    Reloading PHP versions
[Web Server ] Jul 30 14:54:54 |DEBUG  | PHP    Using PHP version 8.0.8 (from default version in $PATH)
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[Web Server ] Jul 30 14:54:54 |INFO   | PHP    listening path="/usr/local/Cellar/php/8.0.8_2/sbin/php-fpm" php="8.0.8" port=65140
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections

```

--------------------------------

### Clone Heroku PHP Starter Project

Source: https://learn.getgrav.org/20/webservers-hosting/paas/heroku

Clone the official Heroku PHP getting started example to your local machine. This provides a basic structure for PHP applications on Heroku.

```bash
git clone https://github.com/heroku/php-getting-started.git your-folder

```

--------------------------------

### Install Shortcode Core Plugin

Source: https://learn.getgrav.org/20/grav-premium/downloads-pro

Before using Downloads Pro shortcodes, ensure the 'shortcode-core' plugin is installed. Install it via the Admin panel or using the Grav CLI.

```bash
bin/gpm install shortcode-core
```

--------------------------------

### Run Grav with Built-in PHP Webserver

Source: https://learn.getgrav.org/20/basics/installation

Use this command to start Grav's development server. It requires PHP to be installed and provides real-time updates in your terminal.

```bash
➜ bin/grav server

Grav Web Server
===============

Tailing Web Server log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)
Tailing PHP-FPM log file (/Users/joeblow/.symfony/log/96e710135f52930318e745e901e4010d0907cec3/53fb8ec204547646acb3461995e4da5a54cc7575.log)

[OK] Web server listening
The Web server is using PHP FPM 8.0.8
https://127.0.0.1:8000

[Web Server ] Jul 30 14:54:53 |DEBUG  | PHP    Reloading PHP versions
[Web Server ] Jul 30 14:54:54 |DEBUG  | PHP    Using PHP version 8.0.8 (from default version in $PATH)
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    fpm is running, pid 64992
[PHP-FPM    ] Jul  6 14:40:17 |NOTICE | FPM    ready to handle connections
[Web Server ] Jul 30 14:54:54 |INFO   | PHP    listening path="/usr/local/Cellar/php/8.0.8_2/sbin/php-fpm" php="8.0.8" port=65140
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    fpm is running, pid 73709
[PHP-FPM    ] Jul 30 14:54:54 |NOTICE | FPM    ready to handle connections

```

--------------------------------

### Get Page Example

Source: https://learn.getgrav.org/20/api/endpoints/pages

Retrieves a single page with its full content, metadata, and media. Supports conditional fetches using ETags.

```json
{"data": {"route": "/blog/my-post", "slug": "my-post", "title": "My Post", "template": "post", "content": "# Hello World", "header": {"published": true}, "media": [], "has_default_file": true, "explicit_language_files": ["fr"]}}
```

--------------------------------

### Install Grav Plugin and Theme Dependencies

Source: https://learn.getgrav.org/20/basics/installation

Use the Grav CLI to install plugin and theme dependencies. This command should be run from the Grav installation directory.

```bash
cd ~/webroot/grav
bin/grav install
```

--------------------------------

### Install Composer Dependencies

Source: https://learn.getgrav.org/20/basics/installation

After cloning the repository, navigate to the Grav directory and install vendor dependencies using Composer. The --no-dev and -o flags optimize the installation for production.

```bash
cd ~/webroot/grav
composer install --no-dev -o
```

--------------------------------

### Perform Composer Install

Source: https://learn.getgrav.org/20/advanced/grav-cli

Executes `composer install` via the Grav CLI. This is useful for installing dependencies when needed.

```bash
bin/grav composer --install

```

--------------------------------

### Direct Install Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Confirms successful installation of a package via direct install. This response is returned after a successful direct installation.

```json
{"data": {"message": "Package installed successfully via direct install."}}
```

--------------------------------

### Example README Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response when successfully retrieving the README content for a plugin or theme.

```json
{"data": {"content": "# My Plugin\n\nThis plugin does..."}}
```

--------------------------------

### Start Apache Service

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Start the Apache web server service using the service command.

```bash
sudo service apache2 start

```

--------------------------------

### Check Setup Status

Source: https://learn.getgrav.org/20/api/endpoints/authentication

Checks if the Grav instance requires initial setup. This is typically polled by the admin interface on load to determine whether to display the setup wizard or the login screen.

```APIDOC
## Setup Status
GET `/auth/setup`

### Description
Check whether the instance requires first-run setup. Returns `setup_required: true` only when `user/accounts/` is empty. Admin2 polls this on load to decide between showing the setup wizard or the login screen. Public (no auth required).

### Method
GET

### Endpoint
`/auth/setup`

### Response
#### Success Response (200)
- **setup_required** (boolean) - Indicates if setup is required.

### Response Example
```json
{
  "data": {
    "setup_required": true
  }
}
```
```

--------------------------------

### Example Response for Listing Blueprints

Source: https://learn.getgrav.org/20/api/endpoints/flex-objects

This is an example of the JSON response when listing available Flex directory blueprints.

```json
{"data": [{"url": "blueprints://flex-objects/contacts.yaml", "legacy_url": null, "type": "contacts", "title": "Contacts", "description": "Address book"}]}
```

--------------------------------

### Install Grav Dependencies

Source: https://learn.getgrav.org/20/cli-console/command-line-intro

This command ensures all necessary dependencies for your current Grav installation are downloaded and set up.

```bash
bin/grav install
```

--------------------------------

### Verify PHP Installation and Version

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Check if PHP is installed correctly and display its current version.

```bash
php -v

```

--------------------------------

### Install Downloads Pro Plugin

Source: https://learn.getgrav.org/20/grav-premium/downloads-pro

Installs the Downloads Pro plugin using the Grav Package Manager (GPM).

```bash
$ bin/gpm install downloads-pro

```

--------------------------------

### Install Apache on WSL

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Use this command to install the Apache web server package in your WSL distribution.

```bash
sudo apt install apache2

```

--------------------------------

### Install the API Plugin

Source: https://learn.getgrav.org/20/api/getting-started

Install the Grav API Plugin using the Grav Package Manager (GPM) or manually.

```APIDOC
## Install the API Plugin

Install via GPM:
```bash
bin/grav install api
```

Or manually: download the plugin into `user/plugins/api` and run `composer install`.
```

--------------------------------

### Install Gulp Globally

Source: https://learn.getgrav.org/20/themes/customization

Installs Gulp globally to manage build processes for theme compilation.

```bash
npm install -g gulp
```

--------------------------------

### Install Grav Package

Source: https://learn.getgrav.org/20/cli-console/command-line-intro

Installs a theme or plugin from the Grav repository directly into your current Grav instance with a single command.

```bash
bin/gpm install
```

--------------------------------

### Get Scheduler Status

Source: https://learn.getgrav.org/20/api/endpoints/scheduler

Reports the scheduler's crontab installation state, expected cron commands, the effective user, and health diagnostics. This is useful for verifying cron setup and identifying potential issues.

```json
{"data": {"crontab_status": "installed", "cron_command": "* * * * * cd /path/to/grav && /usr/bin/php bin/grav scheduler", "scheduler_command": "bin/grav scheduler", "whoami": "www-data", "health": {}, "triggers": [], "webhook_installed": false, "webhook_enabled": false}}
```

--------------------------------

### setupConsole

Source: https://learn.getgrav.org/20/advanced/php-reference

Sets up the console formatter with style definitions.

```APIDOC
## setupConsole

### Description
Set colors style definition for the formatter.

### Signature
`public function setupConsole(\Symfony\Component\Console\Input\InputInterface $input, \Symfony\Component\Console\Output\OutputInterface $output): void`
```

--------------------------------

### Download and Install Grav

Source: https://learn.getgrav.org/20/webservers-hosting/vps/rosehosting

Switch to the 'grav' user, navigate to the web directory, download the latest Grav core, unzip it, and set up the 'html' directory.

```bash
su - grav
cd ~/
cd www
wget -O grav.zip https://getgrav.org/download/core/grav/latest
unzip grav.zip
rm -rf html
mv grav html
```

--------------------------------

### Get Downloads Object in Twig

Source: https://learn.getgrav.org/20/grav-premium/downloads-pro

Examples of how to get the downloads object for a specific page or route within a Twig template.

```twig
{% set downloads = grav.downloads.getPage() %}
{% set downloads = grav.downloads.getPage(page) %}
{% set downloads = grav.downloads.getRoute('/downloads') %}
```

--------------------------------

### Install Migrate to Grav Plugin

Source: https://learn.getgrav.org/20/migration/assisted-migration

Use this command to install the migration plugin via the Grav Package Manager (GPM).

```bash
bin/gpm install migrate-grav
```

--------------------------------

### Example Changelog Response

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Example JSON response when successfully retrieving the CHANGELOG.md content for a plugin or theme.

```json
{"data": {"content": "# v1.2.0\n## 01/15/2025\n\n* Added feature X..."}}
```

--------------------------------

### Install YetiSearch Pro Plugin

Source: https://learn.getgrav.org/20/grav-premium/yetisearch-pro

Installs the YetiSearch Pro plugin using the Grav Package Manager (GPM).

```bash
$ bin/gpm install yetisearch-pro

```

--------------------------------

### Get Help for a Specific GPM Command

Source: https://learn.getgrav.org/20/advanced/grav-gpm

Use this command to get detailed help for any specific GPM command, such as 'install'.

```bash
bin/gpm help install

```

--------------------------------

### Grav\Common\Config\Setup Class

Source: https://learn.getgrav.org/20/advanced/php-reference

Provides methods for setting up and initializing Grav's configuration, including managing resource locators.

```APIDOC
## Class: \Grav\Common\Config\Setup

### Description
Provides methods for setting up and initializing Grav's configuration.

### Methods
#### `__construct(Container|array $container)`
Initializes the Setup class with a container or configuration array.

#### `getStreams(): array`
Retrieves the available streams and their types from the configuration.

#### `init(): self`
Initializes the configuration setup.

#### `initializeLocator(UniformResourceLocator $locator): void`
Initializes the resource locator using the configuration settings.
```

--------------------------------

### Initialize Migration from CLI

Source: https://learn.getgrav.org/20/migration/assisted-migration

Run this command to start the migration staging process from the command line. It will provide a URL to continue in the wizard.

```bash
bin/plugin migrate-grav init
```

--------------------------------

### Get Repository Package Details

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Fetch detailed information for a specific plugin or theme from the GPM repository using its slug. Includes an `installed` flag to indicate its installation status.

```json
{"data": {"slug": "simplesearch", "name": "SimpleSearch", "version": "2.4.0", "description": "...", "author": {"name": "Trilby Media"}, "installed": false}}
```

--------------------------------

### Create Initial User

Source: https://learn.getgrav.org/20/api/endpoints/authentication

Performs the one-time first-run setup by creating the initial super-admin account. This endpoint is active only when the `user/accounts/` directory is empty.

```APIDOC
## Create Initial User
POST `/auth/setup`

### Description
One-time first-run setup — creates the initial super-admin account on a fresh Grav 2.0 install. Active only while `user/accounts/` is empty; 409 thereafter. Grants `api.super` (not `admin.super`) by default so the account has API authority without implying classic-admin authority. Fires `onApiUserCreated` and `onApiSetupComplete`, then issues a login token pair so the client can skip straight to the dashboard. Public (no auth required), rate-limited per IP.

### Method
POST

### Endpoint
`/auth/setup`

### Parameters
#### Request Body
- **username** (string) - Required - Username (3–64 chars; letters, numbers, hyphens, underscores).
- **password** (string) - Required - Password (minimum 8 characters).
- **email** (string) - Required - A valid email address.
- **fullname** (string) - Optional - Display name for the account.
- **title** (string) - Optional - User title (defaults to "Administrator").

### Request Example
```json
{
  "username": "admin",
  "password": "a-good-secret",
  "email": "admin@example.com",
  "fullname": "Site Admin"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for authentication.
- **refresh_token** (string) - The refresh token for obtaining new access tokens.
- **token_type** (string) - The type of token, typically "Bearer".
- **expires_in** (integer) - The time in seconds until the access token expires.

### Response Example
```json
{
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}
```

### Response Codes
- **200** Account created; token pair issued.
- **400** Validation failed (username format, invalid email, password too short, missing fields).
- **409** Setup has already been completed.
- **429** Too many setup attempts from this IP.
```

--------------------------------

### UserObject Methods

Source: https://learn.getgrav.org/20/advanced/php-reference

Examples of how to use the def(), get(), set(), and undef() methods on a UserObject.

```APIDOC
## UserObject Methods

### Description
Examples of how to use the def(), get(), set(), and undef() methods on a UserObject.

### Examples

#### UserObject::def()
```php
$data->def('this.is.my.nested.variable', 'default');
```

#### UserObject::get()
```php
$value = $this->get('this.is.my.nested.variable');
```

#### UserObject::set()
```php
$data->set('this.is.my.nested.variable', $value);
```

#### UserObject::undef()
```php
$data->undef('this.is.my.nested.variable');
```
```

--------------------------------

### Create Grav Web Directory and Test File

Source: https://learn.getgrav.org/20/webservers-hosting/vps/digitalocean

Switch to the 'grav' user, create the web directory structure, and place a test 'info.php' file to verify the PHP setup.

```bash
su - grav
mkdir -p ~/www/html
echo '<?php phpinfo();' > ~/www/html/info.php
exit
```

--------------------------------

### Get Plugin

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieves detailed information for a specific installed plugin using its slug.

```APIDOC
## GET /gpm/plugins/{slug}

### Description
Get details for a single installed plugin, including `enabled`, `updatable`, `installed_version`, `available_version`, and the `is_symlink` flag.

### Method
GET

### Endpoint
/gpm/plugins/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The plugin slug.

### Response
#### Success Response (200)
- **data** (object) - An object containing the plugin's details.
  - **slug** (string) - The plugin's unique identifier.
  - **name** (string) - The display name of the plugin.
  - **enabled** (boolean) - Indicates if the plugin is currently enabled.
  - **is_symlink** (boolean) - Indicates if the plugin was installed via a symlink.
  - **installed_version** (string) - The currently installed version of the plugin.
  - **available_version** (string) - The latest available version of the plugin.
  - **updatable** (boolean) - Indicates if an update is available for the plugin.

#### Response Example
```json
{"data": {"slug": "simplesearch", "name": "SimpleSearch", "enabled": true, "is_symlink": false, "installed_version": "2.3.0", "available_version": "2.4.0", "updatable": true}}
```

### Response Codes
200 Plugin returned.
401 Unauthorized.
403 Missing `api.gpm.read` permission.
404 Plugin not found.
```

--------------------------------

### Return to Grav Root Directory

Source: https://learn.getgrav.org/20/plugins/plugin-flex

Navigates back to the root directory of the Grav installation after completing plugin setup.

```bash
cd -

```

--------------------------------

### Start PHP Built-in Web Server

Source: https://learn.getgrav.org/20/webservers-hosting/php-built-in-web-server

Navigate to your Grav root directory and run this command to start the server on localhost:8080, using system/router.php for routing. Press Ctrl-C to stop.

```bash
php -S localhost:8080 system/router.php
```

--------------------------------

### Remove Package Example

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Use this snippet to remove an installed package. Provide the 'package' slug of the item to be removed.

```json
{"package": "sitemap"}
```

--------------------------------

### Get Theme

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieve detailed information for a specific installed theme, including its slug, name, version, and screenshot URL.

```APIDOC
## Get Theme
GET `/gpm/themes/{slug}`

### Description
Get details for a specific installed theme, including screenshot URL, `updatable` status, and the `is_symlink` flag.

### Method
GET

### Endpoint
`/gpm/themes/{slug}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The theme slug.

### Response
#### Success Response (200)
- **data** (object) - Theme details:
  - **slug** (string) - The theme's unique identifier.
  - **name** (string) - The theme's display name.
  - **version** (string) - The currently installed version of the theme.
  - **updatable** (boolean) - Indicates if the theme can be updated.
  - **is_symlink** (boolean) - Indicates if the theme is a symbolic link.
  - **screenshot** (string) - URL to the theme's screenshot.

### Response Codes
- **200** Theme returned.
- **401** Unauthorized.
- **403** Missing `api.gpm.read` permission.
- **404** Theme not installed.
```

--------------------------------

### PHP CLI Command Example

Source: https://learn.getgrav.org/20/cli-console/grav-cli-plugin

This example demonstrates how to create a basic CLI command for a Grav plugin. It includes argument and option handling, and custom output formatting. Save this as 'HelloCommand.php' in your plugin's 'cli/' directory.

```php
<?php
namespace Grav\Plugin\Console;

use Grav\Console\ConsoleCommand;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;

/**
 * Class HelloCommand
 *
 * @package Grav\Plugin\Console
 */
class HelloCommand extends ConsoleCommand
{
    /**
     * @var array
     */
    protected $options = [];

    /**
     * Greets a person with or without yelling
     */
    protected function configure()
    {
        $this
            ->setName("hello")
            ->setDescription("Greets a person.")
            ->addArgument(
                'name',
                InputArgument::REQUIRED,
                'The name of the person that should be greeted'
            )
            ->addOption(
                'yell',
                'y',
                InputOption::VALUE_NONE,
                'Wheter the greetings should be yelled or quieter'
            )
            ->setHelp('The <info>hello</info> greets someone.')
        ;
    }

    /**
     * @return int|null|void
     */
    protected function serve()
    {
        // Collects the arguments and options as defined
        $this->options = [
            'name' => $this->input->getArgument('name'),
            'yell' => $this->input->getOption('yell')
        ];

        // Prepare the strings we want to output and wraps the name into a cyan color
        // More colors available at:
        // https://github.com/getgrav/grav/blob/develop/system/src/Grav/Console/ConsoleTrait.php
        $greetings = 'Greetings, dear <cyan>' . $this->options['name'] . '</cyan>!';

        // If the optional `--yell` or `-y` parameter are passed in, let's convert everything to uppercase
        if ($this->options['yell']) {
            $greetings = strtoupper($greetings);
        }

        // finally we write to the output the greetings
        $this->output->writeln($greetings);
    }
}

```

--------------------------------

### Install Dokku

Source: https://learn.getgrav.org/20/webservers-hosting/paas/dokku

Run these commands on a fresh VM to install the latest stable release of Dokku. Ensure the user has sudo access.

```bash
wget https://raw.githubusercontent.com/dokku/dokku/v0.17.9/bootstrap.sh
sudo DOKKU_TAG=v0.17.9 bash bootstrap.sh

```

--------------------------------

### Get Plugin/Theme Changelog

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieves the CHANGELOG.md content for an installed plugin or theme using its slug. This endpoint is also available for themes.

```APIDOC
## Get Changelog
GET `/gpm/plugins/{slug}/changelog`

Get the CHANGELOG.md content for an installed plugin or theme. Also available at `/gpm/themes/{slug}/changelog`.

### Parameters
Name | Type | Description  
---|---|---  
slug required | string |  The package slug  

### Response
#### Success Response (200)
```json
{
  "data": {
    "content": "# v1.2.0\n## 01/15/2025\n\n* Added feature X..."
  }
}
```

#### Response Codes
200 Success
401 Unauthorized
404 Package or changelog not found
```

--------------------------------

### Grav setup.php Configuration Structure

Source: https://learn.getgrav.org/20/advanced/multisite-setup

Defines the structure for the `setup.php` file, which returns an associative array for environment and stream configurations. This script runs on every page request, so avoid memory-intensive operations.

```php
return [
  'environment' => '<name>',            // A name for the environment
  'streams' => [
    'schemes' => [
      '<stream_name>' => [
        'type' => 'ReadOnlyStream',     // Stream object e.g. 'ReadOnlyStream' or 'Stream'
        'prefixes' => [
          '<prefix>' => [
            '<path1>',
            '<path2>',
            '<etc>'
          ]
        ],
        'paths' => [
          '<paths1>',
          '<paths2>',
          '<etc>'
        ]
      ]
    ]
  ]
]
```

--------------------------------

### Get Plugin/Theme README

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieves the README.md content for an installed plugin or theme using its slug. This endpoint is also available for themes.

```APIDOC
## Get README
GET `/gpm/plugins/{slug}/readme`

Get the README.md content for an installed plugin or theme. Also available at `/gpm/themes/{slug}/readme`.

### Parameters
Name | Type | Description  
---|---|---  
slug required | string |  The package slug  

### Response
#### Success Response (200)
```json
{
  "data": {
    "content": "# My Plugin\n\nThis plugin does..."
  }
}
```

#### Response Codes
200 Success
401 Unauthorized
404 Package or README not found
```

--------------------------------

### Configure New Plugin Details

Source: https://learn.getgrav.org/20/plugins/plugin-tutorial

Provide the necessary information when prompted by the `new-plugin` command to create the plugin files. This includes name, description, developer details, and confirms successful creation.

```bash
bin/plugin devtools new-plugin
Enter Plugin Name: Randomizer
Enter Plugin Description: Sends the user to a random page
Enter Developer Name: Acme Corp
Enter Developer Email: contact@acme.co

SUCCESS plugin Randomizer -> Created Successfully

Path: /www/user/plugins/randomizer

Make sure to run `composer update` to initialize the autoloader

```

--------------------------------

### Get Specific Theme Details

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Fetches detailed information for a single installed theme using its slug. Requires 'api.gpm.read' permission.

```json
{"data": {"slug": "quark", "name": "Quark", "version": "2.0.0", "updatable": false, "is_symlink": false, "screenshot": "/api/v1/thumbnails/quark-screen.jpg"}}
```

--------------------------------

### Get Help for a Specific Grav Command

Source: https://learn.getgrav.org/20/advanced/grav-cli

Use this command to retrieve detailed help information for any specific Grav CLI command, such as 'install'.

```bash
bin/grav help install
```

--------------------------------

### Download and Install Grav CMS

Source: https://learn.getgrav.org/20/webservers-hosting/vps/digitalocean

Switches to the 'grav' user, downloads the latest Grav CMS zip file, unzips it, and sets up the 'html' directory.

```bash
su - grav
cd ~/www
wget -O grav.zip https://getgrav.org/download/core/grav/latest
unzip grav.zip
rm -rf html
mv grav html
```

--------------------------------

### PHP Setup Script for Environment Variable Configuration

Source: https://learn.getgrav.org/20/advanced/multisite-setup

Configure initial settings and credentials using environment variables within `user/setup.php`. This is useful for storing secrets outside of the main configuration files.

```php
<?php

// Use following environment variables in your server configuration:
//
// DYNAMODB_SESSION_KEY: DynamoDb server key for the PHP session storage
// DYNAMODB_SESSION_SECRET: DynamoDb server secret
// DYNAMODB_SESSION_REGION: DynamoDb server region
// GOOGLE_MAPS_KEY: Google Maps secret key

return [
    'plugins' => [
        // This plugin does not exist
        'dynamodb_session' => [
            'credentials' => [
                'key' => getenv('DYNAMODB_SESSION_KEY') ?: null,
                'secret' => getenv('DYNAMODB_SESSION_SECRET') ?: null
            ],
            'region' => getenv('DYNAMODB_SESSION_REGION') ?: null
        ],
        // This plugin does not exist
        'google_maps' => [
            'key' => getenv('GOOGLE_MAPS_KEY') ?: null
        ]
    ]
];

```

--------------------------------

### Backup Grav 1.x Site

Source: https://learn.getgrav.org/20/migration/manual-migration

Create a full backup of your live Grav 1.x installation before starting the migration process. This ensures you have a restore point if needed.

```bash
cd /path/to/grav-site
bin/grav backup

```

--------------------------------

### Create Web Directory and Test File

Source: https://learn.getgrav.org/20/webservers-hosting/vps/linode

Create the web directory for Grav and a test PHP file to verify the PHP setup. This involves switching to the 'grav' user.

```bash
su - grav
mkdir -p ~/www/html

```

```php
echo '<?php phpinfo();' > ~/www/html/info.php
exit

```

--------------------------------

### Start ddev Project

Source: https://learn.getgrav.org/20/webservers-hosting/local-development-with-ddev

Run 'ddev start' from the project's root directory to build and launch the Docker containers for your local development environment.

```bash
ddev start
```

--------------------------------

### Create New Grav Project with CLI

Source: https://learn.getgrav.org/20/advanced/grav-cli

Use the Grav CLI to quickly set up a new Grav instance for your project. Specify the destination path for the new project.

```bash
bin/grav new-project ~/webroot/portfolio

```

--------------------------------

### Example of Complex Regex Route Matching

Source: https://learn.getgrav.org/20/content/routing

Illustrates how the complex regex route alias matches and rewrites URLs. Note that the route must start with 'complex/category' or 'complex/section'.

```text
/complex/category/article-1      -> /blog/category/folder/article-1
/complex/section/article-2.html  -> /blog/section/folder/article-2.html
```

--------------------------------

### Download and Install Grav CMS

Source: https://learn.getgrav.org/20/webservers-hosting/vps/vultr

This sequence of commands switches to the 'grav' user, navigates to the web directory, downloads the latest Grav core, unzips it, and sets up the correct directory structure for the web server.

```bash
su - grav
cd ~/www
wget -O grav.zip https://getgrav.org/download/core/grav/latest
unzip grav.zip
rm -rf html
mv grav html

```

--------------------------------

### Get Specific Plugin Details

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Fetches detailed information for a single installed plugin using its slug. Includes version details, enablement status, and symlink information.

```json
{"data": {"slug": "simplesearch", "name": "SimpleSearch", "enabled": true, "is_symlink": false, "installed_version": "2.3.0", "available_version": "2.4.0", "updatable": true}}
```

--------------------------------

### Install Grav in WSL

Source: https://learn.getgrav.org/20/webservers-hosting/windows-subsystem-for-linux

Download the latest Grav package, install the unzip utility if needed, extract Grav to the Apache webroot, and rename the folder to 'mysite'.

```bash
wget -O grav.zip https://getgrav.org/download/core/grav/latest

```

```bash
sudo apt install unzip  # unzip is not installed by default on WSL/Ubuntu

```

```bash
unzip grav.zip -d /var/www/webroot

```

```bash
mv /var/www/webroot/grav /var/www/webroot/mysite

```

--------------------------------

### Upgrade Grav Core

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Self-upgrade the Grav core. Refuses to run when Grav is installed via symlink (typical dev/monorepo setups). Fires `onApiBeforeGravUpgrade` and `onApiGravUpgraded` around the upgrade.

```APIDOC
## POST /gpm/upgrade

### Description
Self-upgrade the Grav core. Refuses to run when Grav is installed via symlink (typical dev/monorepo setups). Fires `onApiBeforeGravUpgrade` and `onApiGravUpgraded` around the upgrade.

### Method
POST

### Endpoint
/gpm/upgrade

### Response
#### Success Response (200)
- **data** (object) - Contains upgrade details.
  - **message** (string) - Confirmation message.
  - **previous_version** (string) - The version before upgrade.
  - **new_version** (string) - The version after upgrade.

### Response Example
```json
{
  "data": {
    "message": "Grav upgraded successfully.",
    "previous_version": "2.0.0-beta.1",
    "new_version": "2.0.0-beta.2"
  }
}
```

### Response Codes
200 Core upgraded.
400 Grav is already at the latest version, or installed via symlink.
401 Unauthorized.
403 Missing `api.gpm.write` permission.
500 Upgrade failed mid-flight.
```

--------------------------------

### Set umask for New Files

Source: https://learn.getgrav.org/20/troubleshooting/permissions

Create or modify the setup.php file to set the umask for newly created files and directories. This example sets it to '0002'.

```php
<?php
umask(0002);

```

--------------------------------

### Create a new Dokku app

Source: https://learn.getgrav.org/20/webservers-hosting/paas/dokku

After Dokku installation, create a new application for your Grav website on the VM.

```bash
dokku apps:create my-grav-site

```

--------------------------------

### Compare Translations Response Body

Source: https://learn.getgrav.org/20/api/endpoints/pages

An example response body for the GET /pages/{route}/compare endpoint, showing a comparison of source and target language versions of a page, including existence status.

```json
{"data": {"route": "/blog/my-post", "source": {"lang": "en", "exists": true, "title": "My Post", "content": "# Hello", "header": {"title": "My Post"}, "modified": "2026-04-17T10:00:00+00:00"}, "target": {"lang": "fr", "exists": false, "title": "My Post", "content": "# Hello", "header": {"title": "My Post"}, "modified": null}}
```

--------------------------------

### Configure Accounts Settings

Source: https://learn.getgrav.org/20/basics/grav-configuration

Set up account types and storage methods. Use 'regular' or 'flex' for type, and 'file' or 'folder' for storage.

```yaml
accounts:
  type: regular
  storage: file

```

--------------------------------

### Authentication Endpoints

Source: https://learn.getgrav.org/20/api/endpoints

Endpoints for JWT login/logout, password reset, two-factor verification, first-run setup, and retrieving the current session. Token/refresh/revoke/2FA/setup/forgot/reset endpoints are public (no auth required). GET /me requires an authenticated session.

```APIDOC
## Authentication Endpoints

### Description
Endpoints for JWT login/logout, password reset, two-factor verification, first-run setup, and retrieving the current session. Token/refresh/revoke/2FA/setup/forgot/reset endpoints are public (no auth required). GET /me requires an authenticated session.

### Public Endpoints (No Auth Required)
- POST /auth/token
- POST /auth/2fa/verify
- POST /auth/refresh
- POST /auth/revoke
- POST /auth/forgot-password
- POST /auth/reset-password
- GET /auth/setup
- POST /auth/setup
- GET /ping
- GET /translations/{lang}

### Authenticated Endpoints
- GET /me (Requires authentication)
```

--------------------------------

### Example Caddyfile for Grav

Source: https://learn.getgrav.org/20/webservers-hosting/servers/caddy

A comprehensive Caddyfile configuration for a Grav site, including domain setup, compression, root directory, PHP-FPM integration, and extensive security rules to block direct access to sensitive files and directories.

```plaintext
example.com
encode gzip
root * /var/www/grav
file_server

php_fastcgi 127.0.0.1:9000

# Begin - Security
# deny all direct access for these folders
rewrite /(\.git|cache|bin|logs|backups|tests)/.* /403

# deny all direct access to these sensitive user folders, whatever the file type
rewrite /user/(accounts|config|env)/.* /403

# block user/data too, but allow public media uploads (e.g. Flex Object images)
# to be served directly. SVG is intentionally excluded as a stored-XSS vector.
# (Go's RE2 has no lookbehind, so this uses a negated matcher.)
@user_data_nonmedia {
    path_regexp /user/data/.*
    not path_regexp (?i)\.(jpe?g|png|gif|webp|avif|bmp|ico|mp4|webm|ogg|ogv|mov|mp3|wav|m4a|flac|pdf)$
}
rewrite @user_data_nonmedia /403

# deny running scripts inside core system folders
rewrite /(system|vendor)/.*\.(txt|xml|md|html|htm|shtml|shtm|yaml|yml|php|php2|php3|php4|php5|phar|phtml|pl|py|cgi|twig|sh|bat)$ /403

# deny running scripts inside user folder
rewrite /user/.*\.(txt|md|yaml|yml|php|php2|php3|php4|php5|phar|phtml|pl|py|cgi|twig|sh|bat)$ /403

# deny access to specific files in the root folder
rewrite /(LICENSE\.txt|composer\.lock|composer\.json|nginx\.conf|web\.config|htaccess\.txt|\.htaccess) /403

# deny access to .env environment files
@dotenv path_regexp \.env(\..+)?$
respond @dotenv 403

respond /403 403
## End - Security

# global rewrite should come last.
try_files {path} {path}/ /index.php?_url={uri}&{query}

```

--------------------------------

### Get Sidebar Items

Source: https://learn.getgrav.org/20/api/endpoints/sidebar

Collects sidebar navigation items registered by plugins. Fires the onApiSidebarItems event and returns all items contributed by installed plugins. Each item defines an id, label, icon, route, and optional badge.

```APIDOC
## GET /sidebar/items

### Description
Collects sidebar navigation items registered by plugins. Fires the onApiSidebarItems event and returns all items contributed by installed plugins. Each item defines an id, label, icon, route, and optional badge.

### Method
GET

### Endpoint
/sidebar/items

### Response
#### Success Response (200)
- **data** (array) - An array of sidebar item objects.
  - **id** (string) - The unique identifier for the sidebar item.
  - **plugin** (string) - The name of the plugin that registered the item.
  - **label** (string) - The display label for the sidebar item.
  - **icon** (string) - The CSS class for the icon associated with the item.
  - **route** (string) - The route to navigate to when the item is selected.
  - **priority** (integer) - The priority of the item in the sidebar.

#### Response Example
```json
{
  "data": [
    {
      "id": "license-manager",
      "plugin": "license-manager",
      "label": "Licenses",
      "icon": "fa-key",
      "route": "/plugin/license-manager",
      "priority": 10
    }
  ]
}
```

### Response Codes
- **200** Success
- **401** Unauthorized
```

--------------------------------

### Install Composer Globally

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

Installs Composer globally by setting the COMPOSERDIR environment variable and downloading the installer. Use this if you prefer a global installation.

```bash
export COMPOSERDIR=~/bin;mkdir bin
curl -sS https://getcomposer.org/installer | php -- --install-dir=$COMPOSERDIR --filename=composer

```

--------------------------------

### Run Deployer Upgrade Tasks

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

Execute these commands sequentially from the 'public_html/deployer/' directory to perform a full site upgrade. This includes backing up the site, upgrading Grav core, and updating all plugins and themes.

```bash
php vendor/bin/dep backup
```

```bash
php vendor/bin/dep core
```

```bash
php vendor/bin/dep packages
```

--------------------------------

### Manual Installation Directory

Source: https://learn.getgrav.org/20/grav-premium/revisions-pro

This is the expected directory structure for the Revisions Pro plugin after manual installation and running composer install.

```text
/your/site/grav/user/plugins/revisions-pro

```

--------------------------------

### Direct Install

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Install a plugin or theme from a URL or uploaded zip — bypasses the GPM repository lookup. Useful for private/unpublished packages, pre-release builds, or local development.

```APIDOC
## POST /gpm/direct-install

### Description
Install a plugin or theme from a URL or uploaded zip — bypasses the GPM repository lookup. Accepts either a JSON body with `url`, or a multipart upload with a `file` field. Useful for private/unpublished packages, pre-release builds, or local development.

### Method
POST

### Endpoint
/gpm/direct-install

### Parameters
#### Request Body
- **url** (string) - Optional - URL of the package zip (mutually exclusive with `file`).
- **file** (file) - Optional - Uploaded zip file (multipart; mutually exclusive with `url`).

### Request Example
```json
{
  "url": "https://example.com/builds/my-plugin-1.0.0.zip"
}
```

### Response
#### Success Response (201)
- **data** (object) - Contains installation details.
  - **message** (string) - Confirmation message.

### Response Example
```json
{
  "data": {
    "message": "Package installed successfully via direct install."
  }
}
```

### Response Codes
201 Package installed.
400 Neither `url` nor a valid `file` was provided.
401 Unauthorized.
403 Missing `api.gpm.write` permission.
500 Installation failed.
```

--------------------------------

### Install Composer Locally

Source: https://learn.getgrav.org/20/cli-console/scripted-upgrades

Installs Composer locally within the current directory. This is useful for projects where a global installation is not desired or possible.

```bash
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

```

--------------------------------

### List Installed Plugins

Source: https://learn.getgrav.org/20/api/endpoints/gpm

Retrieves a list of all installed plugins, including their enablement status, update availability, and whether they are installed via a symlink.

```json
{"data": [{"slug": "admin2", "name": "Admin2", "version": "3.0.0-beta.1", "enabled": true, "is_symlink": false, "updatable": false}]}
```

--------------------------------

### Install Shortcode Core Plugin

Source: https://learn.getgrav.org/20/content/creating-a-shortcode

Install the Shortcode Core plugin using the Grav Package Manager (GPM). This is a prerequisite for using shortcodes.

```bash
bin/gpm install shortcode-core

```

--------------------------------

### Install Helios Theme via GPM

Source: https://learn.getgrav.org/20/grav-premium/helios

Install the Helios theme using the Grav Package Manager (GPM). Confirm the installation of dependencies when prompted.

```bash
$ bin/gpm install helios

```
Tokens:
Raw