Creating object type for Drupal configuration

This page provides an example of how to create a configuration entity type with administrative management pages in Drupal 8. For an introduction to the concepts of simple configuration and configuration entities, see https://drupal.org/node/2120523.

After enabling the example module that contains the code below, the configuration form should be available at “admin/config/system/example”, as shown in the screenshot:

Module Setup and Admin Menu Entry

example/example.info.yml

name: Example
description: 'Manages example configuration.'
package: Example
type: module
core: 8.x

Routing

(See helper classes added for working with entity paths for simplification tips.)

example/example.routing.yml

This routing.yml file defines routes for management pages: list, add, edit, delete.

entity.example.collection:
  path: '/admin/config/system/example'
  defaults:
    _entity_list: 'example'
    _title: 'Example configuration'
  requirements:
    _permission: 'administer site configuration'

entity.example.add_form:
  path: '/admin/config/system/example/add'
  defaults:
    _entity_form: 'example.add'
    _title: 'Add example'
  requirements:
    _permission: 'administer site configuration'

entity.example.edit_form:
  path: '/admin/config/system/example/{example}'
  defaults:
    _entity_form: 'example.edit'
    _title: 'Edit example'
  requirements:
    _permission: 'administer site configuration'

entity.example.delete_form:
  path: '/admin/config/system/example/{example}/delete'
  defaults:
    _entity_form: 'example.delete'
    _title: 'Delete example'
  requirements:
    _permission: 'administer site configuration'

example/example.links.menu.yml

This adds a link to the Configuration → System page.

entity.example.collection:
  title: 'Example'
  parent: system.admin_config_system
  description: 'Configure example'
  route_name: entity.example.collection

example/example.links.action.yml

This makes an “Add” link appear on the list page.

entity.example.add_form:
  route_name: 'entity.example.add_form'
  title: 'Add example'
  appears_on:
    - entity.example.collection

Entity Type Classes

example/src/ExampleInterface.php

namespace Drupal\example;

use Drupal\Core\Config\Entity\ConfigEntityInterface;

/**
 * Provides an interface defining an Example entity.
 */
interface ExampleInterface extends ConfigEntityInterface {
  // Add get/set methods for your configuration properties here.
}

example/src/Entity/Example.php

This file defines the configuration entity class.

namespace Drupal\example\Entity;

use Drupal\Core\Config\Entity\ConfigEntityBase;
use Drupal\example\ExampleInterface;

/**
 * Defines the Example entity.
 *
 * @ConfigEntityType(
 *   id = "example",
 *   label = @Translation("Example"),
 *   handlers = {
 *     "list_builder" = "Drupal\example\Controller\ExampleListBuilder",
 *     "form" = {
 *       "add" = "Drupal\example\Form\ExampleForm",
 *       "edit" = "Drupal\example\Form\ExampleForm",
 *       "delete" = "Drupal\example\Form\ExampleDeleteForm",
 *     }
 *   },
 *   config_prefix = "example",
 *   admin_permission = "administer site configuration",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label",
 *   },
 *   config_export = {
 *     "id",
 *     "label"
 *   },
 *   links = {
 *     "edit-form" = "/admin/config/system/example/{example}",
 *     "delete-form" = "/admin/config/system/example/{example}/delete",
 *   }
 * )
 */
class Example extends ConfigEntityBase implements ExampleInterface {

  /**
   * The Example ID.
   *
   * @var string
   */
  public $id;

  /**
   * The Example label.
   *
   * @var string
   */
  public $label;

  // Add your get/set methods for custom configuration properties.
}

The admin_permission key grants access to users with that permission. If more complex logic is needed, a custom access controller can be used.

Starting with Drupal 8.6.x, it is recommended that all configuration entity types include a config_export property in their annotations (see: https://www.drupal.org/node/2949023).

Configuration Schema File

example/config/schema/example.schema.yml

example.example.*:
  type: config_entity
  label: 'Example config'
  mapping:
    id:
      type: string
      label: 'ID'
    label:
      type: label
      label: 'Label'

In example.schema.yml, add the properties/attributes defined in \Drupal\example\Entity\Example

example.example.* references the config variables in our class. To change this, set the config_prefix in the annotation, e.g.:

@ConfigEntityType(
  ...
  config_prefix = "variable_name"

Then reference it like this:

example.variable_name.*:

See Configuration schema/metadata for more information.

Entity Classes

example/src/Form/ExampleForm.php

Defines the add/edit form for the configuration entity.

example/src/Controller/ExampleListBuilder.php

Provides a listing of the configuration entities.

example/src/Form/ExampleDeleteForm.php

Provides a confirmation form for deleting an entity.