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

[raffaelj]

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

[raffaelj]

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:

• source .md, source .html
• view via htmlpreview.github.io

---

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

[artur]

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

[raffaelj]

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