Understanding Cockpit - A development guide (work in progress...)

After reading and testing a lot of code, I want to share a few things with you. It’s no secret, that the documentation isn’t up to date. Cockpit is extendible in all directions - sometimes easily and sometimes the structure is hard to understand… so, I tried to visualize it:

Of course, it’s a bit short, but it is a start to understand the basics and possibilities of Cockpit CMS.

@artur Did I miss or misunderstood something fundamentally?

So Cockpit can be used in very different ways. The most common use case is, to use the REST API with another application. I am more interested in having an easy to use and decoupled admin panel. This way I can write my own front-end in PHP, using Cockpit as a library. If I want to switch to other applications or to reuse the same data sets in the future, than I’ll use the API. Call me old-fashioned, but I like to do things server side :wink:

5 Likes

Explanation of all paths and constants

A few weeks ago, I started to analyze all the paths and constants. For most of them I added a few lines of explanation. I will update this list with the missing parts when I find the time to do it.

The example paths are on an Uberspace (CentOS 7) in ~/html/cockpit.


Originally, I wrote this text in kramdown and rendered it to HTML. If you want to see the rendered file with a table of contents, have a look here:


type constants

If no type constant is set to 1, cockpit was called as library.

COCKPIT_ADMIN

[COCKPIT_ADMIN] => 1

  • called index.php
  • triggered admin.init

COCKPIT_CLI

[COCKPIT_CLI] =>

called from cli ./cp ...

COCKPIT_API_REQUEST

[COCKPIT_API_REQUEST] => 0

  • api request
  • called via domain.tld/path/to/cockpit/api/...

other constants

COCKPIT_START_TIME

[COCKPIT_START_TIME] => 1542646468.3189

for debugging: duration time

COCKPIT_ADMIN_ROUTE

[COCKPIT_ADMIN_ROUTE] => /

  • current route, url part after domain.tld/path/to/cockpit
  • e. g. /collections

path constants

COCKPIT_BASE_URL

[COCKPIT_BASE_URL] => /cockpit

  • for COCKPIT_ADMIN_ROUTE detection
  • sets registry: base_url
* What is the difference between `COCKPIT_BASE_URL` and `COCKPIT_BASE_ROUTE`?

COCKPIT_BASE_ROUTE

[COCKPIT_BASE_ROUTE] => /cockpit

  • sets registry: base_route
* What is the difference between `COCKPIT_BASE_URL` and `COCKPIT_BASE_ROUTE`?

COCKPIT_SITE_DIR

[COCKPIT_SITE_DIR] => /var/www/virtual/username

  • parent of root
  • used for relative paths of assets
  • used for relative path of config file in /settings/edit
  • sets registry: site

COCKPIT_DOCS_ROOT

[COCKPIT_DOCS_ROOT] => /var/www/virtual/username/html

  • root
  • used for relative paths of assets
  • part of define COCKPIT_SITE_DIR
  • sets registry: docs_root

COCKPIT_DIR

[COCKPIT_DIR] => /var/www/virtual/username/html/cockpit

to do

COCKPIT_CONFIG_DIR

[COCKPIT_CONFIG_DIR] => /var/www/virtual/username/html/cockpit/config

  • location of config dir
  • sets paths: #config

COCKPIT_CONFIG_PATH

[COCKPIT_CONFIG_PATH] => /var/www/virtual/username/html/cockpit/config/config.yaml

can be COCKPIT_CONFIG_DIR/*.php of COCKPIT_CONFIG_DIR/*.yaml

COCKPIT_STORAGE_FOLDER

[COCKPIT_STORAGE_FOLDER] => /var/www/virtual/username/html/cockpit/storage

  • sets paths: #storage
  • sets paths: #data
  • sets paths: #cache
  • sets paths: #tmp
  • also used in install script for writable check

COCKPIT_PUBLIC_STORAGE_FOLDER

[COCKPIT_PUBLIC_STORAGE_FOLDER] => /var/www/virtual/username/html/cockpit/storage

  • sets paths: #pstorage
  • sets paths: #thumbs
  • sets paths: #uploads

registry

route

[route] => /

see COCKPIT_ADMIN_ROUTE

base_url

[base_url] => /cockpit

to do
  • used in
    • App
      • baseUrl($path)
        • calls: pathToUrl($path)
        • called from: base($path)
    • LimeExtra
      • @base()

base_route

[base_route] => /cockpit

  • used in
    • App
      • routeUrl($path)
        • route()
        • reroute($path)
    • LimeExtra
      • @route()

docs_root

[docs_root] => /var/www/virtual/username/html

  • used in
    • App
      • pathToUrl($path, $full = false)
        • assets($src, $version=false)
          • style($href, $version=false)
          • script($href, $version=false)
        • baseUrl($path)
          • base($path)
    • LimeExtra
      • @base()
      • @assets()
      • @url()
      • ``

other

[site_url] => https://username.uber.space
[base_host] => username.uber.space
[base_port] => 443

paths

to do...

[#root] => /var/www/virtual/username/html/cockpit
[#storage] => /var/www/virtual/username/html/cockpit/storage
[#pstorage] => /var/www/virtual/username/html/cockpit/storage
[#data] => /var/www/virtual/username/html/cockpit/storage/data
[#cache] => /var/www/virtual/username/html/cockpit/storage/cache
[#tmp] => /var/www/virtual/username/html/cockpit/storage/tmp
[#thumbs] => /var/www/virtual/username/html/cockpit/storage/thumbs
[#uploads] => /var/www/virtual/username/html/cockpit/storage/uploads
[#modules] => /var/www/virtual/username/html/cockpit/modules
[#addons] => /var/www/virtual/username/html/cockpit/addons
[#config] => /var/www/virtual/username/html/cockpit/config
[assets] => /var/www/virtual/username/html/cockpit/assets
[site] => /var/www/virtual/username

3 Likes

Awesome work @raffaelj :+1:. One additional thing that can be mentioned maybe is the event system :thinking:

And here is the slightly more complex version with the controller and the event system:

2 Likes