Skeleton Application

Description

Skeleton is an application template. You can use it to kickstart development, see Creating Your First Module.
It is also an educational example, trying to keep up with the framework's most recent best practices. Comments are decidedly wordy.

Usage

Skeleton does not provide any end user value. It does generate a DB schema, a portal block and a preference setting, but none of it implements any particular feature.
The list shown in the only UI screen is generated from a mock array.

Bugs

List any tickets on http://bugs.horde.org/ that cover this issue or are relevant to it.

People

Ralf Lang for the H6 upgrade
Jan Schneider and Chuck Hagenbuch for the original content.

Resources

Include links to protocol descriptions, specifications, RFCs, external applications, presentations on http://horde.org/papers/ or elsewhere that are relevant, articles, API docs from http://dev.horde.org/ - anything that might be useful to someone working on this.

• https://github.com/maintaina-com/skeleton/ Refactored POC version of skeleton. Needs recent versions of horde/core, horde/horde-installer-plugin and horde/horde-deployment.

UPGRADING

As skeleton is not designed to be of any use, this section describes evolution of best practice as it becomes available. These MAY also be applied to other applications as time permits and is feasible.

Because skeleton is also used as a clone template, the version history should not be spammed with entries reflecting the changes.

Registry Snippet

A registry snippet has been placed in doc/registry.d/ - this prevents skeleton from showing up as a button with no text when installed. The snippet is automatically picked up by the horde-installer-plugin and copied to the var/config/horde/registry.d dir unless a file already exists. This is symlinked to web/horde/config/registry.d for BC reasons.

Routes/Controllers: No more list.php and index.php

The list.php UI page has been moved to the routes/controller framework. TODO link to a more detailed article on that framework feature.
The index.php is no longer needed. With a sufficiently recent version of the horde/horde-deployment (2021-11-27 and beyond), there is a rewrite rule that forwards missing directory indexes to the routes/controller framework. A default route catches all links which are not handled by other routes or files

Constructor injection replaces globals

These globals are avoided:

• $notification: replaced by constructor injection. Requires sufficiently recent horde/core (2021-11-27 and beyond)
• $registry: Replaced by constructor injection
• $page_output: Replaced by constructor injection
• $session: Replaced by constructor injection

Usage of injector (DIC) in controllers

The injector is now offered by constructor injection. We pass the namespaced version, not the unnamespaced wrapper. The $injector global should not be used.
The injector SHOULD not need to be passed to controllers at all but there is too much horde code out there that gets and uses the injector as a replacement for missing factories, catalogs, service locators etc. Plans are to keep the injector in the signature but replace it with a wrapper that logs any uses of getInstance as debug messages. People need time to adopt.

src/ code removes underscores for most non-publics

Traditional code uses the PEAR convention, prepending names with underscores:

• for private and protected properties
• for private and protected function names
• for technically public code which is implementation specific

These underscores have been removed unless

• there is a name clash with another method
• a protected variable or method needs to stay compatible with parent or child code which cannot currently be refactored

lib/ code removed

Original code in has been removed. As applications are not inherited from or used like libraries, this should not be a problem but you need a recent enough framework version. For horde/core before 3.0.0alpha9 and horde/horde before 6.0.0alpha6, you may need to add wrappers for integration points:

• lib/Application.php - Used for inter-app and DAV calls. Also contains fallback definition of the SKELETON_BASE and HORDE_BASE constants, though most likely not needed anymore
• lib/Api.php - Used for inter-app and RPC. In real world applications, we might see some breakage if we actually use the API, as calling code may be liberal with typing. In the case of skeleton, the Api is empty anyway.
• lib/Ajax/Application.php - Integration point for the AJAX framework.
• lib/Test.php - The integration point for the health check UI called under /horde/test.php. Though skeleton does not really implement any useful test

With Portal Blocks, there is a little issue: If you add wrappers and run a recent framework, blocks will show up twice. If you do not add wrappers and run an old framework, blocks will not show up. Advise is to not wrap blocks though. See also: https://www.ralf-lang.de/2021/12/01/horde-skeleton-modernized/

Strict types applied and type hints turned to real types

The strict typing mode is used consistently everywhere in src/.
Most property, parameter and return type hints were turned into actual types. Many missing types were added.

Exceptions:

• We know of calling code which does not (yet) behave
• Union types, Stringable etc are PHP 8 only but we currently target php 7.4 compatibility
• Resources

Code moves to PSR-4 with unnamespaced wrappers

The code in src/ started out as a copy of the traditional, unnamespaced code in lib/ and then got namespaced. In some cases, structure and names were change. We want the class name to be useful in its most likely use cases without the namespace prepended. To avoid confusion or name clashes, factory got moved into the namespace of the driver. Horde\Skeleton\Driver\Driver and Horde\Skeleton\Driver\DriverFactory may seem like duplication but consider:

• Inside the Driver namespace, we save on use statements
• When importing a class to other namespaces, we have a useful name

Back to the Project List